[occt.git] / src / BRepBuilderAPI / BRepBuilderAPI_MakeWire.cdl

-- File:	BRepBuilderAPI_MakeWire.cdl
-- Created:	Thu Jul  8 11:15:02 1993
-- Author:	Remi LEQUETTE
--		<rle@phylox>
---Copyright:	 Matra Datavision 1993


class MakeWire from BRepBuilderAPI inherits MakeShape from BRepBuilderAPI 

	---Purpose: Describes functions to build wires from edges. A wire can
    	-- be built from any number of edges.
    	-- To build a wire you first initialize the construction, then
    	-- add edges in sequence. An unlimited number of edges
    	-- can be added. The initialization of construction is done with:
    	-- -   no edge (an empty wire), or
    	-- -   edges of an existing wire, or
    	-- -   up to four connectable edges.
    	-- In order to be added to a wire under construction, an
    	-- edge (unless it is the first one) must satisfy the following
    	-- condition: one of its vertices must be geometrically
    	-- coincident with one of the vertices of the wire (provided
    	-- that the highest tolerance factor is assigned to the two
    	-- vertices). It could also be the same vertex.
    	-- -   The given edge is shared by the wire if it contains:
    	--   -   two vertices, identical to two vertices of the wire
    	--    under construction (a general case of the wire closure), or
    	--   -   one vertex, identical to a vertex of the wire under
    	--    construction; the other vertex not being
    	--    geometrically coincident with another vertex of the wire.
    	-- -   In other cases, when one of the vertices of the edge
    	--   is simply geometrically coincident with a vertex of the
    	--   wire under construction (provided that the highest
    	--   tolerance factor is assigned to the two vertices), the
    	--   given edge is first copied and the coincident vertex is
    	-- replaced in this new edge, by the coincident vertex of the wire.
    	--  Note: it is possible to build non manifold wires using this construction tool.
    	-- A MakeWire object provides a framework for:
    	-- -   initializing the construction of a wire,
    	-- -   adding edges to the wire under construction, and
    	-- -   consulting the result.

uses
    Vertex      from TopoDS,
    Edge        from TopoDS,
    Wire        from TopoDS,
    ListOfShape from TopTools,
    WireError   from BRepBuilderAPI,
    MakeWire    from BRepLib

raises
    NotDone    from StdFail

is

    Create                                              
	---Purpose: Constructs an empty wire framework, to which edges
    	-- are added using the Add function.
    	-- As soon as the wire contains one edge, it can return
    	-- with the use of the function Wire.
    	-- Warning
    	-- The function Error will return
    	-- BRepBuilderAPI_EmptyWire if it is called before at
    	-- least one edge is added to the wire under construction.
    returns MakeWire from BRepBuilderAPI;
    
    ----------------------------------------------
    -- From edges
    ----------------------------------------------

    Create(E : Edge from TopoDS)                        
	---Purpose: Make a Wire from an edge.
	---Level: Public
    returns MakeWire from BRepBuilderAPI;

    Create(E1,E2 : Edge from TopoDS)                    
	---Purpose: Make a Wire from two edges.
	---Level: Public
    returns MakeWire from BRepBuilderAPI;

    Create(E1,E2,E3 : Edge from TopoDS)                 
	---Purpose: Make a Wire from three edges.
	---Level: Public
    returns MakeWire from BRepBuilderAPI;

    Create(E1,E2,E3,E4 : Edge from TopoDS)              
	---Purpose: Make a Wire from four edges.
	---Level: Public
    returns MakeWire from BRepBuilderAPI;
    	---Purpose: Constructs a wire
    	-- -   from the TopoDS_Wire W composed of the edge E, or
    	-- -   from edge E, or
    	-- -   from two edges E1 and E2, or
    	-- -   from three edges E1, E2 and E3, or
    	-- -   from four edges E1, E2, E3 and E4.
    	-- Further edges can be added using the function Add.
    	-- Given edges are added in a sequence. Each of them
    	-- must be connectable to the wire under construction,
    	-- and so must satisfy the following condition (unless it is
    	-- the first edge of the wire): one of its vertices must be
    	-- geometrically coincident with one of the vertices of the
    	-- wire (provided that the highest tolerance factor is
    	-- assigned to the two vertices). It could also be the same vertex.
    	-- Warning
    	-- If an edge is not connectable to the wire under
    	-- construction it is not added. The function Error will
    	-- return BRepBuilderAPI_DisconnectedWire, the
    	-- function IsDone will return false and the function Wire
    	-- will raise an error, until a new connectable edge is added.  
	
    ----------------------------------------------
    -- From wire and edge
    ----------------------------------------------

    Create(W : Wire from TopoDS)                        
	---Purpose: Make a Wire from a Wire. Usefull for adding later.
	---Level: Public
    returns MakeWire from BRepBuilderAPI;

    Create(W : Wire from TopoDS; E : Edge from TopoDS)  
	---Purpose: Add an edge to a wire.
	---Level: Public
    returns MakeWire from BRepBuilderAPI;
	
    ----------------------------------------------
    -- Auxiliary methods
    ----------------------------------------------

    Add(me : in out; E : Edge from TopoDS)
	---Purpose:  Adds the edge E to the wire under construction.
    	-- E must be connectable to the wire under construction, and, unless it
    	-- is the first edge of the wire, must satisfy the following
    	-- condition: one of its vertices must be geometrically coincident
    	-- with one of the vertices of the wire (provided that the highest
    	-- tolerance factor is assigned to the two vertices). It could also
    	-- be the same vertex.
    	-- Warning
    	-- If E is not connectable to the wire under construction it is not
    	-- added. The function Error will return
    	-- BRepBuilderAPI_DisconnectedWire, the function IsDone will return
    	-- false and the function Wire will raise an error, until a new
    	-- connectable edge is added.
    is static;
    
    Add(me : in out; W : Wire from TopoDS)
	---Purpose: Add the edges of <W> to the current wire.
	---Level: Public
    is static;
    
    Add(me : in out; L : ListOfShape from TopTools)
	---Purpose: Adds  the edges of <L>   to the current  wire.  The
	--          edges are not to be consecutive.   But they are to
	--          be  all  connected geometrically or topologically.
	--          If some of them are  not connected the Status give
	--          DisconnectedWire but the "Maker" is Done() and you
	--          can get the  partial result. (ie connected to  the
	--          first edgeof the list <L>)
        is static;
    
    ----------------------------------------------
    -- Results
    ----------------------------------------------

    IsDone(me) returns Boolean
	---Purpose: Returns true if this algorithm contains a valid wire.
    	-- IsDone returns false if:
    	-- -   there are no edges in the wire, or
    	-- -   the last edge which you tried to add was not connectable.
    is redefined;

    Error(me) returns WireError from BRepBuilderAPI
	---Purpose: Returns the construction status
    	-- -   BRepBuilderAPI_WireDone if the wire is built, or
    	-- -   another value of the BRepBuilderAPI_WireError
    	--   enumeration indicating why the construction failed.
    is static;

    Wire(me) returns Wire from TopoDS
	---Purpose: Returns the constructed wire; or the part of the wire
    	-- under construction already built.
    	-- Exceptions StdFail_NotDone if a wire is not built.
    	---C++: return const &
    	---C++: alias "Standard_EXPORT operator TopoDS_Wire() const;"
	 raises
    	NotDone from StdFail
    is static;
    
    Edge(me) returns Edge from TopoDS
	---C++: return const &
    	---Purpose: Returns the last edge added to the wire under construction.
    	-- Warning
    	-- -   This edge can be different from the original one (the
    	--   argument of the function Add, for instance,)
    	-- -   A null edge is returned if there are no edges in the
    	--   wire under construction, or if the last edge which you
    	--   tried to add was not connectable..
	    raises
    	NotDone from StdFail
    is static;
    
    Vertex(me) returns Vertex from TopoDS
	---C++: return const &
    	---Purpose: Returns the last vertex of the last edge added to the
    	-- wire under construction.
    	-- Warning
    	-- A null vertex is returned if there are no edges in the wire
    	-- under construction, or if the last edge which you tried to
    	-- add was not connectableR
    raises
    	NotDone from StdFail
    is static;
     

fields
    myMakeWire : MakeWire from BRepLib;

end MakeWire;
Commit	Line	Data
7fd59977	1	-- File: BRepBuilderAPI_MakeWire.cdl
	2	-- Created: Thu Jul 8 11:15:02 1993
	3	-- Author: Remi LEQUETTE
	4	-- <rle@phylox>
	5	---Copyright: Matra Datavision 1993
	6
	7
	8
	9	class MakeWire from BRepBuilderAPI inherits MakeShape from BRepBuilderAPI
	10
	11	---Purpose: Describes functions to build wires from edges. A wire can
	12	-- be built from any number of edges.
	13	-- To build a wire you first initialize the construction, then
	14	-- add edges in sequence. An unlimited number of edges
	15	-- can be added. The initialization of construction is done with:
	16	-- - no edge (an empty wire), or
	17	-- - edges of an existing wire, or
	18	-- - up to four connectable edges.
	19	-- In order to be added to a wire under construction, an
	20	-- edge (unless it is the first one) must satisfy the following
	21	-- condition: one of its vertices must be geometrically
	22	-- coincident with one of the vertices of the wire (provided
	23	-- that the highest tolerance factor is assigned to the two
	24	-- vertices). It could also be the same vertex.
	25	-- - The given edge is shared by the wire if it contains:
	26	-- - two vertices, identical to two vertices of the wire
	27	-- under construction (a general case of the wire closure), or
	28	-- - one vertex, identical to a vertex of the wire under
	29	-- construction; the other vertex not being
	30	-- geometrically coincident with another vertex of the wire.
	31	-- - In other cases, when one of the vertices of the edge
	32	-- is simply geometrically coincident with a vertex of the
	33	-- wire under construction (provided that the highest
	34	-- tolerance factor is assigned to the two vertices), the
	35	-- given edge is first copied and the coincident vertex is
	36	-- replaced in this new edge, by the coincident vertex of the wire.
	37	-- Note: it is possible to build non manifold wires using this construction tool.
	38	-- A MakeWire object provides a framework for:
	39	-- - initializing the construction of a wire,
	40	-- - adding edges to the wire under construction, and
	41	-- - consulting the result.
	42
	43	uses
	44	Vertex from TopoDS,
	45	Edge from TopoDS,
	46	Wire from TopoDS,
	47	ListOfShape from TopTools,
	48	WireError from BRepBuilderAPI,
	49	MakeWire from BRepLib
	50
	51	raises
	52	NotDone from StdFail
	53
	54	is
	55
	56	Create
	57	---Purpose: Constructs an empty wire framework, to which edges
	58	-- are added using the Add function.
	59	-- As soon as the wire contains one edge, it can return
	60	-- with the use of the function Wire.
	61	-- Warning
	62	-- The function Error will return
	63	-- BRepBuilderAPI_EmptyWire if it is called before at
	64	-- least one edge is added to the wire under construction.
65	returns MakeWire from BRepBuilderAPI;
66
67	----------------------------------------------
68	-- From edges
69	----------------------------------------------
70
71	Create(E : Edge from TopoDS)
72	---Purpose: Make a Wire from an edge.
73	---Level: Public
74	returns MakeWire from BRepBuilderAPI;
75
76	Create(E1,E2 : Edge from TopoDS)
77	---Purpose: Make a Wire from two edges.
78	---Level: Public
79	returns MakeWire from BRepBuilderAPI;
80
81	Create(E1,E2,E3 : Edge from TopoDS)
82	---Purpose: Make a Wire from three edges.
83	---Level: Public
84	returns MakeWire from BRepBuilderAPI;
85
86	Create(E1,E2,E3,E4 : Edge from TopoDS)
87	---Purpose: Make a Wire from four edges.
88	---Level: Public
89	returns MakeWire from BRepBuilderAPI;
90	---Purpose: Constructs a wire
91	-- - from the TopoDS_Wire W composed of the edge E, or
92	-- - from edge E, or
93	-- - from two edges E1 and E2, or
94	-- - from three edges E1, E2 and E3, or
95	-- - from four edges E1, E2, E3 and E4.
96	-- Further edges can be added using the function Add.
97	-- Given edges are added in a sequence. Each of them
98	-- must be connectable to the wire under construction,
99	-- and so must satisfy the following condition (unless it is
100	-- the first edge of the wire): one of its vertices must be
101	-- geometrically coincident with one of the vertices of the
102	-- wire (provided that the highest tolerance factor is
103	-- assigned to the two vertices). It could also be the same vertex.
104	-- Warning
105	-- If an edge is not connectable to the wire under
106	-- construction it is not added. The function Error will
107	-- return BRepBuilderAPI_DisconnectedWire, the
108	-- function IsDone will return false and the function Wire
109	-- will raise an error, until a new connectable edge is added.
110
111	----------------------------------------------
112	-- From wire and edge
113	----------------------------------------------
114
115	Create(W : Wire from TopoDS)
116	---Purpose: Make a Wire from a Wire. Usefull for adding later.
117	---Level: Public
118	returns MakeWire from BRepBuilderAPI;
119
120	Create(W : Wire from TopoDS; E : Edge from TopoDS)
121	---Purpose: Add an edge to a wire.
122	---Level: Public
123	returns MakeWire from BRepBuilderAPI;
124
125	----------------------------------------------
126	-- Auxiliary methods
127	----------------------------------------------
128
129	Add(me : in out; E : Edge from TopoDS)
130	---Purpose: Adds the edge E to the wire under construction.
131	-- E must be connectable to the wire under construction, and, unless it
132	-- is the first edge of the wire, must satisfy the following
133	-- condition: one of its vertices must be geometrically coincident
134	-- with one of the vertices of the wire (provided that the highest
135	-- tolerance factor is assigned to the two vertices). It could also
136	-- be the same vertex.
137	-- Warning
138	-- If E is not connectable to the wire under construction it is not
139	-- added. The function Error will return
140	-- BRepBuilderAPI_DisconnectedWire, the function IsDone will return
141	-- false and the function Wire will raise an error, until a new
142	-- connectable edge is added.
143	is static;
144
145	Add(me : in out; W : Wire from TopoDS)
146	---Purpose: Add the edges of <W> to the current wire.
147	---Level: Public
148	is static;
149
150	Add(me : in out; L : ListOfShape from TopTools)
151	---Purpose: Adds the edges of <L> to the current wire. The
152	-- edges are not to be consecutive. But they are to
153	-- be all connected geometrically or topologically.
154	-- If some of them are not connected the Status give
155	-- DisconnectedWire but the "Maker" is Done() and you
156	-- can get the partial result. (ie connected to the
157	-- first edgeof the list <L>)
158	is static;
159
160	----------------------------------------------
161	-- Results
162	----------------------------------------------
163
164	IsDone(me) returns Boolean
165	---Purpose: Returns true if this algorithm contains a valid wire.
166	-- IsDone returns false if:
167	-- - there are no edges in the wire, or
168	-- - the last edge which you tried to add was not connectable.
169	is redefined;
170
171	Error(me) returns WireError from BRepBuilderAPI
172	---Purpose: Returns the construction status
173	-- - BRepBuilderAPI_WireDone if the wire is built, or
174	-- - another value of the BRepBuilderAPI_WireError
175	-- enumeration indicating why the construction failed.
176	is static;
177
178	Wire(me) returns Wire from TopoDS
179	---Purpose: Returns the constructed wire; or the part of the wire
180	-- under construction already built.
181	-- Exceptions StdFail_NotDone if a wire is not built.
182	---C++: return const &
183	---C++: alias "Standard_EXPORT operator TopoDS_Wire() const;"
184	raises
185	NotDone from StdFail
186	is static;
187
188	Edge(me) returns Edge from TopoDS
189	---C++: return const &
190	---Purpose: Returns the last edge added to the wire under construction.
191	-- Warning
192	-- - This edge can be different from the original one (the
193	-- argument of the function Add, for instance,)
194	-- - A null edge is returned if there are no edges in the
195	-- wire under construction, or if the last edge which you
196	-- tried to add was not connectable..
197	raises
198	NotDone from StdFail
199	is static;
200
201	Vertex(me) returns Vertex from TopoDS
202	---C++: return const &
203	---Purpose: Returns the last vertex of the last edge added to the
204	-- wire under construction.
205	-- Warning
206	-- A null vertex is returned if there are no edges in the wire
207	-- under construction, or if the last edge which you tried to
208	-- add was not connectableR
209	raises
210	NotDone from StdFail
211	is static;
212
213
214	fields
215	myMakeWire : MakeWire from BRepLib;
216
217	end MakeWire;