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