78eec0fc0616bf1b185a4c905a6afc8521d3abf6
[occt.git] / src / BRepAlgo / BRepAlgo_Section.cdl
1 -- Created on: 1994-02-18
2 -- Created by: Remi LEQUETTE
3 -- Copyright (c) 1994-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 class Section from BRepAlgo inherits BooleanOperation from BRepAlgo
23
24         ---Purpose: Construction of the section lines between two shapes.
25         -- For this Boolean operation, each face of the first
26         -- shape is intersected by each face of the second
27         -- shape. The resulting intersection edges are brought
28         -- together into a compound object, but not chained or
29         -- grouped into wires.
30         -- Computation of the intersection of two Shapes or Surfaces
31         -- The two parts involved in this Boolean operation may
32         -- be defined from geometric surfaces: the most common
33         -- use is the computation of the planar section of a shape.
34         -- A Section object provides the framework for:
35         -- - defining the shapes to be intersected, and the
36         --   computation options,
37         -- - implementing the construction algorithm, and
38         -- - consulting the result.
39         -- Example : giving two shapes S1,S2 accessing faces,
40         -- let compute the section edges R on S1,S2, 
41         -- performing approximation on new curves,
42         -- performing PCurve on part 1 but not on part 2 :
43         -- Standard_Boolean PerformNow = Standard_False;
44         -- BRepBoolAPI_Section S(S1,S2,PerformNow);
45         -- S.ComputePCurveOn1(Standard_True);
46         -- S.Approximation(Standard_True);
47         -- S.Build();
48         -- TopoDS_Shape R = S.Shape();
49         -- On Null Shapes of geometries, NotDone() is called. 
50
51 uses
52
53  Shape from TopoDS,
54  Surface from Geom,
55  Pln from gp,
56  Curve from Geom2d
57  
58 is
59
60  Create(Sh1,Sh2 : Shape from TopoDS;
61         PerformNow : Boolean = Standard_True)
62  returns Section from BRepAlgo;
63         
64  Create(Sh : Shape from TopoDS; Pl : Pln from gp;
65         PerformNow : Boolean = Standard_True)
66         
67  returns Section from BRepAlgo;
68
69  Create(Sh : Shape from TopoDS; Sf : Surface from Geom;
70         PerformNow : Boolean = Standard_True)
71
72  returns Section from BRepAlgo;
73
74  Create(Sf : Surface from Geom; Sh : Shape from TopoDS;
75          PerformNow : Boolean = Standard_True)
76  
77  returns Section from BRepAlgo;
78
79  Create(Sf1 : Surface from Geom; Sf2 : Surface from Geom;
80         PerformNow : Boolean = Standard_True)
81         ---Purpose: This and the above algorithms construct a framework for computing the section lines of
82         -- - the two shapes Sh1 and Sh2, or
83         -- - the shape Sh and the plane Pl, or
84         -- - the shape Sh and the surface Sf, or
85         -- - the surface Sf and the shape Sh, or
86         -- - the two surfaces Sf1 and Sf2,
87         --   and builds the result if PerformNow equals true, its
88         -- default value. If PerformNow equals false, the
89         -- intersection will be computed later by the function Build.
90         -- The constructed shape will be returned by the
91         -- function Shape. This is a compound object
92         -- composed of edges. These intersection edges may be built:
93         -- - on new intersection lines, or
94         -- - on coincident portions of edges in the two intersected shapes.
95         --   These intersection edges are independent: they
96         -- are not chained or grouped in wires.
97         -- If no intersection edge exists, the result is an empty compound object.
98         -- Note that other objects than TopoDS_Shape
99         -- shapes involved in these syntaxes are converted
100         -- into faces or shells before performing the
101         -- computation of the intersection. A shape resulting
102         -- from this conversion can be retrieved with the
103         -- function Shape1 or Shape2.
104         -- Parametric 2D curves on intersection edges
105         -- No parametric 2D curve (pcurve) is defined for
106         -- each elementary edge of the result. To attach such
107         -- parametric curves to the constructed edges you
108         -- may use a constructor with the PerformNow flag
109         -- equal to false; then you use:
110         -- - the function ComputePCurveOn1 to ask for the
111         --   additional computation of a pcurve in the
112         --   parametric space of the first shape,
113         -- - the function ComputePCurveOn2 to ask for the
114         --   additional computation of a pcurve in the
115         --   parametric space of the second shape,
116         -- - in the end, the function Build to construct the result.
117         --   Note that as a result, pcurves will only be added on
118         -- edges built on new intersection lines.
119         -- Approximation of intersection edges
120         -- The underlying 3D geometry attached to each
121         -- elementary edge of the result is:
122         -- - analytic where possible, provided the
123         --   corresponding geometry corresponds to a type
124         --   of analytic curve defined in the Geom package;
125         --   for example, the intersection of a cylindrical
126         --   shape with a plane gives an ellipse or a circle;
127         -- - or elsewhere, given as a succession of points
128         --   grouped together in a BSpline curve of degree 1.
129         --   If you prefer to have an attached 3D geometry
130         -- which is a BSpline approximation of the computed
131         -- set of points on computed elementary intersection
132         -- edges whose underlying geometry is not analytic,
133         -- you may use a constructor with the PerformNow
134         -- flag equal to false. Then you use:
135         -- - the function Approximation to ask for this
136         --   computation option, and
137         -- - the function Build to construct the result.
138         --   Note that as a result, approximations will only be
139         -- computed on edges built on new intersection lines.
140         -- Example
141         --   You may also combine these computation options.
142         -- In the following example:
143         -- - each elementary edge of the computed
144         --   intersection, built on a new intersection line,
145         --   which does not correspond to an analytic Geom
146         --   curve, will be approximated by a BSpline curve
147         --   whose degree is not greater than 8.
148         -- - each elementary edge built on a new intersection line, will have:
149         --   - a pcurve in the parametric space of the shape S1,
150         --   - no pcurve in the parametric space of the shape S2.
151         --     // TopoDS_Shape S1 = ... , S2 = ... ;
152         -- Standard_Boolean PerformNow = Standard_False;
153         -- BRepAlgo_Section S ( S1, S2, PerformNow );
154         -- S.ComputePCurveOn1 (Standard_True);
155         -- S.Approximation (Standard_True);
156         -- S.Build();
157         -- TopoDS_Shape R = S.Shape();
158     
159  returns Section from BRepAlgo;
160
161  Init1(me : out;S1 : Shape from TopoDS);
162         ---Purpose: Initializes the first part
163  
164  Init1(me : out;Pl : Pln from gp);
165         ---Purpose: Initializes the first part
166  
167  Init1(me : out;Sf : Surface from Geom);
168         ---Purpose: Initializes the first part
169  
170  Init2(me : out;S2 : Shape from TopoDS);
171         ---Purpose: initialize second part
172  
173  Init2(me : out;Pl : Pln from gp);
174         ---Purpose: Initializes the second part
175  
176  Init2(me : out;Sf : Surface from Geom);
177         ---Purpose: This and the above algorithms 
178         --   reinitialize the first and the second parts on which
179         -- this algorithm is going to perform the intersection
180         -- computation. This is done with either: the surface
181         -- Sf, the plane Pl or the shape Sh.
182         -- You use the function Build to construct the result.
183  
184  Approximation(me : out;B : Boolean);
185         ---Purpose: Defines an option for computation of further
186         --- intersections. This computation will be performed by
187         -- the function Build in this framework.
188         -- By default, the underlying 3D geometry attached to
189         -- each elementary edge of the result of a computed intersection is:
190         -- - analytic where possible, provided the
191         --   corresponding geometry corresponds to a type of
192         --   analytic curve defined in the Geom package; for
193         --   example the intersection of a cylindrical shape with
194         --   a plane gives an ellipse or a circle;
195         -- - or elsewhere, given as a succession of points
196         --   grouped together in a BSpline curve of degree 1. If
197         --   Approx equals true, when further computations are
198         --   performed in this framework with the function
199         --   Build, these edges will have an attached 3D
200         --   geometry which is a BSpline approximation of the
201         --  computed set of points.
202         --   Note that as a result, approximations will be computed
203         -- on edges built only on new intersection lines.
204  
205  ComputePCurveOn1(me : out;B : Boolean);
206         ---Level: Public
207         ---Purpose: Indicates if the Pcurve must be (or not) performed on first part. 
208
209  ComputePCurveOn2(me : out;B : Boolean);
210         ---Level: Public
211         ---Purpose: Define options for the computation of further
212         -- intersections which will be performed by the function
213         -- Build in this framework.
214         -- By default, no parametric 2D curve (pcurve) is defined
215         -- for the elementary edges of the result.
216         -- If ComputePCurve1 equals true, further computations
217         -- performed in this framework with the function Build
218         -- will attach an additional pcurve in the parametric
219         -- space of the first shape to the constructed edges.
220         -- If ComputePCurve2 equals true, the additional pcurve
221         -- will be attached to the constructed edges in the
222         -- parametric space of the second shape.
223         -- These two functions may be used together.
224         -- Note that as a result, pcurves will only be added onto
225         -- edges built on new intersection lines.
226  
227  Build(me : in out)
228         ---Purpose:  Performs the computation of the section lines
229         -- between the two parts defined at the time of
230         -- construction of this framework or reinitialized with the
231         -- Init1 and Init2 functions.
232         -- The constructed shape will be returned by the function
233         -- Shape. This is a compound object composed of
234         -- edges. These intersection edges may be built:
235         -- - on new intersection lines, or
236         -- - on coincident portions of edges in the two intersected shapes.
237         --   These intersection edges are independent: they are
238         -- not chained or grouped into wires.
239         -- If no intersection edge exists, the result is an empty compound object.
240         -- The shapes involved in the construction of the section
241         -- lines can be retrieved with the function Shape1 or
242         -- Shape2. Note that other objects than
243         -- TopoDS_Shape shapes given as arguments at the
244         -- construction time of this framework, or to the Init1 or
245         --   Init2 function, are converted into faces or shells
246         -- before performing the computation of the intersection.
247         -- Parametric 2D curves on intersection edges
248         -- No parametric 2D curve (pcurve) is defined for the
249         -- elementary edges of the result. To attach parametric
250         -- curves like this to the constructed edges you have to use:
251         -- - the function ComputePCurveOn1 to ask for the
252         --   additional computation of a pcurve in the
253         --   parametric space of the first shape,
254         -- - the function ComputePCurveOn2 to ask for the
255         --   additional computation of a pcurve in the
256         --   parametric space of the second shape.
257         -- This must be done before calling this function.
258         -- Note that as a result, pcurves are added on edges
259         -- built on new intersection lines only.
260         -- Approximation of intersection edges
261         -- The underlying 3D geometry attached to each
262         -- elementary edge of the result is:
263         -- - analytic where possible provided the corresponding
264         --   geometry corresponds to a type of analytic curve
265         --   defined in the Geom package; for example, the
266         --   intersection of a cylindrical shape with a plane
267         --   gives an ellipse or a circle; or
268         -- - elsewhere, given as a succession of points grouped
269         --   together in a BSpline curve of degree 1.
270         --   If, on computed elementary intersection edges whose
271         -- underlying geometry is not analytic, you prefer to
272         -- have an attached 3D geometry which is a BSpline
273         -- approximation of the computed set of points, you have
274         -- to use the function Approximation to ask for this
275         -- computation option before calling this function.
276         -- You may also have combined these computation
277         -- options: look at the example given above to illustrate
278         -- the use of the constructors.
279  is redefined static;
280
281  HasAncestorFaceOn1(me; E : Shape from TopoDS;
282                         F : out Shape from TopoDS)
283  returns Boolean;
284         ---Purpose:Identifies the ancestor faces of the new
285         -- intersection edge E resulting from the last
286         -- computation performed in this framework, that is,
287         -- the faces of the two original shapes on which the edge E lies:
288         -- - HasAncestorFaceOn1 gives the ancestor face
289         --   in the first shape, and
290         --   These functions return:
291         -- - true if an ancestor face F is found, or
292         -- - false if not.
293         --   An ancestor face is identifiable for the edge E if the
294         -- three following conditions are satisfied:
295         -- - the first part on which this algorithm performed
296         --   its last computation is a shape, that is, it was not
297         --   given as a surface or a plane at the time of
298         --   construction of this algorithm or at a later time by
299         --   the Init1 function,
300         -- - E is one of the elementary edges built by the last
301         --   computation of this section algorithm,
302         -- - the edge E is built on an intersection curve. In
303         --   other words, E is a new edge built on the
304         --   intersection curve, not on edges belonging to the
305         --   intersecting shapes.
306         --   To use these functions properly, you have to test
307         -- the returned Boolean value before using the
308         -- ancestor face: F is significant only if the returned
309         -- Boolean value equals true.
310
311  HasAncestorFaceOn2(me; E : Shape from TopoDS;
312                         F : out Shape from TopoDS)
313  returns Boolean;
314         ---Purpose: Identifies the ancestor faces of the new
315         -- intersection edge E resulting from the last
316         -- computation performed in this framework, that is,
317         -- the faces of the two original shapes on which the edge E lies:
318         -- - HasAncestorFaceOn2 gives the ancestor face in the second shape.
319         --   These functions return:
320         -- - true if an ancestor face F is found, or
321         -- - false if not.
322         --   An ancestor face is identifiable for the edge E if the
323         -- three following conditions are satisfied:
324         -- - the first part on which this algorithm performed
325         --   its last computation is a shape, that is, it was not
326         --   given as a surface or a plane at the time of
327         --   construction of this algorithm or at a later time by
328         --   the Init1 function,
329         -- - E is one of the elementary edges built by the last
330         --   computation of this section algorithm,
331         -- - the edge E is built on an intersection curve. In
332         --   other words, E is a new edge built on the
333         --   intersection curve, not on edges belonging to the
334         --   intersecting shapes.
335         --   To use these functions properly, you have to test
336         -- the returned Boolean value before using the
337         -- ancestor face: F is significant only if the returned
338         -- Boolean value equals true.
339
340  PCurveOn1(me; E : Shape from TopoDS)
341  returns Curve from Geom2d;
342         ---Purpose: Returns the pcurve attached to section edge E, in the
343         -- parametric space of  the first part
344         -- on which this algorithm has previously performed the
345         -- computation of a section.
346         -- Warning
347         -- - No pcurve is attached to an elementary edge of the
348         --   resulting section, and the function returns a null
349         --   handle, unless the function ComputePCurveOn1
350         --   or ComputePCurveOn2 was previously used to
351         --   define this sort of option of computation.
352         -- - A null handle is also returned if the edge E does
353         --   not belong to the last computed intersection, that is,
354         --   if it is not one of the elementary edges of the
355         --   compound object returned by the function Shape.
356
357
358  PCurveOn2(me; E : Shape from TopoDS)
359  returns Curve from Geom2d;
360         ---Purpose: Returns the pcurve attached to section edge E, in the
361         -- parametric space of  the second part
362         -- on which this algorithm has previously performed the
363         -- computation of a section.
364         -- Warning
365         -- - No pcurve is attached to an elementary edge of the
366         --   resulting section, and the function returns a null
367         --   handle, unless the function ComputePCurveOn1
368         --   or ComputePCurveOn2 was previously used to
369         --   define this sort of option of computation.
370         -- - A null handle is also returned if the edge E does
371         --   not belong to the last computed intersection, that is,
372         --   if it is not one of the elementary edges of the
373         --   compound object returned by the function Shape.
374
375  InitParameters(me : out)
376  ---Level: Public
377  ---Level: Private
378  is redefined private;
379  
380 fields
381
382  myS1Changed : Boolean;
383  myS2Changed : Boolean;
384  myApproxChanged : Boolean;
385  myPCurve1Changed : Boolean;
386  myPCurve2Changed : Boolean;
387  myshapeisnull : Boolean;
388
389 end Section;