0024428: Implementation of LGPL license
[occt.git] / src / BRepBuilderAPI / BRepBuilderAPI_MakeFace.cdl
1 -- Created on: 1993-07-12
2 -- Created by: Remi LEQUETTE
3 -- Copyright (c) 1993-1999 Matra Datavision
4 -- Copyright (c) 1999-2014 OPEN CASCADE SAS
5 --
6 -- This file is part of Open CASCADE Technology software library.
7 --
8 -- This library is free software; you can redistribute it and / or modify it
9 -- under the terms of the GNU Lesser General Public version 2.1 as published
10 -- by the Free Software Foundation, with special exception defined in the file
11 -- OCCT_LGPL_EXCEPTION.txt. Consult the file LICENSE_LGPL_21.txt included in OCCT
12 -- distribution for complete text of the license and disclaimer of any warranty.
13 --
14 -- Alternatively, this file may be used under the terms of Open CASCADE
15 -- commercial license or contractual agreement.
16
17 --              xab: 29Nov96  correction de doc
18
19
20 class MakeFace from BRepBuilderAPI inherits MakeShape from BRepBuilderAPI 
21
22         ---Purpose: Provides methods to build faces.
23         --          
24         --          A face may be built :
25         --          
26         --          * From a surface.
27         --          
28         --             - Elementary surface from gp.
29         --             
30         --             - Surface from Geom.
31         --             
32         --          * From a surface and U,V values.
33         --          
34         --          * From a wire.
35         --            
36         --            - Find the surface automatically if possible.
37         --          
38         --          * From a surface and a wire.
39         --          
40         --            - A flag Inside is given, when this flag is True
41         --            the  wire is  oriented to bound a finite area on
42         --            the surface.
43         --          
44         --          * From a face and a wire.
45         --            
46         --            - The new wire is a perforation.
47         
48 uses
49     Pln       from gp,
50     Cylinder  from gp,
51     Cone      from gp,
52     Sphere    from gp,
53     Torus     from gp,
54     Surface   from Geom,
55     Face      from TopoDS,
56     Wire      from TopoDS,
57     FaceError from BRepBuilderAPI,
58     MakeFace  from BRepLib
59     
60 raises
61     NotDone    from StdFail
62
63 is
64
65     Create  
66         ---Purpose: Not done.
67         ---Level: Public
68     returns MakeFace from BRepBuilderAPI;
69     
70     Create(F : Face from TopoDS)  
71         ---Purpose: Load a face. Usefull to add wires.
72         ---Level: Public
73     returns MakeFace from BRepBuilderAPI;
74
75     ----------------------------------------------
76     -- From a surface
77     ----------------------------------------------
78
79     Create(P : Pln from gp)
80         ---Purpose: Make a face from a plane.
81         ---Level: Public
82     returns MakeFace from BRepBuilderAPI;
83
84     Create(C : Cylinder from gp)
85         ---Purpose: Make a face from a cylinder.
86         ---Level: Public
87     returns MakeFace from BRepBuilderAPI;
88
89     Create(C : Cone from gp)
90         ---Purpose: Make a face from a cone.
91         ---Level: Public
92     returns MakeFace from BRepBuilderAPI;
93
94     Create(S : Sphere from gp)
95         ---Purpose: Make a face from a sphere.
96         ---Level: Public
97     returns MakeFace from BRepBuilderAPI;
98
99     Create(C : Torus from gp)
100         ---Purpose: Make a face from a torus.
101         ---Level: Public
102     returns MakeFace from BRepBuilderAPI;
103
104     Create(S : Surface from Geom; TolDegen : Real)
105     ---Purpose: Make a face from a Surface. Accepts tolerance value (TolDegen)
106     -- for resolution of degenerated edges.
107     ---Level: Public
108     returns MakeFace from BRepBuilderAPI;
109
110     ----------------------------------------------
111     -- From a surface and U,V values
112     ----------------------------------------------
113
114     Create(P : Pln from gp; UMin, UMax, VMin, VMax : Real)
115         ---Purpose: Make a face from a plane.
116         ---Level: Public
117     returns MakeFace from BRepBuilderAPI;
118
119     Create(C : Cylinder from gp; UMin, UMax, VMin, VMax : Real)
120         ---Purpose: Make a face from a cylinder.
121         ---Level: Public
122     returns MakeFace from BRepBuilderAPI;
123
124     Create(C : Cone from gp; UMin, UMax, VMin, VMax : Real)
125         ---Purpose: Make a face from a cone.
126         ---Level: Public
127     returns MakeFace from BRepBuilderAPI;
128
129     Create(S : Sphere from gp; UMin, UMax, VMin, VMax : Real)
130         ---Purpose: Make a face from a sphere.
131         ---Level: Public
132     returns MakeFace from BRepBuilderAPI;
133
134     Create(C : Torus from gp; UMin, UMax, VMin, VMax : Real)
135         ---Purpose: Make a face from a torus.
136         ---Level: Public
137     returns MakeFace from BRepBuilderAPI;
138
139     Create(S : Surface from Geom; UMin, UMax, VMin, VMax, TolDegen : Real)
140     ---Purpose: Make a face from a Surface. Accepts tolerance value (TolDegen)
141     --          for resolution of degenerated edges.
142     ---Level: Public
143     returns MakeFace from BRepBuilderAPI;
144
145     ----------------------------------------------
146     -- From a wire
147     ----------------------------------------------
148
149     Create(W         : Wire    from TopoDS;
150            OnlyPlane : Boolean from Standard = Standard_False)
151         ---Purpose: Find a surface from the wire and make a face.
152         --          if <OnlyPlane> is true, the computed surface will be
153         --          a plane. If it is not possible to find a plane, the
154         --          flag NotDone will be set.
155         ---Level: Public
156     returns MakeFace from BRepBuilderAPI;
157
158     ----------------------------------------------
159     -- From a surface and a wire
160     ----------------------------------------------
161
162     Create(P : Pln from gp; W : Wire from TopoDS;
163            Inside : Boolean = Standard_True)
164         ---Purpose: Make a face from a plane and a wire.
165         ---Level: Public
166     returns MakeFace from BRepBuilderAPI;
167
168     Create(C : Cylinder from gp; W : Wire from TopoDS;
169            Inside : Boolean = Standard_True)
170         ---Purpose: Make a face from a cylinder and a wire.
171         ---Level: Public
172     returns MakeFace from BRepBuilderAPI;
173
174     Create(C : Cone from gp; W : Wire from TopoDS;
175            Inside : Boolean = Standard_True)
176         ---Purpose: Make a face from a cone and a wire.
177         ---Level: Public
178     returns MakeFace from BRepBuilderAPI;
179
180     Create(S : Sphere from gp; W : Wire from TopoDS;
181            Inside : Boolean = Standard_True)
182         ---Purpose: Make a face from a sphere and a wire.
183         ---Level: Public
184     returns MakeFace from BRepBuilderAPI;
185
186     Create(C : Torus from gp; W : Wire from TopoDS;
187            Inside : Boolean = Standard_True)
188         ---Purpose: Make a face from a torus and a wire.
189         ---Level: Public
190     returns MakeFace from BRepBuilderAPI;
191
192     Create(S : Surface from Geom; W : Wire from TopoDS;
193            Inside : Boolean = Standard_True)
194         ---Purpose: Make a face from a Surface and a wire.
195         ---Level: Public
196     returns MakeFace from BRepBuilderAPI;
197
198     ----------------------------------------------
199     -- From face and wire.
200     ----------------------------------------------
201
202     Create(F : Face from TopoDS; W : Wire from TopoDS)
203         ---Purpose: Adds the wire <W> in the face <F>
204         ---Level: Public
205     returns MakeFace from BRepBuilderAPI;
206     
207         ---Purpose: A general method to create a face is to give
208         -- -      a surface S as the support (the geometric domain) of the face,
209         -- -      and a wire W to bound it.
210         -- The bounds of the face can also be defined by four parameter values
211         -- umin, umax, vmin, vmax which determine isoparametric limitations on
212         -- the parametric space of the surface. In this way, a patch is
213         -- defined. The parameter values are optional. If they are omitted, the
214         -- natural bounds of the surface are used. A wire is automatically
215         -- built using the defined bounds. Up to four edges and four vertices
216         -- are created with this wire (no edge is created when the
217         -- corresponding parameter value is infinite).
218         -- Wires can then be added using the function Add to define other
219         -- restrictions on the face. These restrictions represent holes. More
220         -- than one wire may be added by this way, provided that the wires do
221         -- not cross each other and that they define only one area on the
222         -- surface. (Be careful, however, as this is not checked).
223         --  Forbidden addition of wires
224         -- Note that in this schema, the third case is valid if edges of the
225         -- wire W are declared internal to the face. As a result, these edges
226         -- are no longer bounds of the face.
227         -- A default tolerance (Precision::Confusion()) is given to the face,
228         -- this tolerance may be increased during construction of the face
229         -- using various algorithms.
230         -- Rules applied to the arguments
231         -- For the surface:
232         -- -      The surface must not be a 'null handle'.
233         -- -      If the surface is a trimmed surface, the basis surface is used.
234         -- -      For the wire: the wire is composed of connected edges, each
235         --    edge having a parametric curve description in the parametric
236         --    domain of the surface; in other words, as a pcurve.
237         -- For the parameters:
238         -- -      The parameter values must be in the parametric range of the
239         --    surface (or the basis surface, if the surface is trimmed). If this
240         --    condition is not satisfied, the face is not built, and the Error
241         --    function will return BRepBuilderAPI_ParametersOutOfRange.
242         -- -      The bounding parameters p1 and p2 are adjusted on a periodic
243         --    surface in a given parametric direction by adding or subtracting
244         --    the period to obtain p1 in the parametric range of the surface and
245         --    such p2, that p2 - p1 <= Period, where Period is the period of the
246         --    surface in this parametric direction.
247         -- -      A parameter value may be infinite. There will be no edge and
248         --    no vertex in the corresponding direction.
249        
250
251     Init(me : in out; F : Face from TopoDS)
252         ---Purpose:  Initializes (or reinitializes) the
253         -- construction of a face by creating a new object which is a copy of
254         -- the face F, in order to add wires to it, using the function Add.
255         -- Note: this complete copy of the geometry is only required if you
256         -- want to work on the geometries of the two faces independently.
257     is static;
258
259     Init(me : in out; S : Surface from Geom; Bound : Boolean; TolDegen : Real)
260     ---Purpose: Initializes (or reinitializes) the construction of a face on
261     -- the surface S. If Bound is true, a wire is
262     -- automatically created from the natural bounds of the
263     -- surface S and added to the face in order to bound it. If
264     -- Bound is false, no wire is added. This option is used
265     -- when real bounds are known. These will be added to
266     -- the face after this initialization, using the function Add.
267     -- TolDegen parameter is used for resolution of degenerated edges
268     -- if calculation of natural bounds is turned on.
269     is static;
270
271     Init(me : in out; S : Surface from Geom; UMin, UMax, VMin, VMax, TolDegen : Real) 
272     ---Purpose:  Initializes (or reinitializes) the construction of a face on
273     -- the surface S, limited in the u parametric direction by
274     -- the two parameter values UMin and UMax and in the
275     -- v parametric direction by the two parameter values VMin and VMax.
276     -- Warning
277     --  Error returns:
278     -- -      BRepBuilderAPI_ParametersOutOfRange
279     --    when the parameters given are outside the bounds of the
280     --    surface or the basis surface of a trimmed surface.
281     -- TolDegen parameter is used for resolution of degenerated edges.
282     is static;
283
284     Add(me : in out; W : Wire from TopoDS)
285         ---Purpose: Adds the wire W to the constructed face as a hole.
286         -- Warning
287         -- W must not cross the other bounds of the face, and all
288         -- the bounds must define only one area on the surface.
289         -- (Be careful, however, as this is not checked.)
290         -- Example
291         -- // a cylinder
292         --    gp_Cylinder C = ..;
293         -- // a wire
294         -- TopoDS_Wire W = ...;
295         -- BRepBuilderAPI_MakeFace MF(C);
296         -- MF.Add(W);
297         -- TopoDS_Face F = MF;
298     is static;
299
300
301     ----------------------------------------------
302     -- Results
303     ----------------------------------------------
304
305     IsDone(me) returns Boolean
306         ---Purpose: Returns true if this algorithm has a valid face.
307     is redefined;
308
309     Error(me) returns FaceError from BRepBuilderAPI
310         ---Purpose: Returns the construction status
311         --   BRepBuilderAPI_FaceDone if the face is built, or
312         -- -   another value of the BRepBuilderAPI_FaceError
313         --   enumeration indicating why the construction failed, in
314         --   particular when the given parameters are outside the
315         --   bounds of the surface.
316     is static;
317
318     Face(me) returns Face from TopoDS
319         ---C++: return const &
320         ---C++: alias "Standard_EXPORT operator TopoDS_Face() const;"
321         ---Purpose: Returns the constructed face.
322         -- Exceptions
323         -- StdFail_NotDone if no face is built.
324     raises 
325         NotDone from StdFail
326     is static;
327     
328 fields
329     myMakeFace : MakeFace from BRepLib;
330
331 end MakeFace;