0023024: Update headers of OCCT files
[occt.git] / src / BRepBuilderAPI / BRepBuilderAPI_MakeEdge.cdl
1 -- Created on: 1993-07-06
2 -- Created by: Remi LEQUETTE
3 -- Copyright (c) 1993-1999 Matra Datavision
4 -- Copyright (c) 1999-2012 OPEN CASCADE SAS
5 --
6 -- The content of this file is subject to the Open CASCADE Technology Public
7 -- License Version 6.5 (the "License"). You may not use the content of this file
8 -- except in compliance with the License. Please obtain a copy of the License
9 -- at http://www.opencascade.org and read it completely before using this file.
10 --
11 -- The Initial Developer of the Original Code is Open CASCADE S.A.S., having its
12 -- main offices at: 1, place des Freres Montgolfier, 78280 Guyancourt, France.
13 --
14 -- The Original Code and all software distributed under the License is
15 -- distributed on an "AS IS" basis, without warranty of any kind, and the
16 -- Initial Developer hereby disclaims all such warranties, including without
17 -- limitation, any warranties of merchantability, fitness for a particular
18 -- purpose or non-infringement. Please see the License for the specific terms
19 -- and conditions governing the rights and limitations under the License.
20
21
22
23
24 class MakeEdge from BRepBuilderAPI  inherits MakeShape from BRepBuilderAPI
25
26         ---Purpose: Provides methods to build edges.
27         --          
28         --          The   methods have  the  following   syntax, where
29         --          TheCurve is one of Lin, Circ, ...
30         --          
31         --          Create(C : TheCurve)
32         --            
33         --            Makes an edge on  the whole curve.  Add vertices
34         --            on finite curves.
35         --            
36         --          Create(C : TheCurve; p1,p2 : Real)
37         --          
38         --            Make an edge  on the curve between parameters p1
39         --            and p2. if p2 < p1 the edge will be REVERSED. If
40         --            p1  or p2 is infinite the  curve will be open in
41         --            that  direction. Vertices are created for finite
42         --            values of p1 and p2.
43         --            
44         --          Create(C : TheCurve; P1, P2 : Pnt from gp)
45         --          
46         --            Make an edge on the curve  between the points P1
47         --            and P2. The  points are projected on   the curve
48         --            and the   previous method is  used. An  error is
49         --            raised if the points are not on the curve.
50         --            
51         --          Create(C : TheCurve; V1, V2 : Vertex from TopoDS)
52         --          
53         --            Make an edge  on the curve  between the vertices
54         --            V1 and V2. Same as the  previous but no vertices
55         --            are created. If a vertex is  Null the curve will
56         --            be open in this direction.
57
58 uses
59     EdgeError from BRepBuilderAPI,
60     Edge      from TopoDS,
61     Vertex    from TopoDS,
62     Pnt       from gp,
63     Lin       from gp,
64     Circ      from gp,
65     Elips     from gp,
66     Hypr      from gp,
67     Parab     from gp,
68     Curve     from Geom2d,
69     Curve     from Geom,
70     Surface   from Geom,
71     MakeEdge  from BRepLib
72     
73 raises
74     NotDone from StdFail
75     
76 is
77
78     Create returns MakeEdge from BRepBuilderAPI;
79
80     ----------------------------------------
81     -- Points
82     ----------------------------------------
83
84     Create(V1, V2 : Vertex from TopoDS)                    
85         ---Level: Public
86     returns MakeEdge from BRepBuilderAPI;
87
88     Create(P1, P2 : Pnt from gp)                           
89         ---Level: Public
90     returns MakeEdge from BRepBuilderAPI;
91
92
93     ----------------------------------------
94     -- Lin
95     ----------------------------------------
96         
97     Create(L : Lin from gp)                                
98         ---Level: Public
99     returns MakeEdge from BRepBuilderAPI;
100
101     Create(L : Lin from gp; p1,p2 : Real)                  
102         ---Level: Public
103     returns MakeEdge from BRepBuilderAPI;
104
105     Create(L : Lin from gp; P1,P2 : Pnt from gp)           
106         ---Level: Public
107     returns MakeEdge from BRepBuilderAPI;
108
109     Create(L : Lin from gp; V1, V2 : Vertex from TopoDS)   
110         ---Level: Public
111     returns MakeEdge from BRepBuilderAPI;
112
113     ----------------------------------------
114     -- Circ
115     ----------------------------------------
116         
117     Create(L : Circ from gp)                               
118         ---Level: Public
119     returns MakeEdge from BRepBuilderAPI;
120
121     Create(L : Circ from gp; p1,p2 : Real)                 
122         ---Level: Public
123     returns MakeEdge from BRepBuilderAPI;
124
125     Create(L : Circ from gp; P1,P2 : Pnt from gp)          
126         ---Level: Public
127     returns MakeEdge from BRepBuilderAPI;
128
129     Create(L : Circ from gp; V1, V2 : Vertex from TopoDS)  
130         ---Level: Public
131     returns MakeEdge from BRepBuilderAPI;
132
133         
134     ----------------------------------------
135     -- Elips
136     ----------------------------------------
137
138     Create(L : Elips from gp)                               
139         ---Level: Public
140     returns MakeEdge from BRepBuilderAPI;
141
142     Create(L : Elips from gp; p1,p2 : Real)                 
143         ---Level: Public
144     returns MakeEdge from BRepBuilderAPI;
145
146     Create(L : Elips from gp; P1,P2 : Pnt from gp)          
147         ---Level: Public
148     returns MakeEdge from BRepBuilderAPI;
149
150     Create(L : Elips from gp; V1, V2 : Vertex from TopoDS)  
151         ---Level: Public
152     returns MakeEdge from BRepBuilderAPI;
153
154     ----------------------------------------
155     -- Hypr
156     ----------------------------------------
157
158     Create(L : Hypr from gp)                               
159         ---Level: Public
160     returns MakeEdge from BRepBuilderAPI;
161
162     Create(L : Hypr from gp; p1,p2 : Real)                 
163         ---Level: Public
164     returns MakeEdge from BRepBuilderAPI;
165
166     Create(L : Hypr from gp; P1,P2 : Pnt from gp)          
167         ---Level: Public
168     returns MakeEdge from BRepBuilderAPI;
169
170     Create(L : Hypr from gp; V1, V2 : Vertex from TopoDS)  
171         ---Level: Public
172     returns MakeEdge from BRepBuilderAPI;
173
174     ----------------------------------------
175     -- Parab
176     ----------------------------------------
177
178     Create(L : Parab from gp)                               
179         ---Level: Public
180     returns MakeEdge from BRepBuilderAPI;
181
182     Create(L : Parab from gp; p1,p2 : Real)                 
183         ---Level: Public
184     returns MakeEdge from BRepBuilderAPI;
185
186     Create(L : Parab from gp; P1,P2 : Pnt from gp)          
187         ---Level: Public
188     returns MakeEdge from BRepBuilderAPI;
189
190     Create(L : Parab from gp; V1, V2 : Vertex from TopoDS)  
191         ---Level: Public
192     returns MakeEdge from BRepBuilderAPI;
193
194     ----------------------------------------
195     -- Curve
196     ----------------------------------------
197
198     Create(L : Curve from Geom)                               
199         ---Level: Public
200     returns MakeEdge from BRepBuilderAPI;
201
202     Create(L : Curve from Geom; p1,p2 : Real)                 
203         ---Level: Public
204     returns MakeEdge from BRepBuilderAPI;
205
206     Create(L : Curve from Geom; 
207     P1,P2 : Pnt from gp)
208         ---Level: Public                        
209     returns MakeEdge from BRepBuilderAPI;
210
211     Create(L : Curve from Geom; 
212     V1, V2 : Vertex from TopoDS)
213         ---Level: Public
214     returns MakeEdge from BRepBuilderAPI;
215
216     Create(L : Curve from Geom; 
217     P1,P2 : Pnt from gp; p1,p2 : Real)                        
218         ---Level: Public
219     returns MakeEdge from BRepBuilderAPI;
220
221     Create(L : Curve from Geom; 
222     V1, V2 : Vertex from TopoDS;
223     p1, p2 :Real)       
224         ---Level: Public                                      
225     returns MakeEdge from BRepBuilderAPI;
226
227     ----------------------------------------
228     -- Curve and surface
229     ----------------------------------------
230
231     Create(L : Curve from Geom2d; S : Surface from Geom)
232         ---Level: Public
233     returns MakeEdge from BRepBuilderAPI;
234
235     Create(L : Curve from Geom2d; S : Surface from Geom; p1,p2 : Real)
236         ---Level: Public
237     returns MakeEdge from BRepBuilderAPI;
238
239     Create(L : Curve from Geom2d; S : Surface from Geom; 
240     P1,P2 : Pnt from gp)
241         ---Level: Public                        
242     returns MakeEdge from BRepBuilderAPI;
243
244     Create(L : Curve from Geom2d; S : Surface from Geom; 
245     V1, V2 : Vertex from TopoDS)
246         ---Level: Public
247     returns MakeEdge from BRepBuilderAPI;
248
249     Create(L : Curve from Geom2d; S : Surface from Geom; 
250     P1,P2 : Pnt from gp; p1,p2 : Real)                        
251         ---Level: Public
252     returns MakeEdge from BRepBuilderAPI;
253
254     Create(L : Curve from Geom2d; S : Surface from Geom; 
255     V1, V2 : Vertex from TopoDS;
256     p1, p2 :Real)       
257         ---Level: Public                                      
258     returns MakeEdge from BRepBuilderAPI;
259
260  
261         ---Purpose: The general method to directly create an edge is to give
262         -- -      a 3D curve C as the support (geometric domain) of the edge,
263         -- -      two vertices V1 and V2 to limit the curve (definition of the restriction of
264         --    the edge), and
265         -- -      two real values p1 and p2 which are the parameters for the vertices V1 and V2
266         --    on the curve.
267         -- The curve may be defined as a 2d curve in the parametric space of a surface: a
268         -- pcurve. The surface on which the edge is built is then kept at the level of the edge.
269         -- The default tolerance will be associated with this edge.
270         -- Rules applied to the arguments:
271         -- For the curve:
272         -- -      The curve must not be a 'null handle'.
273         -- -      If the curve is a trimmed curve the basis curve is used.
274         -- For the vertices:
275         -- -      Vertices may be null shapes. When V1 or V2 is null the edge is open in the
276         --    corresponding direction and the parameter value p1 or p2 must be infinite
277         --    (remember that Precision::Infinite() defines an infinite value).
278         -- -      The two vertices must be identical if they have the same 3D location.
279         --    Identical vertices are used in particular when the curve is closed.
280         -- For the parameters:
281         -- -      The parameters must be in the parametric range of the curve (or the basis
282         --    curve if the curve is trimmed). If this condition is not satisfied the edge is not
283         --    built, and the Error function will return BRepAPI_ParameterOutOfRange.
284         -- -      Parameter values must not be equal. If this condition is not satisfied (i.e.
285         --    if | p1 - p2 | ) the edge is not built, and the Error function will return
286         --    BRepAPI_LineThroughIdenticPoints.
287         -- Parameter values are expected to be given in increasing order:
288         --      C->FirstParameter() 
289         -- - If the parameter values are given in decreasing order the vertices are switched,
290         -- i.e. the "first vertex" is on the point of parameter p2 and the "second vertex" is
291         -- on the point of parameter p1. In such a case, to keep the original intent of the
292         -- construction, the edge will be oriented "reversed".
293         -- - On a periodic curve the parameter values p1 and p2 are adjusted by adding or
294         -- subtracting the period to obtain p1 in the parametric range of the curve, and p2]
295         -- such that [ p1 , where Period is the period of the curve.
296         -- - A parameter value may be infinite. The edge is open in the corresponding
297         -- direction. However the corresponding vertex must be a null shape. If this condition
298         -- is not satisfied the edge is not built, and the Error function will return
299         -- BRepAPI_PointWithInfiniteParameter.
300         -- - The distance between the vertex and the point evaluated on the curve with the
301         -- parameter, must be lower than the precision of the vertex. If this condition is not
302         -- satisfied the edge is not built, and the Error function will return
303         -- BRepAPI_DifferentsPointAndParameter.
304         --  Other edge constructions
305         -- - The parameter values can be omitted, they will be computed by projecting the
306         -- vertices on the curve. Note that projection is the only way to evaluate the
307         -- parameter values of the vertices on the curve: vertices must be given on the curve,
308         -- i.e. the distance from a vertex to the curve must be less than or equal to the
309         -- precision of the vertex. If this condition is not satisfied the edge is not built,
310         -- and the Error function will return BRepAPI_PointProjectionFailed.
311         -- -      3D points can be given in place of vertices. Vertices will be created from the
312         --    points (with the default topological precision Precision::Confusion()). 
313         -- Note:
314         -- -      Giving vertices is useful when creating a connected edge.
315         -- -      If the parameter values correspond to the extremities of a closed curve,
316         --    points must be identical, or at least coincident. If this condition is not
317         --    satisfied the edge is not built, and the Error function will return
318         --   BRepAPI_DifferentPointsOnClosedCurve.
319         -- -      The vertices or points can be omitted if the parameter values are given. The
320         --    points will be computed from the parameters on the curve.
321         -- The vertices or points and the parameter values can be omitted. The first and last
322         --   parameters of the curve will then be used.   
323         ----------------------------------------
324     --  Auxiliary methods
325     ----------------------------------------
326
327     Init(me : in out; C      : Curve from Geom)
328         ---Level: Public
329     is static;
330     
331     Init(me : in out; C      : Curve from Geom;
332                       p1, p2 : Real)
333         ---Level: Public
334     is static;                
335         
336     Init(me : in out; C      : Curve from Geom;
337                       P1, P2 : Pnt   from gp)
338         ---Level: Public
339     is static;                
340         
341     Init(me : in out; C      : Curve  from Geom;
342                       V1, V2 : Vertex from TopoDS)
343         ---Level: Public
344     is static;
345         
346     Init(me : in out; C      : Curve from Geom;
347                       P1, P2 : Pnt   from gp;
348                       p1, p2 : Real)
349         ---Level: Public
350     is static;                
351         
352     Init(me : in out; C      : Curve  from Geom;
353                       V1, V2 : Vertex from TopoDS;
354                       p1, p2 : Real)
355         ---Level: Public
356     is static;
357         
358     Init(me : in out; C      : Curve from Geom2d; S : Surface from Geom)
359         ---Level: Public
360     is static;
361     
362     Init(me : in out; C      : Curve from Geom2d; S : Surface from Geom;
363                       p1, p2 : Real)
364         ---Level: Public
365     is static;                
366         
367     Init(me : in out; C      : Curve from Geom2d; S : Surface from Geom;
368                       P1, P2 : Pnt   from gp)
369         ---Level: Public
370     is static;                
371         
372     Init(me : in out; C      : Curve  from Geom2d; S : Surface from Geom;
373                       V1, V2 : Vertex from TopoDS)
374         ---Level: Public
375     is static;
376         
377     Init(me : in out; C      : Curve from Geom2d; S : Surface from Geom;
378                       P1, P2 : Pnt   from gp;
379                       p1, p2 : Real)
380         ---Level: Public
381     is static;                
382         
383     Init(me : in out; C      : Curve  from Geom2d; S : Surface from Geom;
384                       V1, V2 : Vertex from TopoDS;
385                       p1, p2 : Real)
386         ---Level: Public
387     is static;
388         ---Purpose: Defines or redefines the arguments for the construction of an edge.
389         -- This function is currently used after the empty constructor BRepAPI_MakeEdge().      
390
391     ----------------------------------------
392     --  Results
393     ----------------------------------------
394
395     IsDone(me) returns Boolean
396         ---Purpose: Returns true if the edge is built.
397     is redefined;
398
399     Error(me) returns EdgeError from BRepBuilderAPI
400         ---Purpose: Returns the construction status
401         -- -   BRepBuilderAPI_EdgeDone if the edge is built, or
402         -- -   another value of the BRepBuilderAPI_EdgeError
403         --   enumeration indicating the reason of construction failure.
404     is static;
405
406     Edge(me) returns Edge from TopoDS
407         ---C++: return const &
408         ---C++: alias "Standard_EXPORT operator TopoDS_Edge() const;"
409         --- Purpose:
410         -- Returns the constructed edge.
411         -- Exceptions StdFail_NotDone if the edge is not built.
412     raises
413         NotDone from StdFail
414     is static;
415     
416     Vertex1(me) returns Vertex from TopoDS
417         ---Purpose: Returns the first vertex of the edge. May be Null.
418         --          
419         ---C++: return const &
420         ---Level: Public
421     is static;
422     
423     Vertex2(me) returns Vertex from TopoDS
424                 ---C++: return const &
425         ---Purpose: Returns the second vertex of the edge. May be Null.
426         --          
427         -- Warning
428         -- The returned vertex in each function corresponds respectively to
429         -- -   the lowest, or
430         -- -   the highest parameter on the curve along which the edge is built.
431         --  It does not correspond to the first or second vertex
432         -- given at the time of the construction, if the edge is oriented reversed.
433         -- Exceptions
434         -- StdFail_NotDone if the edge is not built.
435     is static; 
436     
437 fields
438
439     myMakeEdge : MakeEdge  from BRepLib;
440
441 end MakeEdge;