0029311: Implementation of the Oriented Bounding Boxes (OBB) functionality
[occt.git] / dox / user_guides / modeling_data / modeling_data.md
CommitLineData
ba06f8bb 1Modeling Data {#occt_user_guides__modeling_data}
72b7576f 2========================
3
e5bd0d98 4@tableofcontents
5
ba06f8bb 6@section occt_modat_0 Introduction
72b7576f 7
e2b55410 8Modeling Data supplies data structures to represent 2D and 3D geometric models.
9
e2ba9cb1 10This manual explains how to use Modeling Data. For advanced information on modeling data, see our <a href="http://www.opencascade.com/content/tutorial-learning">E-learning & Training</a> offerings.
72b7576f 11
72b7576f 12@section occt_modat_1 Geometry Utilities
13
14Geometry Utilities provide the following services:
15 * Creation of shapes by interpolation and approximation
16 * Direct construction of shapes
e2b55410 17 * Conversion of curves and surfaces to BSpline curves and surfaces
72b7576f 18 * Computation of the coordinates of points on 2D and 3D curves
19 * Calculation of extrema between shapes.
20
21@subsection occt_modat_1_1 Interpolations and Approximations
22
e2b55410 23In modeling, it is often required to approximate or interpolate points into curves and surfaces. In interpolation, the process is complete when the curve or surface passes through all the points; in approximation, when it is as close to these points as possible.
24
25Approximation of Curves and Surfaces groups together a variety of functions used in 2D and 3D geometry for:
26 * the interpolation of a set of 2D points using a 2D BSpline or Bezier curve;
27 * the approximation of a set of 2D points using a 2D BSpline or Bezier curve;
28 * the interpolation of a set of 3D points using a 3D BSpline or Bezier curve, or a BSpline surface;
29 * the approximation of a set of 3D points using a 3D BSpline or Bezier curve, or a BSpline surface.
30
31You can program approximations in two ways:
32
33 * Using high-level functions, designed to provide a simple method for obtaining approximations with minimal programming,
34 * Using low-level functions, designed for users requiring more control over the approximations.
72b7576f 35
36@subsubsection occt_modat_1_1_1 Analysis of a set of points
37
e2b55410 38The class *PEquation* from *GProp* package allows analyzing a collection or cloud of points and verifying if they are coincident, collinear or coplanar within a given precision. If they are, the algorithm computes the mean point, the mean line or the mean plane of the points. If they are not, the algorithm computes the minimal box, which includes all the points.
72b7576f 39
40@subsubsection occt_modat_1_1_2 Basic Interpolation and Approximation
41
42Packages *Geom2dAPI* and *GeomAPI* provide simple methods for approximation and interpolation with minimal programming
43
dba69de2 44#### 2D Interpolation
45
72b7576f 46The class *Interpolate* from *Geom2dAPI* package allows building a constrained 2D BSpline curve, defined by a table of points through which the curve passes. If required, the parameter values and vectors of the tangents can be given for each point in the table.
47
dba69de2 48#### 3D Interpolation
49
72b7576f 50The class *Interpolate* from *GeomAPI* package allows building a constrained 3D BSpline curve, defined by a table of points through which the curve passes. If required, the parameter values and vectors of the tangents can be given for each point in the table.
51
d6b4d3d0 52@figure{/user_guides/modeling_data/images/modeling_data_image003.png,"Approximation of a BSpline from scattered points",420}
72b7576f 53
54This class may be instantiated as follows:
55~~~~~
56GeomAPI_Interpolate Interp(Points);
57~~~~~
58
59From this object, the BSpline curve may be requested as follows:
60~~~~~
61Handle(Geom_BSplineCurve) C = Interp.Curve();
62~~~~~
63
dba69de2 64#### 2D Approximation
65
72b7576f 66The class *PointsToBSpline* from *Geom2dAPI* package allows building a 2DBSpline curve, which approximates a set of points. You have to define the lowest and highest degree of the curve, its continuity and a tolerance value for it.The tolerance value is used to check that points are not too close to each other, or tangential vectors not too small. The resulting BSpline curve will beC2 or second degree continuous, except where a tangency constraint is defined on a point through which the curve passes. In this case, it will be only C1continuous.
67
dba69de2 68#### 3D Approximation
69
72b7576f 70The class *PointsToBSpline* from GeomAPI package allows building a 3D BSplinecurve, which approximates a set of points. It is necessary to define the lowest and highest degree of the curve, its continuity and tolerance. The tolerance value is used to check that points are not too close to each other,or that tangential vectors are not too small.
71
72The resulting BSpline curve will be C2 or second degree continuous, except where a tangency constraint is defined on a point, through which the curve passes. In this case, it will be only C1 continuous. This class is instantiated as follows:
73
74~~~~~
75GeomAPI_PointsToBSpline
76Approx(Points,DegMin,DegMax,Continuity, Tol);
77~~~~~
78
79From this object, the BSpline curve may be requested as follows:
e5bd0d98 80
72b7576f 81~~~~~
82Handle(Geom_BSplineCurve) K = Approx.Curve();
83~~~~~
84
dba69de2 85#### Surface Approximation
86
72b7576f 87The class **PointsToBSplineSurface** from GeomAPI package allows building a BSpline surface, which approximates or interpolates a set of points.
88
89@subsubsection occt_modat_1_1_3 Advanced Approximation
90
91Packages *AppDef* and *AppParCurves* provide low-level functions, allowing more control over the approximations.
92
e2b55410 93The low-level functions provide a second API with functions to:
94 * Define compulsory tangents for an approximation. These tangents have origins and extremities.
95 * Approximate a set of curves in parallel to respect identical parameterization.
96 * Smooth approximations. This is to produce a faired curve.
97
98You can also find functions to compute:
99 * The minimal box which includes a set of points
100 * The mean plane, line or point of a set of coplanar, collinear or coincident points.
101
dba69de2 102#### Approximation by multiple point constraints
103
72b7576f 104*AppDef* package provides low-level tools to allow parallel approximation of groups of points into Bezier or B-Spline curves using multiple point constraints.
105
106The following low level services are provided:
e5bd0d98 107
72b7576f 108* Definition of an array of point constraints:
72b7576f 109
e2b55410 110 The class *MultiLine* allows defining a given number of multi-point constraints in order to build the multi-line, multiple lines passing through ordered multiple point constraints.
e5bd0d98 111
d6b4d3d0 112 @figure{/user_guides/modeling_data/images/modeling_data_image004.png,"Definition of a MultiLine using Multiple Point Constraints",240}
72b7576f 113
e5bd0d98 114 In this image:
115 * *Pi*, *Qi*, *Ri* ... *Si* can be 2D or 3D points.
72b7576f 116 * Defined as a group: *Pn*, *Qn*, *Rn,* ... *Sn* form a MultipointConstraint. They possess the same passage, tangency and curvature constraints.
117 * *P1*, *P2*, ... *Pn*, or the *Q*, *R*, ... or *S* series represent the lines to be approximated.
118
119* Definition of a set of point constraints:
e5bd0d98 120
e2b55410 121 The class *MultiPointConstraint* allows defining a multiple point constraint and computing the approximation of sets of points to several curves.
72b7576f 122
ba06f8bb 123* Computation of an approximation of a Bezier curve from a set of points:
e5bd0d98 124
125 The class *Compute* allows making an approximation of a set of points to a Bezier curve
72b7576f 126
127* Computation of an approximation of a BSpline curve from a set of points:
e5bd0d98 128
e2b55410 129 The class *BSplineCompute* allows making an approximation of a set of points to a BSpline curve.
72b7576f 130
131* Definition of Variational Criteria:
e5bd0d98 132
72b7576f 133The class *TheVariational* allows fairing the approximation curve to a given number of points using a least squares method in conjunction with a variational criterion, usually the weights at each constraint point.
134
dba69de2 135#### Approximation by parametric or geometric constraints
136
72b7576f 137
138*AppParCurves* package provides low-level tools to allow parallel approximation of groups of points into Bezier or B-Spline curve with parametric or geometric constraints, such as a requirement for the curve to pass through given points, or to have a given tangency or curvature at a particular point.
139
140The algorithms used include:
141- the least squares method
142- a search for the best approximation within a given tolerance value.
143
144The following low-level services are provided:
145
146* Association of an index to an object:
e5bd0d98 147
72b7576f 148The class *ConstraintCouple* allows you associating an index to an object to compute faired curves using *AppDef_TheVariational*.
149
150* Definition of a set of approximations of Bezier curves:
e5bd0d98 151
72b7576f 152The class *MultiCurve* allows defining the approximation of a multi-line made up of multiple Bezier curves.
153
154* Definition of a set of approximations of BSpline curves:
e5bd0d98 155
72b7576f 156The class *MultiBSpCurve* allows defining the approximation of a multi-line made up of multiple BSpline curves.
157
158* Definition of points making up a set of point constraints
e5bd0d98 159
72b7576f 160The class *MultiPoint* allows defining groups of 2D or 3D points making up a multi-line.
e2b55410 161
162#### Example: How to approximate a curve with respect to tangency
163
164To approximate a curve with respect to tangency, follow these steps:
165
166 1. Create an object of type <i> AppDef_MultiPointConstraints</i> from the set of points to approximate and use the method <i> SetTang </i>to set the tangency vectors.
167 2. Create an object of type <i> AppDef_MultiLine </i>from the <i> AppDef_MultiPointConstraint</i>.
168 3. Use <i> AppDef_BSplineCompute</i>, which instantiates <i>Approx_BSplineComputeLine</i> to perform the approximation.
72b7576f 169
170@subsection occt_modat_1_2 Direct Construction
171
4ee1bdf4 172Direct Construction methods from *gce*, *GC* and *GCE2d* packages provide simplified algorithms to build elementary geometric entities such as lines, circles and curves. They complement the reference definitions provided by the *gp*, *Geom* and *Geom2d* packages.
72b7576f 173
e2b55410 174The algorithms implemented by <i> gce</i>, <i> GCE2d</i> and <i> GC</i> packages are simple: there is no creation of objects defined by advanced positional constraints (for more information on this subject, see *Geom2dGcc* and *GccAna*, which describe geometry by constraints).
175
72b7576f 176For example, to construct a circle from a point and a radius using the *gp* package, it is necessary to construct axis *Ax2d* before creating the circle. If *gce* package is used, and *Ox* is taken for the axis, it is possible to create a circle directly from a point and a radius.
177
e2b55410 178Another example is the class <i>gce_MakeCirc</i> providing a framework for defining eight problems encountered in the geometric construction of circles and implementing the eight related construction algorithms.
179
180The object created (or implemented) is an algorithm which can be consulted to find out, in particular:
181
182 * its result, which is a <i>gp_Circ</i>, and
183 * its status. Here, the status indicates whether or not the construction was successful.
184
185If it was unsuccessful, the status gives the reason for the failure.
186
187~~~~
188 gp_Pnt P1 (0.,0.,0.);
189 gp_Pnt P2 (0.,10.,0.);
190 gp_Pnt P3 (10.,0.,0.);
191 gce_MakeCirc MC (P1,P2,P3);
192 if (MC.IsDone()) {
193 const gp_Circ& C = MC.Value();
194 }
195~~~~
196
197In addition, <i> gce</i>, <i> GCE2d</i> and <i> GC</i> each have a <i>Root</i> class. This class is the root of all classes in the package, which return a status. The returned status (successful
198construction or construction error) is described by the enumeration <i>gce_ErrorType</i>.
199
200Note, that classes, which construct geometric transformations do not return a status, and therefore do not inherit from *Root*.
201
202
d3013f55 203@subsubsection occt_modat_1_2_1 Simple geometric entities
72b7576f 204
d3013f55 205The following algorithms used to build entities from *gp* package are provided by *gce* package.
72b7576f 206- 2D line parallel to another at a distance,
207- 2D line parallel to another passing through a point,
208- 2D circle passing through two points,
209- 2D circle parallel to another at a distance,
210- 2D circle parallel to another passing through a point,
211- 2D circle passing through three points,
212- 2D circle from a center and a radius,
213- 2D hyperbola from five points,
214- 2D hyperbola from a center and two apexes,
215- 2D ellipse from five points,
216- 2D ellipse from a center and two apexes,
217- 2D parabola from three points,
218- 2D parabola from a center and an apex,
219- line parallel to another passing through a point,
220- line passing through two points,
221- circle coaxial to another passing through a point,
222- circle coaxial to another at a given distance,
223- circle passing through three points,
224- circle with its center, radius, and normal to the plane,
225- circle with its axis (center + normal),
226- hyperbola with its center and two apexes,
227- ellipse with its center and two apexes,
228- plane passing through three points,
229- plane from its normal,
230- plane parallel to another plane at a given distance,
231- plane parallel to another passing through a point,
232- plane from an array of points,
233- cylinder from a given axis and a given radius,
234- cylinder from a circular base,
235- cylinder from three points,
236- cylinder parallel to another cylinder at a given distance,
237- cylinder parallel to another cylinder passing through a point,
238- cone from four points,
239- cone from a given axis and two passing points,
240- cone from two points (an axis) and two radii,
241- cone parallel to another at a given distance,
242- cone parallel to another passing through a point,
243- all transformations (rotations, translations, mirrors,scaling transformations, etc.).
244
245Each class from *gp* package, such as *Circ, Circ2d, Mirror, Mirror2d*, etc., has the corresponding *MakeCirc, MakeCirc2d, MakeMirror, MakeMirror2d*, etc. class from *gce* package.
246
247It is possible to create a point using a *gce* package class, then question it to recover the corresponding *gp* object.
248
72b7576f 249~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.cpp}
250 gp_Pnt2d Point1,Point2;
251 ...
252 //Initialization of Point1 and Point2
253 gce_MakeLin2d L = gce_MakeLin2d(Point1,Point2);
254 if (L.Status() == gce_Done() ){
255 gp_Lin2d l = L.Value();
256 }
257~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
72b7576f 258
dba69de2 259This is useful if you are uncertain as to whether the arguments can create the *gp* object without raising an exception. In the case above, if *Point1* and *Point2* are closer than the tolerance value required by *MakeLin2d*, the function *Status* will return the enumeration *gce_ConfusedPoint*. This tells you why the *gp* object cannot be created. If you know that the points *Point1* and *Point2* are separated by the value exceeding the tolerance value, then you may create the *gp* object directly, as follows:
72b7576f 260
261~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.cpp}
262gp_Lin2d l = gce_MakeLin2d(Point1,Point2);
263~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
264
d3013f55 265@subsubsection occt_modat_1_2_2 Geometric entities manipulated by handle
72b7576f 266
d3013f55 267*GC* and *GCE2d* packages provides an implementation of algorithms used to build entities from *Geom* and *Geom2D* packages.
268They implement the same algorithms as the *gce* package, and also contain algorithms for trimmed surfaces and curves.
269The following algorithms are available:
72b7576f 270- arc of a circle trimmed by two points,
271- arc of a circle trimmed by two parameters,
272- arc of a circle trimmed by one point and one parameter,
273- arc of an ellipse from an ellipse trimmed by two points,
274- arc of an ellipse from an ellipse trimmed by two parameters,
275- arc of an ellipse from an ellipse trimmed by one point and one parameter,
276- arc of a parabola from a parabola trimmed by two points,
277- arc of a parabola from a parabola trimmed by two parameters,
278- arc of a parabola from a parabola trimmed by one point and one parameter,
279- arc of a hyperbola from a hyperbola trimmed by two points,
280- arc of a hyperbola from a hyperbola trimmed by two parameters,
281- arc of a hyperbola from a hyperbola trimmed by one point and one parameter,
282- segment of a line from two points,
283- segment of a line from two parameters,
284- segment of a line from one point and one parameter,
285- trimmed cylinder from a circular base and a height,
286- trimmed cylinder from three points,
287- trimmed cylinder from an axis, a radius, and a height,
288- trimmed cone from four points,
289- trimmed cone from two points (an axis) and a radius,
290- trimmed cone from two coaxial circles.
291
292Each class from *GCE2d* package, such as *Circle, Ellipse, Mirror*, etc., has the corresponding *MakeCircle, MakeEllipse, MakeMirror*, etc. class from *Geom2d* package.
293Besides, the class *MakeArcOfCircle* returns an object of type *TrimmedCurve* from *Geom2d*.
294
295Each class from *GC* package, such as *Circle, Ellipse, Mirror*, etc., has the corresponding *MakeCircle, MakeEllipse, MakeMirror*, etc. class from *Geom* package.
296The following classes return objects of type *TrimmedCurve* from *Geom*:
297- *MakeArcOfCircle*
298- *MakeArcOfEllipse*
299- *MakeArcOfHyperbola*
300- *MakeArcOfParabola*
301- *MakeSegment*
302
303@subsection occt_modat_1_3 Conversion to and from BSplines
304
e2b55410 305The Conversion to and from BSplines component has two distinct purposes:
306 * Firstly, it provides a homogeneous formulation which can be used to describe any curve or surface.
307 This is useful for writing algorithms for a single data structure model.
308 The BSpline formulation can be used to represent most basic geometric objects provided
309 by the components which describe geometric data structures ("Fundamental Geometry Types", "2D Geometry Types" and "3D Geometry Types" components).
310 * Secondly, it can be used to divide a BSpline curve or surface into a series of curves or surfaces,
311 thereby providing a higher degree of continuity. This is useful for writing algorithms
312 which require a specific degree of continuity in the objects to which they are applied.
313 Discontinuities are situated on the boundaries of objects only.
314
315The "Conversion to and from BSplines" component is composed of three packages.
316
317The <i> Convert </i> package provides algorithms to convert the following into a BSpline curve or surface:
318
319 * a bounded curve based on an elementary 2D curve (line, circle or conic) from the <i> gp </i> package,
320 * a bounded surface based on an elementary surface (cylinder, cone, sphere or torus) from the <i> gp</i> package,
321 * a series of adjacent 2D or 3D Bezier curves defined by their poles.
322
323These algorithms compute the data needed to define the resulting BSpline curve or surface.
324This elementary data (degrees, periodic characteristics, poles and weights, knots and multiplicities)
325may then be used directly in an algorithm, or can be used to construct the curve or the surface
326by calling the appropriate constructor provided by the classes <i>Geom2d_BSplineCurve, Geom_BSplineCurve </i> or <i>Geom_BSplineSurface</i>.
327
328The <i>Geom2dConvert</i> package provides the following:
329
330 * a global function which is used to construct a BSpline curve from a bounded curve based on a 2D curve from the Geom2d package,
331 * a splitting algorithm which computes the points at which a 2D BSpline curve should be cut in order to obtain arcs with the same degree of continuity,
332 * global functions used to construct the BSpline curves created by this splitting algorithm, or by other types of segmentation of the BSpline curve,
333 * an algorithm which converts a 2D BSpline curve into a series of adjacent Bezier curves.
334
335The <i> GeomConvert</i> package also provides the following:
336
337 * a global function used to construct a BSpline curve from a bounded curve based on a curve from the Geom package,
338 * a splitting algorithm, which computes the points at which a BSpline curve should be cut in order to obtain arcs with the same degree of continuity,
339 * global functions to construct BSpline curves created by this splitting algorithm, or by other types of BSpline curve segmentation,
340 * an algorithm, which converts a BSpline curve into a series of adjacent Bezier curves,
341 * a global function to construct a BSpline surface from a bounded surface based on a surface from the Geom package,
342 * a splitting algorithm, which determines the curves along which a BSpline surface should be cut in order to obtain patches with the same degree of continuity,
343 * global functions to construct BSpline surfaces created by this splitting algorithm, or by other types of BSpline surface segmentation,
344 * an algorithm, which converts a BSpline surface into a series of adjacent Bezier surfaces,
345 * an algorithm, which converts a grid of adjacent Bezier surfaces into a BSpline surface.
72b7576f 346
347@subsection occt_modat_1_4 Points on Curves
348
e2b55410 349The Points on Curves component comprises high level functions providing an API for complex algorithms that compute points on a 2D or 3D curve.
350
72b7576f 351The following characteristic points exist on parameterized curves in 3d space:
352- points equally spaced on a curve,
353- points distributed along a curve with equal chords,
354- a point at a given distance from another point on a curve.
355
356*GCPnts* package provides algorithms to calculate such points:
357- *AbscissaPoint* calculates a point on a curve at a given distance from another point on the curve.
358- *UniformAbscissa* calculates a set of points at a given abscissa on a curve.
359- *UniformDeflection* calculates a set of points at maximum constant deflection between the curve and the polygon that results from the computed points.
360
dba69de2 361### Example: Visualizing a curve.
362
72b7576f 363Let us take an adapted curve **C**, i.e. an object which is an interface between the services provided by either a 2D curve from the package Geom2d (in case of an Adaptor_Curve2d curve) or a 3D curve from the package Geom (in case of an Adaptor_Curve curve), and the services required on the curve by the computation algorithm. The adapted curve is created in the following way:
364
dba69de2 365**2D case :**
72b7576f 366~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.cpp}
367 Handle(Geom2d_Curve) mycurve = ... ;
368 Geom2dAdaptor_Curve C (mycurve) ;
369~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
370
dba69de2 371**3D case :**
72b7576f 372~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.cpp}
373 Handle(Geom_Curve) mycurve = ... ;
374 GeomAdaptor_Curve C (mycurve) ;
375~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
376
377The algorithm is then constructed with this object:
378
379~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.cpp}
380 GCPnts_UniformDeflection myAlgo () ;
381 Standard_Real Deflection = ... ;
382 myAlgo.Initialize ( C , Deflection ) ;
383 if ( myAlgo.IsDone() )
384 {
385 Standard_Integer nbr = myAlgo.NbPoints() ;
386 Standard_Real param ;
4ee1bdf4 387 for ( Standard_Integer i = 1 ; i <= nbr ; i++ )
72b7576f 388 {
389 param = myAlgo.Parameter (i) ;
390 ...
391 }
392 }
393~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
394
395
396@subsection occt_modat_1_5 Extrema
397
398The classes to calculate the minimum distance between points, curves, and surfaces in 2d and 3d are provided by *GeomAPI* and *Geom2dAPI* packages.
399
400These packages calculate the extrema of distance between:
401- point and a curve,
402- point and a surface,
403- two curves,
404- a curve and a surface,
405- two surfaces.
406
eb5c2ff4 407### Extrema between Point and Curve / Surface
408
409The *GeomAPI_ProjectPointOnCurve* class allows calculation of all extrema between a point and a curve. Extrema are the lengths of the segments orthogonal to the curve.
410The *GeomAPI_ProjectPointOnSurface* class allows calculation of all extrema between a point and a surface. Extrema are the lengths of the segments orthogonal to the surface.
411These classes use the "Projection" criteria for optimization.
72b7576f 412
eb5c2ff4 413### Extrema between Curves
72b7576f 414
eb5c2ff4 415The *Geom2dAPI_ExtremaCurveCurve* class allows calculation of all minimal distances between two 2D geometric curves.
80223385 416The *GeomAPI_ExtremaCurveCurve* class allows calculation of all minimal distances between two 3D geometric curves.
eb5c2ff4 417These classes use Euclidean distance as the criteria for optimization.
72b7576f 418
e2b55410 419### Extrema between Curve and Surface
72b7576f 420
eb5c2ff4 421The *GeomAPI_ExtremaCurveSurface* class allows calculation of one extrema between a 3D curve and a surface. Extrema are the lengths of the segments orthogonal to the curve and the surface.
80223385 422This class uses the "Projection" criteria for optimization.
72b7576f 423
e2b55410 424### Extrema between Surfaces
72b7576f 425
eb5c2ff4 426The *GeomAPI_ExtremaSurfaceSurface* class allows calculation of one minimal and one maximal distance between two surfaces.
80223385 427This class uses Euclidean distance to compute the minimum, and "Projection" criteria to compute the maximum.
72b7576f 428
429@section occt_modat_2 2D Geometry
430
d3013f55 431*Geom2d* package defines geometric objects in 2dspace. All geometric entities are STEP processed. The objects are handled by reference.
e2b55410 432
433In particular, <i>Geom2d</i> package provides classes for:
434* description of points, vectors and curves,
435* their positioning in the plane using coordinate systems,
436* their geometric transformation, by applying translations, rotations, symmetries, scaling transformations and combinations thereof.
437
438The following objects are available:
72b7576f 439- point,
440- Cartesian point,
441- vector,
442- direction,
443- vector with magnitude,
444- axis,
445- curve,
446- line,
e2b55410 447- conic: circle, ellipse, hyperbola, parabola,
448- rounded curve: trimmed curve, NURBS curve, Bezier curve,
449- offset curve.
72b7576f 450
451Before creating a geometric object, it is necessary to decide how the object is handled.
452The objects provided by *Geom2d* package are handled by reference rather than by value. Copying an instance copies the handle, not the object, so that a change to one instance is reflected in each occurrence of it.
453If a set of object instances is needed rather than a single object instance, *TColGeom2d* package can be used. This package provides standard and frequently used instantiations of one-dimensional arrays and sequences for curves from *Geom2d* package. All objects are available in two versions:
454- handled by reference and
455- handled by value.
456
e2b55410 457The key characteristic of <i> Geom2d </i> curves is that they are parameterized.
458Each class provides functions to work with the parametric equation of the curve,
459and, in particular, to compute the point of parameter u on a curve and the derivative vectors of order 1, 2.., N at this point.
460
461As a consequence of the parameterization, a <i> Geom2d </i> curve is naturally oriented.
462
3f812249 463Parameterization and orientation differentiate elementary <i>Geom2d</i>curves from their
464equivalent as provided by <i> gp</i> package. <i>Geom2d</i> package provides conversion
e2b55410 465functions to transform a <i> Geom2d</i> object into a <i> gp</i> object, and vice-versa, when this is possible.
466
467Moreover, <i> Geom2d</i> package provides more complex curves, including Bezier curves,
468BSpline curves, trimmed curves and offset curves.
469
470<i> Geom2d </i> objects are organized according to an inheritance structure over several levels.
471
472Thus, an ellipse (specific class <i> Geom2d_Ellipse</i>) is also a conical curve and inherits from the abstract class <i> Geom2d_Conic</i>, while a Bezier curve (concrete class <i> Geom2d_BezierCurve</i>) is also a bounded curve and inherits from the abstract class <i> Geom2d_BoundedCurve</i>; both these examples are also curves (abstract class <i>Geom2d_Curve</i>). Curves, points and vectors inherit from the abstract class <i> Geom2d_Geometry,</i> which describes the properties common to any geometric object from the <i>Geom2d</i> package.
473
474This inheritance structure is open and it is possible to describe new objects, which inherit from those provided in the <i>Geom2d</i> package, provided that they respect the behavior of the classes from which they are to inherit.
475
476Finally, <i> Geom2d</i> objects can be shared within more complex data structures. This is why they are used within topological data structures, for example.
477
478<i>Geom2d</i>package uses the services of the <i> gp</i> package to:
479 * implement elementary algebraic calculus and basic analytic geometry,
480 * describe geometric transformations which can be applied to <i> Geom2d</i> objects,
481 * describe the elementary data structures of <i>Geom2d</i> objects.
482
483However, the <i> Geom2d</i> package essentially provides data structures and not algorithms.
484You can refer to the <i> GCE2d </i> package to find more evolved construction algorithms for <i> Geom2d </i> objects.
485
72b7576f 486@section occt_modat_3 3D Geometry
487
e2b55410 488The *Geom* package defines geometric objects in 3d space and contains all basic geometric transformations, such as identity, rotation, translation, mirroring, scale transformations, combinations of transformations, etc. as well as special functions depending on the reference definition of the geometric object (e.g. addition of a control point on a B-Spline curve,modification of a curve, etc.). All geometrical entities are STEP processed.
489
490In particular, it provides classes for:
491 * description of points, vectors, curves and surfaces,
492 * their positioning in 3D space using axis or coordinate systems, and
493 * their geometric transformation, by applying translations, rotations, symmetries, scaling transformations and combinations thereof.
494
d3013f55 495The following objects are available:
72b7576f 496- Point
497- Cartesian point
498- Vector
499- Direction
500- Vector with magnitude
501- Axis
502- Curve
503- Line
504- Conic: circle, ellipse, hyperbola, parabola
505- Offset curve
506- Elementary surface: plane, cylinder, cone, sphere, torus
507- Bounded curve: trimmed curve, NURBS curve, Bezier curve
508- Bounded surface: rectangular trimmed surface, NURBS surface,Bezier surface
509- Swept surface: surface of linear extrusion, surface of revolution
510- Offset surface.
511
e2b55410 512The key characteristic of *Geom* curves and surfaces is that they are parameterized.
513Each class provides functions to work with the parametric equation of the curve or
514surface, and, in particular, to compute:
515 * the point of parameter u on a curve, or
516 * the point of parameters (u, v) on a surface.
517together with the derivative vectors of order 1, 2, ... N at this point.
518
519As a consequence of this parameterization, a Geom curve or surface is naturally oriented.
520
521Parameterization and orientation differentiate elementary Geom curves and surfaces from the classes of the same (or similar) names found in <i> gp</i> package.
522<i>Geom</i> package also provides conversion functions to transform a Geom object into a <i> gp</i> object, and vice-versa, when such transformation is possible.
523
524Moreover, <i> Geom </i>package provides more complex curves and surfaces, including:
525 * Bezier and BSpline curves and surfaces,
526 * swept surfaces, for example surfaces of revolution and surfaces of linear extrusion,
527 * trimmed curves and surfaces, and
528 * offset curves and surfaces.
529
530Geom objects are organized according to an inheritance structure over several levels.
531Thus, a sphere (concrete class <i> Geom_SphericalSurface</i>) is also an elementary surface and inherits from the abstract class <i> Geom_ElementarySurface</i>, while a Bezier surface (concrete class <i> Geom_BezierSurface</i>) is also a bounded surface and inherits from the abstract class <i> Geom_BoundedSurface</i>; both these examples are also surfaces (abstract class <i> Geom_Surface</i>). Curves, points and vectors inherit from the abstract class <i> Geom_Geometry,</i> which describes the properties common to any geometric object from the <i>Geom</i> package.
532
533This inheritance structure is open and it is possible to describe new objects, which inherit from those provided in the Geom package, on the condition that they respect the behavior of the classes from which they are to inherit.
534
535Finally, Geom objects can be shared within more complex data structures. This is why they are used within topological data structures, for example.
536
72b7576f 537If a set of object instances is needed rather than a single object instance, *TColGeom* package can be used. This package provides instantiations of one- and two-dimensional arrays and sequences for curves from *Geom* package. All objects are available in two versions:
538- handled by reference and
539- handled by value.
540
e2b55410 541The <i> Geom</i> package uses the services of the <i> gp</i> package to:
542 * implement elementary algebraic calculus and basic analytic geometry,
543 * describe geometric transformations which can be applied to Geom objects,
544 * describe the elementary data structures of Geom objects.
545
546However, the Geom package essentially provides data structures, not algorithms.
547
548You can refer to the <i> GC</i> package to find more evolved construction algorithms for
549Geom objects.
550
551@section occt_modat_4 Properties of Shapes
552
553@subsection occt_modat_4_1 Local Properties of Shapes
554
555<i>BRepLProp</i> package provides the Local Properties of Shapes component,
556which contains algorithms computing various local properties on edges and faces in a BRep model.
557
558The local properties which may be queried are:
559
560 * for a point of parameter u on a curve which supports an edge :
561 * the point,
562 * the derivative vectors, up to the third degree,
563 * the tangent vector,
564 * the normal,
565 * the curvature, and the center of curvature;
566 * for a point of parameter (u, v) on a surface which supports a face :
567 * the point,
568 * the derivative vectors, up to the second degree,
569 * the tangent vectors to the u and v isoparametric curves,
570 * the normal vector,
571 * the minimum or maximum curvature, and the corresponding directions of curvature;
572 * the degree of continuity of a curve which supports an edge, built by the concatenation of two other edges, at their junction point.
573
574Analyzed edges and faces are described as <i> BRepAdaptor</i> curves and surfaces,
575which provide shapes with an interface for the description of their geometric support.
576The base point for local properties is defined by its u parameter value on a curve, or its (u, v) parameter values on a surface.
577
578@subsection occt_modat_4_2 Local Properties of Curves and Surfaces
579
580The "Local Properties of Curves and Surfaces" component provides algorithms for computing various local properties on a Geom curve (in 2D or 3D space) or a surface. It is composed of:
581
582 * <i> Geom2dLProp</i> package, which allows computing Derivative and Tangent vectors (normal and curvature) of a parametric point on a 2D curve;
583 * <i> GeomLProp </i> package, which provides local properties on 3D curves and surfaces
584 * <i> LProp </i> package, which provides an enumeration used to characterize a particular point on a 2D curve.
585
586Curves are either <i> Geom_Curve </i> curves (in 3D space) or <i> Geom2d_Curve </i> curves (in the plane).
587Surfaces are <i> Geom_Surface </i> surfaces. The point on which local properties are calculated
588is defined by its u parameter value on a curve, and its (u,v) parameter values on a surface.
589
590It is possible to query the same local properties for points as mentioned above, and additionally for 2D curves:
591
592 * the points corresponding to a minimum or a maximum of curvature;
593 * the inflection points.
594
595
596#### Example: How to check the surface concavity
597
598To check the concavity of a surface, proceed as follows:
599
600 1. Sample the surface and compute at each point the Gaussian curvature.
601 2. If the value of the curvature changes of sign, the surface is concave or convex depending on the point of view.
602 3. To compute a Gaussian curvature, use the class <i> SLprops</i> from <i> GeomLProp</i>, which instantiates the generic class <i> SLProps </i>from <i> LProp</i> and use the method <i> GaussianCurvature</i>.
712879c8 603
604@subsection occt_modat_4_2a Continuity of Curves and Surfaces
605
606Types of supported continuities for curves and surfaces are described in *GeomAbs_Shape* enumeration.
607
608In respect of curves, the following types of continuity are supported (see the figure below):
609 * C0 (*GeomAbs_C0*) - parametric continuity. It is the same as G0 (geometric continuity), so the last one is not represented by separate variable.
610 * G1 (*GeomAbs_G1*) - tangent vectors on left and on right are parallel.
611 * C1 (*GeomAbs_C1*) - indicates the continuity of the first derivative.
612 * G2 (*GeomAbs_G2*) - in addition to G1 continuity, the centers of curvature on left and on right are the same.
613 * C2 (*GeomAbs_C2*) - continuity of all derivatives till the second order.
614 * C3 (*GeomAbs_C3*) - continuity of all derivatives till the third order.
615 * CN (*GeomAbs_CN*) - continuity of all derivatives till the N-th order (infinite order of continuity).
616
617*Note:* Geometric continuity (G1, G2) means that the curve can be reparametrized to have parametric (C1, C2) continuity.
618
d6b4d3d0 619@figure{/user_guides/modeling_data/images/modeling_data_continuity_curves.svg,"Continuity of Curves",420}
712879c8 620
621The following types of surface continuity are supported:
622 * C0 (*GeomAbs_C0*) - parametric continuity (the surface has no points or curves of discontinuity).
623 * G1 (*GeomAbs_G1*) - surface has single tangent plane in each point.
624 * C1 (*GeomAbs_C1*) - indicates the continuity of the first derivatives.
625 * G2 (*GeomAbs_G2*) - in addition to G1 continuity, principal curvatures and directions are continuous.
626 * C2 (*GeomAbs_C2*) - continuity of all derivatives till the second order.
627 * C3 (*GeomAbs_C3*) - continuity of all derivatives till the third order.
628 * CN (*GeomAbs_CN*) - continuity of all derivatives till the N-th order (infinite order of continuity).
629
d6b4d3d0 630@figure{/user_guides/modeling_data/images/modeling_data_continuity_surfaces.svg,"Continuity of Surfaces",420}
712879c8 631
632Against single surface, the connection of two surfaces (see the figure above) defines its continuity in each intersection point only. Smoothness of connection is a minimal value of continuities on the intersection curve.
633
634
635@subsection occt_modat_4_2b Regularity of Shared Edges
636
637Regularity of an edge is a smoothness of connection of two faces sharing this edge. In other words, regularity is a minimal continuity between connected faces in each point on edge.
638
639Edge's regularity can be set by *BRep_Builder::Continuity* method. To get the regularity use *BRep_Tool::Continuity* method.
640
641Some algorithms like @ref occt_modalg_6 "Fillet" set regularity of produced edges by their own algorithms. On the other hand, some other algorithms (like @ref occt_user_guides__boolean_operations "Boolean Operations", @ref occt_user_guides__shape_healing "Shape Healing", etc.) do not set regularity. If the regularity is needed to be set correctly on a shape, the method *BRepLib::EncodeRegularity* can be used. It calculates and sets correct values for all edges of the shape.
642
643The regularity flag is extensively used by the following high level algorithms: @ref occt_modalg_6_1_2 "Chamfer", @ref occt_modalg_7_3 "Draft Angle", @ref occt_modalg_10 "Hidden Line Removal", @ref occt_modalg_9_2_3 "Gluer".
644
e2b55410 645
646@subsection occt_modat_4_3 Global Properties of Shapes
647
648The Global Properties of Shapes component provides algorithms for computing the global
649properties of a composite geometric system in 3D space, and frameworks to query the computed results.
650
651The global properties computed for a system are :
652 * mass,
653 * mass center,
654 * matrix of inertia,
655 * moment about an axis,
656 * radius of gyration about an axis,
657 * principal properties of inertia such as principal axis, principal moments, and principal radius of gyration.
658
659Geometric systems are generally defined as shapes. Depending on the way they are analyzed, these shapes will give properties of:
660
661 * lines induced from the edges of the shape,
662 * surfaces induced from the faces of the shape, or
663 * volumes induced from the solid bounded by the shape.
664
665The global properties of several systems may be brought together to give the global properties of the system composed of the sum of all individual systems.
72b7576f 666
e2b55410 667The Global Properties of Shapes component is composed of:
668* seven functions for computing global properties of a shape: one function for lines, two functions for surfaces and four functions for volumes. The choice of functions depends on input parameters and algorithms used for computation (<i>BRepGProp</i> global functions),
669* a framework for computing global properties for a set of points (<i>GProp_PGProps</i>),
670* a general framework to bring together the global properties retained by several more elementary frameworks, and provide a general programming interface to consult computed global properties.
671
672Packages *GeomLProp* and *Geom2dLProp* provide algorithms calculating the local properties of curves and surfaces
72b7576f 673
674A curve (for one parameter) has the following local properties:
675- Point
676- Derivative
677- Tangent
678- Normal
679- Curvature
680- Center of curvature.
681
682A surface (for two parameters U and V) has the following local properties:
683- point
684- derivative for U and V)
685- tangent line (for U and V)
686- normal
687- max curvature
688- min curvature
689- main directions of curvature
690- mean curvature
691- Gaussian curvature
692
693The following methods are available:
3f812249 694* *CLProps* -- calculates the local properties of a curve (tangency, curvature,normal);
695* *CurAndInf2d* -- calculates the maximum and minimum curvatures and the inflection points of 2d curves;
696* *SLProps* -- calculates the local properties of a surface (tangency, the normal and curvature).
697* *Continuity* -- calculates regularity at the junction of two curves.
72b7576f 698
699Note that the B-spline curve and surface are accepted but they are not cut into pieces of the desired continuity. It is the global continuity, which is seen.
700
8d44b0a0 701@subsection occt_modat_4_4 Adaptors for Curves and Surfaces
e2b55410 702
703Some Open CASCADE Technology general algorithms may work theoretically on numerous types of curves or surfaces.
704
705To do this, they simply get the services required of the analyzed curve or surface through an interface so as to a single API, whatever the type of curve or surface. These interfaces are called adaptors.
706
707For example, <i> Adaptor3d_Curve </i> is the abstract class which provides the required services by an algorithm which uses any 3d curve.
708
709<i> GeomAdaptor </i> package provides interfaces:
710 * On a Geom curve;
711 * On a curve lying on a Geom surface;
712 * On a Geom surface;
713
714<i> Geom2dAdaptor</i> package provides interfaces :
715 * On a <i>Geom2d</i> curve.
716
717<i> BRepAdaptor </i> package provides interfaces:
718 * On a Face
719 * On an Edge
720
721When you write an algorithm which operates on geometric objects, use <i> Adaptor3d</i> (or <i> Adaptor2d</i>) objects.
722
723As a result, you can use the algorithm with any kind of object, if you provide for this object an interface derived from *Adaptor3d* or *Adaptor2d*.
724These interfaces are easy to use: simply create an adapted curve or surface from a *Geom2d* curve, and then use this adapted curve as an argument for the algorithm? which requires it.
725
72b7576f 726
727@section occt_modat_5 Topology
728
e2b55410 729OCCT Topology allows accessing and manipulating data of objects without dealing with their 2D or 3D representations. Whereas OCCT Geometry provides a description of objects in terms of coordinates or parametric values, Topology describes data structures of objects in parametric space. These descriptions use location in and restriction of parts of this space.
730
731Topological library allows you to build pure topological data structures. Topology defines relationships between simple geometric entities. In this way, you can model complex shapes as assemblies of simpler entities. Due to a built-in non-manifold (or mixed-dimensional) feature, you can build models mixing:
732 * 0D entities such as points;
733 * 1D entities such as curves;
734 * 2D entities such as surfaces;
735 * 3D entities such as volumes.
736
737You can, for example, represent a single object made of several distinct bodies containing embedded curves and surfaces connected or non-connected to an outer boundary.
72b7576f 738
3f812249 739Abstract topological data structure describes a basic entity -- a shape, which can be divided into the following component topologies:
740 * Vertex -- a zero-dimensional shape corresponding to a point in geometry;
741 * Edge -- a shape corresponding to a curve, and bound by a vertex at each extremity;
742 * Wire -- a sequence of edges connected by their vertices;
743 * Face -- part of a plane (in 2D geometry) or a surface (in 3D geometry) bounded by a closed wire;
744 * Shell -- a collection of faces connected by some edges of their wire boundaries;
745 * Solid -- a part of 3D space bound by a shell;
746 * Compound solid -- a collection of solids.
72b7576f 747
e2b55410 748The wire and the solid can be either infinite or closed.
749
750A face with 3D underlying geometry may also refer to a collection of connected triangles that approximate the underlying surface. The surfaces can be undefined leaving the faces represented by triangles only. If so, the model is purely polyhedral.
751
752Topology defines the relationship between simple geometric entities, which can thus be linked together to represent complex shapes.
753
754Abstract Topology is provided by six packages.
755The first three packages describe the topological data structure used in Open CASCADE Technology:
756
757 * <i> TopAbs</i> package provides general resources for topology-driven applications. It contains enumerations that are used to describe basic topological notions: topological shape, orientation and state. It also provides methods to manage these enumerations.
758 * <i> TopLoc </i>package provides resources to handle 3D local coordinate systems: <i> Datum3D</i>and <i> Location</i>. <i> Datum3D</i> describes an elementary coordinate system, while <i> Location</i> comprises a series of elementary coordinate systems.
759 * <i> TopoDS</i> package describes classes to model and build data structures that are purely topological.
760
761Three additional packages provide tools to access and manipulate this abstract topology:
762
763 * <i> TopTools</i> package provides basic tools to use on topological data structures.
764 * <i> TopExp</i> package provides classes to explore and manipulate the topological data structures described in the TopoDS package.
765 * <i> BRepTools </i> package provides classes to explore, manipulate, read and write BRep data structures. These more complex data structures combine topological descriptions with additional geometric information, and include rules for evaluating equivalence of different possible representations of the same object, for example, a point.
72b7576f 766
767@subsection occt_modat_5_1 Shape Location
768
769A local coordinate system can be viewed as either of the following:
e2b55410 770- A right-handed trihedron with an origin and three orthonormal vectors. The *gp_Ax2* package corresponds to this definition.
771- A transformation of a +1 determinant, allowing the transformation of coordinates between local and global references frames. This corresponds to the *gp_Trsf*.
72b7576f 772
773*TopLoc* package distinguishes two notions:
774- *TopLoc_Datum3D* class provides the elementary reference coordinate, represented by a right-handed orthonormal system of axes or by a right-handed unitary transformation.
775- *TopLoc_Location* class provides the composite reference coordinate made from elementary ones. It is a marker composed of a chain of references to elementary markers. The resulting cumulative transformation is stored in order to avoid recalculating the sum of the transformations for the whole list.
776
d6b4d3d0 777@figure{/user_guides/modeling_data/images/modeling_data_image005.png,"Structure of TopLoc_Location",420}
72b7576f 778
779Two reference coordinates are equal if they are made up of the same elementary coordinates in the same order. There is no numerical comparison. Two coordinates can thus correspond to the same transformation without being equal if they were not built from the same elementary coordinates.
780
781For example, consider three elementary coordinates:
782R1, R2, R3
783The composite coordinates are:
784C1 = R1 * R2,
785C2 = R2 * R3
786C3 = C1 * R3
787C4 = R1 * C2
788
789**NOTE** C3 and C4 are equal because they are both R1 * R2 * R3.
790
e2b55410 791The *TopLoc* package is chiefly targeted at the topological data structure, but it can be used for other purposes.
72b7576f 792
793Change of coordinates
794---------------------
795
25e59720 796*TopLoc_Datum3D* class represents a change of elementary coordinates. Such changes must be shared so this class inherits from *Standard_Transient*. The coordinate is represented by a transformation *gp_Trsfpackage*. This transformation has no scaling factor.
72b7576f 797
72b7576f 798@subsection occt_modat_5_2 Naming shapes, sub-shapes, their orientation and state
799
800The **TopAbs** package provides general enumerations describing the basic concepts of topology and methods to handle these enumerations. It contains no classes. This package has been separated from the rest of the topology because the notions it contains are sufficiently general to be used by all topological tools. This avoids redefinition of enumerations by remaining independent of modeling resources. The TopAbs package defines three notions:
e2b55410 801- **Type** *TopAbs_ShapeEnum*;
802- **Orientation** *TopAbs_Orientation* ;
803- **State** *StateTopAbs_State*
72b7576f 804
805@subsubsection occt_modat_5_2_1 Topological types
806
807TopAbs contains the *TopAbs_ShapeEnum* enumeration,which lists the different topological types:
3f812249 808- COMPOUND -- a group of any type of topological objects.
809- COMPSOLID -- a composite solid is a set of solids connected by their faces. It expands the notions of WIRE and SHELL to solids.
810- SOLID -- a part of space limited by shells. It is three dimensional.
811- SHELL -- a set of faces connected by their edges. A shell can be open or closed.
812- FACE -- in 2D it is a part of a plane; in 3D it is a part of a surface. Its geometry is constrained (trimmed) by contours. It is two dimensional.
813- WIRE -- a set of edges connected by their vertices. It can be an open or closed contour depending on whether the edges are linked or not.
814- EDGE -- a topological element corresponding to a restrained curve. An edge is generally limited by vertices. It has one dimension.
815- VERTEX -- a topological element corresponding to a point. It has zero dimension.
816- SHAPE -- a generic term covering all of the above.
72b7576f 817
818A topological model can be considered as a graph of objects with adjacency relationships. When modeling a part in 2D or 3D space it must belong to one of the categories listed in the ShapeEnum enumeration. The TopAbspackage lists all the objects, which can be found in any model. It cannot be extended but a subset can be used. For example, the notion of solid is useless in 2D.
819
820The terms of the enumeration appear in order from the most complex to the most simple, because objects can contain simpler objects in their description. For example, a face references its wires, edges, and vertices.
d6b4d3d0 821@figure{/user_guides/modeling_data/images/modeling_data_image006.png,"ShapeEnum",420}
72b7576f 822
823@subsubsection occt_modat_5_2_2 Orientation
824
825The notion of orientation is represented by the **TopAbs_Orientation** enumeration. Orientation is a generalized notion of the sense of direction found in various modelers. This is used when a shape limits a geometric domain; and is closely linked to the notion of boundary. The three cases are the following:
826- Curve limited by a vertex.
827- Surface limited by an edge.
828- Space limited by a face.
829
830In each case the topological form used as the boundary of a geometric domain of a higher dimension defines two local regions of which one is arbitrarily considered as the **default region**.
831
832For a curve limited by a vertex the default region is the set of points with parameters greater than the vertex. That is to say it is the part of the curve after the vertex following the natural direction along the curve.
833
834For a surface limited by an edge the default region is on the left of the edge following its natural direction. More precisely it is the region pointed to by the vector product of the normal vector to the surface and the vector tangent to the curve.
835
836For a space limited by a face the default region is found on the negative side of the normal to the surface.
837
838Based on this default region the orientation allows definition of the region to be kept, which is called the *interior* or *material*. There are four orientations defining the interior.
839
e5bd0d98 840| Orientation | Description |
841| :--------- | :--------------------------------- |
dba69de2 842| FORWARD | The interior is the default region. |
843| REVERSED | The interior is the region complementary to the default. |
844| INTERNAL | The interior includes both regions. The boundary lies inside the material. For example a surface inside a solid. |
845| EXTERNAL | The interior includes neither region. The boundary lies outside the material. For example an edge in a wire-frame model. |
72b7576f 846
d6b4d3d0 847@figure{/user_guides/modeling_data/images/modeling_data_image007.png,"Four Orientations",420}
72b7576f 848
3f812249 849The notion of orientation is a very general one, and it can be used in any context where regions or boundaries appear. Thus, for example, when describing the intersection of an edge and a contour it is possible to describe not only the vertex of intersection but also how the edge crosses the contour considering it as a boundary. The edge would therefore be divided into two regions: exterior and interior and the intersection vertex would be the boundary. Thus an orientation can be associated with an intersection vertex as in the following figure:
72b7576f 850
e5bd0d98 851| Orientation | Association |
852| :-------- | :-------- |
dba69de2 853| FORWARD | Entering |
854| REVERSED | Exiting |
855| INTERNAL | Touching from inside |
856| EXTERNAL | Touching from outside |
72b7576f 857
d6b4d3d0 858@figure{/user_guides/modeling_data/images/modeling_data_image008.png,"Four orientations of intersection vertices",420}
72b7576f 859
860
861Along with the Orientation enumeration the *TopAbs* package defines four methods:
862
863@subsubsection occt_modat_5_2_3 State
864
865The **TopAbs_State** enumeration described the position of a vertex or a set of vertices with respect to a region. There are four terms:
dba69de2 866
e5bd0d98 867|Position | Description |
868| :------ | :------- |
dba69de2 869|IN | The point is interior. |
870|OUT | The point is exterior. |
871|ON | The point is on the boundary(within tolerance). |
872|UNKNOWN | The state of the point is indeterminate. |
873
72b7576f 874The UNKNOWN term has been introduced because this enumeration is often used to express the result of a calculation, which can fail. This term can be used when it is impossible to know if a point is inside or outside, which is the case with an open wire or face.
875
d6b4d3d0 876@figure{/user_guides/modeling_data/images/modeling_data_image009.png,"The four states",420}
72b7576f 877
878The State enumeration can also be used to specify various parts of an object. The following figure shows the parts of an edge intersecting a face.
879
d6b4d3d0 880@figure{/user_guides/modeling_data/images/modeling_data_image010.png,"State specifies the parts of an edge intersecting a face",420}
72b7576f 881
882@subsection occt_modat_5_3 Manipulating shapes and sub-shapes
883
884The *TopoDS* package describes the topological data structure with the following characteristics:
885- reference to an abstract shape with neither orientation nor location.
886- Access to the data structure through the tool classes.
887
888As stated above, OCCT Topology describes data structures of objects in parametric space. These descriptions use localization in and restriction of parts of this space. The types of shapes, which can be described in these terms, are the vertex, the face and the shape. The vertex is defined in terms of localization in parametric space, and the face and shape, in terms of restriction of this space.
889
890OCCT topological descriptions also allow the simple shapes defined in these terms to be combined into sets. For example, a set of edges forms a wire; a set of faces forms a shell, and a set of solids forms a composite solid (CompSolid in Open CASCADE Technology). You can also combine shapes of either sort into compounds. Finally, you can give a shape an orientation and a location.
891
892Listing shapes in order of complexity from vertex to composite solid leads us to the notion of the data structure as knowledge of how to break a shape down into a set of simpler shapes. This is in fact, the purpose of the *TopoDS* package.
893
3f812249 894The model of a shape is a shareable data structure because it can be used by other shapes. (An edge can be used by more than one face of a solid). A shareable data structure is handled by reference. When a simple reference is insufficient, two pieces of information are added: an orientation and a local coordinate reference.
72b7576f 895- An orientation tells how the referenced shape is used in a boundary (*Orientation* from *TopAbs*).
896- A local reference coordinate (*Location* from *TopLoc*) allows referencing a shape at a position different from that of its definition.
897
898The **TopoDS_TShape** class is the root of all shape descriptions. It contains a list of shapes. Classes inheriting **TopoDS_TShape** can carry the description of a geometric domain if necessary (for example, a geometric point associated with a TVertex). A **TopoDS_TShape** is a description of a shape in its definition frame of reference. This class is manipulated by reference.
899
900The **TopoDS_Shape** class describes a reference to a shape. It contains a reference to an underlying abstract shape, an orientation,and a local reference coordinate. This class is manipulated by value and thus cannot be shared.
901
902The class representing the underlying abstract shape is never referenced directly. The *TopoDS_Shape* class is always used to refer to it.
903
dba69de2 904The information specific to each shape (the geometric support) is always added by inheritance to classes deriving from **TopoDS_TShape**. The following figures show the example of a shell formed from two faces connected by an edge.
72b7576f 905
d6b4d3d0 906@figure{/user_guides/modeling_data/images/modeling_data_image011.png,"Structure of a shell formed from two faces",420}
72b7576f 907
d6b4d3d0 908@figure{/user_guides/modeling_data/images/modeling_data_image012.png,"Data structure of the above shell",420}
72b7576f 909
910In the previous diagram, the shell is described by the underlying shape TS, and the faces by TF1 and TF2. There are seven edges from TE1 to TE7 and six vertices from TV1 to TV6.
911
912The wire TW1 references the edges from TE1 to TE4; TW2 references from TE4 to TE7.
913
914The vertices are referenced by the edges as follows:TE1(TV1,TV4), TE2(TV1,TV2), TE3(TV2,TV3), TE4(TV3,TV4), TE5(TV4,TV5), TE6(T5,TV6),TE7(TV3,TV6).
915
916**Note** that this data structure does not contain any *back references*. All references go from more complex underlying shapes to less complex ones. The techniques used to access the information are described later. The data structure is as compact as possible. Sub-objects can be shared among different objects.
917
918Two very similar objects, perhaps two versions of the same object, might share identical sub-objects. The usage of local coordinates in the data structure allows the description of a repetitive sub-structure to be shared.
919
920The compact data structure avoids the loss of information associated with copy operations which are usually used in creating a new version of an object or when applying a coordinate change.
921
922The following figure shows a data structure containing two versions of a solid. The second version presents a series of identical holes bored at different positions. The data structure is compact and yet keeps all information on the sub-elements.
923
924The three references from *TSh2* to the underlying face *TFcyl* have associated local coordinate systems, which correspond to the successive positions of the hole.
d6b4d3d0 925@figure{/user_guides/modeling_data/images/modeling_data_image013.png,"Data structure containing two versions of a solid",420}
72b7576f 926
927Classes inheriting TopoDS_Shape
928------------------------------
929*TopoDS* is based on class *TopoDS_Shape* and the class defining its underlying shape. This has certain advantages, but the major drawback is that these classes are too general. Different shapes they could represent do not type them (Vertex, Edge, etc.) hence it is impossible to introduce checks to avoid incoherences such as inserting a face in an edge.
930
931 *TopoDS* package offers two sets of classes, one set inheriting the underlying shape with neither orientation nor location and the other inheriting *TopoDS_Shape*, which represent the standard topological shapes enumerated in *TopAbs* package.
932
933The following classes inherit Shape : *TopoDS_Vertex, TopoDS_Edge, TopoDS_Wire, TopoDS_Face, TopoDS_Shell, TopoDS_Solid,TopoDS_CompSolid,* and *TopoDS_Compound*. In spite of the similarity of names with those inheriting from **TopoDS_TShape** there is a profound difference in the way they are used.
934
935*TopoDS_Shape* class and the classes, which inherit from it, are the natural means to manipulate topological objects. *TopoDS_TShape* classes are hidden. *TopoDS_TShape* describes a class in its original local coordinate system without orientation. *TopoDS_Shape* is a reference to *TopoDS_TShape* with an orientation and a local reference.
936
937*TopoDS_TShape* class is deferred; *TopoDS_Shape* class is not. Using *TopoDS_Shape* class allows manipulation of topological objects without knowing their type. It is a generic form. Purely topological algorithms often use the *TopoDS_Shape* class.
938
939*TopoDS_TShape* class is manipulated by reference; TopoDS_Shape class by value. A TopoDS_Shape is nothing more than a reference enhanced with an orientation and a local coordinate. The sharing of *TopoDS_Shapes* is meaningless. What is important is the sharing of the underlying *TopoDS_TShapes*. Assignment or passage in argument does not copy the data structure: this only creates new *TopoDS_Shapes* which refer to the same *TopoDS_TShape*.
940
941Although classes inheriting *TopoDS_TShape* are used for adding extra information, extra fields should not be added in a class inheriting from TopoDS_Shape. Classes inheriting from TopoDS_Shape serve only to specialize a reference in order to benefit from static type control (carried out by the compiler). For example, a routine that receives a *TopoDS_Face* in argument is more precise for the compiler than the one, which receives a *TopoDS_Shape*. It is pointless to derive other classes than those found inTopoDS. All references to a topological data structure are made with the Shape class and its inheritors defined in *TopoDS*.
942
943There are no constructors for the classes inheriting from the *TopoDS_Shape* class, otherwise the type control would disappear through **implicit casting** (a characteristic of C++). The TopoDS package provides package methods for **casting** an object of the TopoDS_Shape class in one of these sub-classes, with type verification.
944
945The following example shows a routine receiving an argument of the *TopoDS_Shape* type, then putting it into a variable V if it is a vertex or calling the method ProcessEdge if it is an edge.
946
947
72b7576f 948~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.cpp}
4ee1bdf4 949 #include <TopoDS_Vertex.hxx>
950 #include <TopoDS_Edge.hxx>
951 #include <TopoDS_Shape.hxx>
72b7576f 952
953
e5bd0d98 954 void ProcessEdge(const TopoDS_Edge&);
72b7576f 955
e5bd0d98 956 void Process(const TopoDS_Shape& aShape) {
72b7576f 957 if (aShape.Shapetype() == TopAbs_VERTEX) {
958 TopoDS_Vertex V;
959 V = TopoDS::Vertex(aShape); // Also correct
4ee1bdf4 960 TopoDS_Vertex V2 = aShape; // Rejected by the compiler
72b7576f 961 TopoDS_Vertex V3 = TopoDS::Vertex(aShape); // Correct
962 }
963 else if (aShape.ShapeType() == TopAbs_EDGE){
4ee1bdf4 964 ProcessEdge(aShape) ; // This is rejected
72b7576f 965 ProcessEdge(TopoDS::Edge(aShape)) ; // Correct
966 }
967 else {
4ee1bdf4 968 cout <<"Neither a vertex nor an edge ?";
72b7576f 969 ProcessEdge(TopoDS::Edge(aShape)) ;
4ee1bdf4 970 // OK for compiler but an exception will be raised at run-time
72b7576f 971 }
972 }
973~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
974
975
976
977@subsection occt_modat_5_4 Exploration of Topological Data Structures
978
979The *TopExp* package provides tools for exploring the data structure described with the *TopoDS* package. Exploring a topological structure means finding all sub-objects of a given type, for example, finding all the faces of a solid.
980
981The TopExp package provides the class *TopExp_Explorer* to find all sub-objects of a given type. An explorer is built with:
982- The shape to be explored.
983- The type of shapes to be found e.g. VERTEX, EDGE with the exception of SHAPE, which is not allowed.
984- The type of Shapes to avoid. e.g. SHELL, EDGE. By default, this type is SHAPE. This default value means that there is no restriction on the exploration.
985
986
987
988The Explorer visits the whole structure in order to find the shapes of the requested type not contained in the type to avoid. The example below shows how to find all faces in the shape *S*:
989
dba69de2 990
72b7576f 991~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.cpp}
992 void test() {
993 TopoDS_Shape S;
994 TopExp_Explorer Ex;
995 for (Ex.Init(S,TopAbs_FACE); Ex.More(); Ex.Next()) {
996 ProcessFace(Ex.Current());
997 }
998 }
999~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1000
dba69de2 1001Find all the vertices which are not in an edge
72b7576f 1002
72b7576f 1003~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.cpp}
1004for (Ex.Init(S,TopAbs_VERTEX,TopAbs_EDGE); ...)
1005~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1006
1007
dba69de2 1008Find all the faces in a SHELL, then all the faces not in a SHELL:
72b7576f 1009
72b7576f 1010
1011~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.cpp}
1012 void test() {
1013 TopExp_Explorer Ex1, Ex2;
1014 TopoDS_Shape S;
1015 for (Ex1.Init(S,TopAbs_SHELL);Ex1.More(); Ex1.Next()){
1016 // visit all shells
1017 for (Ex2.Init(Ex1.Current(),TopAbs_FACE);Ex2.More();
1018 Ex2.Next()){
1019 //visit all the faces of the current shell
1020 ProcessFaceinAshell(Ex2.Current());
1021 ...
1022 }
1023 }
1024 for(Ex1.Init(S,TopAbs_FACE,TopAbs_SHELL);Ex1.More(); Ex1.Next()){
1025 // visit all faces not ina shell.
1026 ProcessFace(Ex1.Current());
1027 }
1028 }
1029~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1030
dba69de2 1031The Explorer presumes that objects contain only objects of an equal or inferior type. For example, if searching for faces it does not look at wires, edges, or vertices to see if they contain faces.
72b7576f 1032
1033The *MapShapes* method from *TopExp* package allows filling a Map. An exploration using the Explorer class can visit an object more than once if it is referenced more than once. For example, an edge of a solid is generally referenced by two faces. To process objects only once, they have to be placed in a Map.
1034
4ee1bdf4 1035**Example**
72b7576f 1036~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.cpp}
e5bd0d98 1037 void TopExp::MapShapes (const TopoDS_Shape& S,
72b7576f 1038 const TopAbs_ShapeEnum T,
e5bd0d98 1039 TopTools_IndexedMapOfShape& M)
72b7576f 1040 {
1041 TopExp_Explorer Ex(S,T);
1042 while (Ex.More()) {
1043 M.Add(Ex.Current());
1044 Ex.Next();
1045 }
1046 }
1047~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1048
1049In the following example all faces and all edges of an object are drawn in accordance with the following rules:
1050- The faces are represented by a network of *NbIso* iso-parametric lines with *FaceIsoColor* color.
1051- The edges are drawn in a color, which indicates the number of faces sharing the edge:
dba69de2 1052 - *FreeEdgeColor* for edges, which do not belong to a face (i.e. wireframe element).
1053 - *BorderEdgeColor* for an edge belonging to a single face.
1054 - *SharedEdgeColor* for an edge belonging to more than one face.
1055- The methods *DrawEdge* and *DrawFaceIso* are also available to display individual edges and faces.
72b7576f 1056
1057The following steps are performed:
10581. Storing the edges in a map and create in parallel an array of integers to count the number of faces sharing the edge. This array is initialized to zero.
10592. Exploring the faces. Each face is drawn.
10603. Exploring the edges and for each of them increment the counter of faces in the array.
10614. From the Map of edges, drawing each edge with the color corresponding to the number of faces.
1062
72b7576f 1063~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.cpp}
e5bd0d98 1064 void DrawShape ( const TopoDS_Shape& aShape,
72b7576f 1065 const Standard_Integer nbIsos,
1066 const Color FaceIsocolor,
1067 const Color FreeEdgeColor,
1068 const Color BorderEdgeColor,
1069 const Color SharedEdgeColor)
1070 {
1071 // Store the edges in aMap.
1072 TopTools_IndexedMapOfShape edgemap;
1073 TopExp::MapShapes(aShape,TopAbs_EDGE,edgeMap);
1074 // Create an array set to zero.
1075 TColStd_Array1OfInteger faceCount(1,edgeMap.Extent());
1076 faceCount.Init (0);
1077 // Explore the faces.
1078 TopExp_Explorer expFace(aShape,TopAbs_FACE);
1079 while (expFace.More()) {
1080 //Draw the current face.
1081 DrawFaceIsos(TopoDS::Face(expFace.Current()),nbIsos,FaceIsoColor);
1082 // Explore the edges ofthe face.
1083 TopExp_Explorer expEdge(expFace.Current(),TopAbs_EDGE);
1084 while (expEdge.More()) {
1085 //Increment the face count for this edge.
1086 faceCount(edgemap.FindIndex(expEdge.Current()))++;
1087 expEdge.Next();
1088 }
1089 expFace.Next();
1090 }
1091 //Draw the edges of theMap
1092 Standard_Integer i;
4ee1bdf4 1093 for (i=1;i<=edgemap.Extent();i++) {
72b7576f 1094 switch (faceCount(i)) {
1095 case 0 :
1096 DrawEdge(TopoDS::Edge(edgemap(i)),FreeEdgeColor);
1097 break;
1098 case 1 :
1099 DrawEdge(TopoDS::Edge(edgemap(i)),BorderEdgeColor);
1100 break;
1101 default :
1102 DrawEdge(TopoDS::Edge(edgemap(i)),SharedEdgeColor);
1103 break;
1104 }
1105 }
1106 }
1107~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1108
1109@subsection occt_modat_5_5 Lists and Maps of Shapes
1110
1111**TopTools** package contains tools for exploiting the *TopoDS* data structure. It is an instantiation of the tools from *TCollection* package with the Shape classes of *TopoDS*.
1112
e5bd0d98 1113
3f812249 1114* *TopTools_Array1OfShape, HArray1OfShape* -- instantiation of the *TCollection_Array1* and *TCollection_HArray1* with *TopoDS_Shape*.
1115* *TopTools_SequenceOfShape* -- instantiation of the *TCollection_Sequence* with *TopoDS_Shape*.
1116* *TopTools_MapOfShape* - instantiation of the *TCollection_Map*. Allows the construction of sets of shapes.
1117* *TopTools_IndexedMapOfShape* - instantiation of the *TCollection_IndexedMap*. Allows the construction of tables of shapes and other data structures.
72b7576f 1118
dba69de2 1119With a *TopTools_Map*, a set of references to Shapes can be kept without duplication.
1120The following example counts the size of a data structure as a number of *TShapes*.
1121
72b7576f 1122
72b7576f 1123~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.cpp}
4ee1bdf4 1124 #include <TopoDS_Iterator.hxx>
e5bd0d98 1125 Standard_Integer Size(const TopoDS_Shape& aShape)
72b7576f 1126 {
1127 // This is a recursive method.
1128 // The size of a shape is1 + the sizes of the subshapes.
1129 TopoDS_Iterator It;
1130 Standard_Integer size = 1;
1131 for (It.Initialize(aShape);It.More();It.Next()) {
1132 size += Size(It.Value());
1133 }
1134 return size;
1135 }
1136~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1137
1138This program is incorrect if there is sharing in the data structure.
72b7576f 1139
dba69de2 1140Thus for a contour of four edges it should count 1 wire + 4 edges +4 vertices with the result 9, but as the vertices are each shared by two edges this program will return 13. One solution is to put all the Shapes in a Map so as to avoid counting them twice, as in the following example:
1141
1142
72b7576f 1143~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.cpp}
4ee1bdf4 1144 #include <TopoDS_Iterator.hxx>
1145 #include <TopTools_MapOfShape.hxx>
72b7576f 1146
e5bd0d98 1147 void MapShapes(const TopoDS_Shape& aShape,
1148 TopTools_MapOfShape& aMap)
72b7576f 1149 {
1150 //This is a recursive auxiliary method. It stores all subShapes of aShape in a Map.
1151 if (aMap.Add(aShape)) {
1152 //Add returns True if aShape was not already in the Map.
1153 TopoDS_Iterator It;
1154 for (It.Initialize(aShape);It.More();It.Next()){
1155 MapShapes(It.Value(),aMap);
1156 }
1157 }
1158 }
1159
e5bd0d98 1160 Standard_Integer Size(const TopoDS_Shape& aShape)
72b7576f 1161 {
1162 // Store Shapes in a Mapand return the size.
1163 TopTools_MapOfShape M;
1164 MapShapes(aShape,M);
1165 return M.Extent();
1166 }
1167~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1168
dba69de2 1169**Note** For more details about Maps please, refer to the TCollection documentation. (Foundation Classes Reference Manual)
72b7576f 1170
dba69de2 1171The following example is more ambitious and writes a program which copies a data structure using an *IndexedMap*. The copy is an identical structure but it shares nothing with the original. The principal algorithm is as follows:
1172- All Shapes in the structure are put into an *IndexedMap*.
72b7576f 1173- A table of Shapes is created in parallel with the map to receive the copies.
1174- The structure is copied using the auxiliary recursive function,which copies from the map to the array.
1175
72b7576f 1176~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.cpp}
4ee1bdf4 1177 #include <TopoDS_Shape.hxx>
1178 #include <TopoDS_Iterator.hxx>
1179 #include <TopTools_IndexedMapOfShape.hxx>
1180 #include <TopTools_Array1OfShape.hxx>
1181 #include <TopoDS_Location.hxx>
72b7576f 1182
e5bd0d98 1183 TopoDS_Shape Copy(const TopoDS_Shape& aShape,
1184 const TopoDS_Builder& aBuilder)
72b7576f 1185 {
1186 // Copies the wholestructure of aShape using aBuilder.
1187 // Stores all thesub-Shapes in an IndexedMap.
1188 TopTools_IndexedMapOfShape theMap;
1189 TopoDS_Iterator It;
1190 Standard_Integer i;
1191 TopoDS_Shape S;
1192 TopLoc_Location Identity;
1193 S = aShape;
1194 S.Location(Identity);
1195 S.Orientation(TopAbs_FORWARD);
1196 theMap.Add(S);
4ee1bdf4 1197 for (i=1; i<= theMap.Extent(); i++) {
72b7576f 1198 for(It.Initialize(theMap(i)); It.More(); It.Next()) {
1199 S=It.Value();
1200 S.Location(Identity);
1201 S.Orientation(TopAbs_FORWARD);
1202 theMap.Add(S);
1203 }
1204 }
1205 }
1206~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1207
1208
dba69de2 1209In the above example, the index *i* is that of the first object not treated in the Map. When *i* reaches the same size as the Map this means that everything has been treated. The treatment consists in inserting in the Map all the sub-objects, if they are not yet in the Map, they are inserted with an index greater than *i*.
72b7576f 1210
1211**Note** that the objects are inserted with a local reference set to the identity and a FORWARD orientation. Only the underlying TShape is of great interest.
1212
dba69de2 1213
72b7576f 1214~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.cpp}
1215 //Create an array to store the copies.
1216 TopTools_Array1OfShapetheCopies(1,theMap.Extent());
1217
1218 // Use a recursivefunction to copy the first element.
1219 void AuxiliaryCopy (Standard_Integer,
e5bd0d98 1220 const TopTools_IndexedMapOfShape &,
1221 TopTools_Array1OfShape &,
1222 const TopoDS_Builder&);
72b7576f 1223
1224 AuxiliaryCopy(1,theMap,theCopies,aBuilder);
1225
1226 // Get the result with thecorrect local reference and orientation.
1227 S = theCopies(1);
1228 S.Location(aShape.Location());
1229 S.Orientation(aShape.Orientation());
1230 return S;
1231~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1232
1233Below is the auxiliary function, which copies the element of rank *i* from the map to the table. This method checks if the object has been copied; if not copied, then an empty copy is performed into the table and the copies of all the sub-elements are inserted by finding their rank in the map.
1234
dba69de2 1235
72b7576f 1236~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.cpp}
1237 void AuxiliaryCopy(Standard_Integer index,
e5bd0d98 1238 const TopTools_IndexedMapOfShapes& sources,
1239 TopTools_Array1OfShape& copies,
1240 const TopoDS_Builder& aBuilder)
72b7576f 1241 {
1242 //If the copy is a null Shape the copy is not done.
1243 if (copies(index).IsNull()) {
1244 copies(index) =sources(index).EmptyCopied();
1245 //Insert copies of the sub-shapes.
1246 TopoDS_Iterator It;
1247 TopoDS_Shape S;
1248 TopLoc_Location Identity;
1249 for(It.Initialize(sources(index)),It.More(), It.Next ()) {
1250 S = It.Value();
1251 S.Location(Identity);
1252 S.Orientation(TopAbs_FORWARD);
1253 AuxiliaryCopy(sources.FindIndex(S),sources,copies,aBuilder);
1254 S.Location(It.Value().Location());S.Orientation(It.Value().Orientation()); aBuilder.Add(copies(index),S);
1255 }
1256 }
1257 }
1258~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1259
1260@subsubsection occt_modat_5_5_1 Wire Explorer
1261
e2b55410 1262*BRepTools_WireExplorer* class can access edges of a wire in their order of connection.
72b7576f 1263
1264For example, in the wire in the image we want to recuperate the edges in the order {e1, e2, e3,e4, e5} :
1265
d6b4d3d0 1266@figure{/user_guides/modeling_data/images/modeling_data_image014.png,"A wire composed of 6 edges.",320}
72b7576f 1267
dba69de2 1268*TopExp_Explorer*, however, recuperates the lines in any order.
72b7576f 1269
72b7576f 1270~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.cpp}
1271 TopoDS_Wire W = ...;
1272 BRepTools_WireExplorer Ex;
1273 for(Ex.Init(W); Ex.More(); Ex.Next()) {
1274 ProcessTheCurrentEdge(Ex.Current());
1275 ProcessTheVertexConnectingTheCurrentEdgeToThePrevious
1276 One(Ex.CurrentVertex());
1277 }
e2b55410 1278~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1279
745c1386 1280@subsection occt_modat_5_6 Storage of shapes
e2b55410 1281
80223385 1282*BRepTools* and *BinTools* packages contain methods *Read* and *Write* allowing to read and write a Shape to/from a stream or a file.
1283The methods provided by *BRepTools* package use ASCII storage format; *BinTools* package uses binary format.
745c1386 1284Each of these methods has two arguments:
1285- a *TopoDS_Shape* object to be read/written;
1286- a stream object or a file name to read from/write to.
1287
1288The following sample code reads a shape from ASCII file and writes it to a binary one:
1289
1290~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.cpp}
1291 TopoDS_Shape aShape;
1292 if (BRepTools::Read (aShape, "source_file.txt")) {
1293 BinTools::Write (aShape, "result_file.bin");
1294 }
1295~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
d6b4d3d0 1296
1a0339b4 1297@section occt_modat_6 Bounding boxes
1298
1299*Bounding box(es) (BndBox(es))* is used in many OCCT algorithms. In general, it is some filter to avoid check of excess interferences between pairs of shapes (check of interferences between BndBoxes is much simpler then between shapes and if BndBoxes do not interfere then there is no point in searching interferences between the corresponding shapes).
1300Generally, BndBoxes can be divided on two main types:
1301 - axis-aligned BndBox (AABB). I.e. the box whose edges are parallel to the axes of World Coordinate System (WCS);
1302 - oriented BndBox (OBB). I.e. not AABB.
1303In fact, every AABB is a specific case of OBB.<br>
1304
1305The image below illustrates the example, when using OBB is better than AABB.
1306
1307@figure{/user_guides/modeling_data/images/modeling_data_image015.png,"Illustrating the problem with AABB.",320}
1308
1309AABBs in this picture are interfered. Therefore, many OCCT-algorithms will spend much time to interfere the shapes. However, if we check OBBs, which are not interfered, then searching of interferences between the shapes will not be necessary. At that, creation and analysis of OBBs takes significantly more time than the analogical operations with AABB.
1310
1311Later in this section, the BndBox having the smallest surface area will be called as <b> optimal </b>.
1312
1313In OCCT, BndBox(es) are described in Bnd package. In general, Bnd_Box class describes AABB, Bnd_OBB class describes OBB. These classes contain the following common methods (this list is not complete; please see the documentation about corresponding class for detailed information):
1314
1315 - SetVoid() and IsVoid(). SetVoid method clears the existing BndBox. IsVoid method indicates whether the BndBox is initialized.
1316 - Enlarge(...). Extends the current BndBox.
1317 - Add(...). Rebuilds the current BndBox in order to cover all previous objects (which it was created from) and the argument of the method.
1318 - IsOut(...). Checks whether the argument is inside/outside of the current BndBox.
1319
1320Also, BRepBndLib class contains methods to provide creation of BndBox (both AABB and OBB) from the complex shape.
1321
1322@subsection occt_modat_6_1 Brief description of some algorithms working with OBB
1323
1324@subsubsection occt_modat_6_1_1 Creation of OBB from set of points
1325
1326The algorithm is described in <a href="http://www.idt.mdh.se/~tla/publ/FastOBBs.pdf">"Fast Computation of Tight Fitting Oriented Bounding Boxes" by Thomas Larsson and Linus Källberg</a>. It includes the following steps:
1327
1328<span>1.</span> Choose \f$ N_{a} (N_{a} \geq 3) \f$ initial axes.<br>
1329<span>2.</span> Project every given point to the every chosen (in item 1) axis. At that, "minimal" and "maximal" points of every axis (i.e. point having minimal and maximal parameter (correspondingly) of the projection to this axis) are chosen. I.e. \f$ 2*N_{a} \f$ points will be held and this set can contain equal points. Later (unless otherwise specified) in this algorithm we will work with these \f$ 2*N_{a} \f$ points only.<br>
1330<span>3.</span> Choose one pair of points among all pairs of "minimal" and "maximal" points of every axis (from item 1), with two furthest points. Let \f$ p_{0} \f$ and \f$ p_{1} \f$ be the "minimal" and "maximal" point of this pair.<br>
1331<span>4.</span> Create an axis \f$ \mathbf{e_{0}}\left \{ \overrightarrow{p_{0}p_{1}} \right \} \f$ (i.e. having direction \f$ \overrightarrow{p_{0}p_{1}} \f$ ).<br>
1332<span>5.</span> Choose the point \f$ p_{2} \f$ (from the set defined in item 2) which is in the maximal distance from the infinite line directed along \f$ \mathbf{e_{0}} \f$ axis.<br>
1333
1334Further, let us consider the triangle \f$ T_{0}\left \langle p_{0}, p_{1}, p_{2} \right \rangle \f$ (i.e. having vertices \f$ p_{0}, p_{1} \f$ and \f$ p_{2} \f$). Namely:
1335
1336<span>6.</span> Create new axes: \f$ \mathbf{e_{1}}\left \{ \overrightarrow{p_{1}p_{2}} \right \} \f$, \f$ \mathbf{e_{2}}\left \{ \overrightarrow{p_{2}p_{0}} \right \} \f$, \f$ \mathbf{n}\left \{ \overrightarrow{\mathbf{e_{0}}} \times \overrightarrow{\mathbf{e_{1}}} \right \} \f$, \f$ \mathbf{m_{0}}\left \{ \overrightarrow{\mathbf{e_{0}}} \times \overrightarrow{\mathbf{n}} \right \} \f$, \f$ \mathbf{m_{1}}\left \{ \overrightarrow{\mathbf{e_{1}}} \times \overrightarrow{\mathbf{n}} \right \} \f$, \f$ \mathbf{m_{2}}\left \{ \overrightarrow{\mathbf{e_{2}}} \times \overrightarrow{\mathbf{n}} \right \} \f$.<br>
1337<span>7.</span> Create OBBs based on the following axis: \f$ \left \{ \mathbf{e_{0}} \vdots \mathbf{m_{0}} \vdots \mathbf{n} \right \} \f$, \f$ \left \{ \mathbf{e_{1}} \vdots \mathbf{m_{1}} \vdots \mathbf{n} \right \} \f$ and \f$ \left \{ \mathbf{e_{2}} \vdots \mathbf{m_{2}} \vdots \mathbf{n} \right \} \f$ . Choose optimal OBB.<br>
1338<span>8.</span> Choose the points \f$ q_{0} \f$ and \f$ q_{1} \f$ (from the set defined in item 2), which are in maximal distance from the plane of the triangle \f$ T_{0} \f$ (from both sides of this plane). At that, \f$ q_{0} \f$ has minimal coordinate along the axis \f$ \mathbf{n} \f$, \f$ q_{1} \f$ has a maximal coordinate.<br>
1339<span>9.</span> Repeat the step 6...7 for the triangles \f$ T_{1}\left \langle p_{0}, p_{1}, q_{0} \right \rangle \f$, \f$ T_{2}\left \langle p_{1}, p_{2}, q_{0} \right \rangle \f$, \f$ T_{3}\left \langle p_{0}, p_{2}, q_{0} \right \rangle \f$, \f$ T_{4}\left \langle p_{0}, p_{1}, q_{1} \right \rangle \f$, \f$ T_{5}\left \langle p_{1}, p_{2}, q_{1} \right \rangle \f$, \f$ T_{6}\left \langle p_{0}, p_{2}, q_{1} \right \rangle \f$.<br>
1340<span>10.</span> Compute the center of OBB and its half dimensions.<br>
1341<span>11.</span> Create OBB using the center, axes and half dimensions.<br>
1342
1343This algorithm is realized in Bnd_OBB::ReBuild(...) method.
1344
1345@subsubsection occt_modat_6_1_2 Creation of OBB based on Axes of inertia
1346
1347The algorithm contains the following steps:
13481. Calculate three inertia axes, which will be the axes of the OBB.
13492. Transform the source object (TopoDS_Shape) into the local coordinate system based on the axes from item 1.
13503. Create an AABB for the shape obtained in the item 2.
13514. Compute the center of AABB and its half dimensions
13525. Transform the center into the WCS
13536. Create OBB using the center, axes and half dimensions.
1354
1355@subsubsection occt_modat_6_1_3 Method IsOut for a point
1356
13571. Project the point to each axis.
13582. Check, whether the absolute value of the projection parameter greater than the correspond half-dimension. In this case, IsOut method will return TRUE.
1359
1360@subsubsection occt_modat_6_1_4 Method IsOut for another OBB
1361
1362According to the <a href="http://www.jkh.me/files/tutorials/Separating%20Axis%20Theorem%20for%20Oriented%20Bounding%20Boxes.pdf">"Separating Axis Theorem for Oriented Bounding Boxes"</a>, it is necessary to check the 15 separating axes: 6 axes of the boxes and 9 are their cross products.<br>
1363The algorithm of analyzing axis \f$ \mathbf{l} \f$ is following:
13641. Compute the "length" according to the formula: \f$ L_{j}=\sum_{i=0}^{2}{H_{i}\cdot \left | \overrightarrow{\mathbf{a_{i}}} \cdot \overrightarrow{\mathbf{l}} \right |} \f$. Here, \f$ \mathbf{a_{i}} \f$ is an i-th axis (X-axis, Y-axis, Z-axis) of j-th BndBox (j=1...2). \f$ H_{i} \f$ is a half-dimension along i-th axis.
13652. If \f$ \left |\overrightarrow{C_{1}C_{2}} \cdot \overrightarrow{\mathbf{l}} \right | > L_{1}+L_{2} \f$ (where \f$ C_{j} \f$ is the center of j-th OBB) then the considered OBBs are not interfered in terms of the axis \f$ \mathbf{l} \f$.
1366
1367If OBBs are not interfered in terms of at least one axis (of 15) then they are not interfered at all.
1368
1369@subsubsection occt_modat_6_1_5 Method Add for point or another BndBox
1370
1371Create new OBB (see the section @ref occt_modat_6_1_1) based on the source point and all vertices of the given BndBoxes.
1372
1373@subsection occt_modat_6_2 Add a shape
1374
1375Method BRepBndLib::AddOBB(...) allows creating BndBox from the complex object (TopoDS_Shape). This method uses both algorithms described in the sections @ref occt_modat_6_1_1 and sections @ref occt_modat_6_1_2.
1376
1377The first algorithm is used if the shape outer shell can be represented by a set of points contained in the shape. Namely, only the following elements are the source of set of points:
1378
1379 - Nodes of triangulation;
1380 - Nodes of Poly_Polygon3D;
1381 - Vertices of edges with linear 3D-curve lying in the planar face;
1382 - Vertices of edges with linear 3D-curve if the source shape does not contain more complex topological structure (e.g. the source shape is a compound of edges);
1383 - Vertices if the source shape does not contain more complex topological structure (e.g. the source shape is a compound of vertices).
1384
1385If required set of points cannot be extracted then the algorithm from section @ref occt_modat_6_1_2 is used for OBB creation.
1386
1387The package BRepBndLib contains the methods BRepBndLib::Add(...), BRepBndLib::AddClose(...) and BRepBndLib::AddOptimal(...) for creation of AABB of a shape. Please see reference manual for detailed information.
1388
1389@subsection occt_modat_6_3 Limitations of algorithm for OBB creation.
1390
13911. The algorithm described in the section @ref occt_modat_6_1_1 works significantly better (finds resulting OBB with less surface area) and faster than the algorithm from the section @ref occt_modat_6_1_2. Nevertheless, (in general) the result returned by both algorithms is not always optimal (i.e. sometimes another OBB exists having less surface area). Moreover, the first method does not allow computing OBB of shapes with complex geometry.
13922. Currently, the algorithm of OBB creation is implemented for objects in 3D-space only.