0024602: Documentation Code Snippets missing sign
[occt.git] / dox / user_guides / modeling_data / modeling_data.md
1 Modeling Data {#occt_user_guides__modeling_data}
2 ========================
3
4 @tableofcontents
5
6 @section occt_modat_0 Introduction
7
8 Modeling Data supplies data structures to represent 2D and 3D geometric models. This manual explains how to use Modeling Data. For advanced information on modeling data, see our offerings on our web site at <a href="http://www.opencascade.org/support/training/">www.opencascade.org/support/training/</a>     
9
10 @section occt_modat_1 Geometry Utilities
11
12 Geometry Utilities provide the following services: 
13   * Creation of shapes by interpolation and approximation 
14   * Direct construction of shapes 
15   * Conversion of curves and surfaces to Bspline curves and surfaces 
16   * Computation of the coordinates of points on 2D and 3D curves 
17   * Calculation of extrema between shapes. 
18
19 @subsection occt_modat_1_1 Interpolations and Approximations
20
21 In 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. This component provides both high and low level services to approximate or interpolate points into curves and surfaces. The lower level services allow performing parallel approximation of groups of points into groups of Bezier or B-spline curves. 
22
23 @subsubsection occt_modat_1_1_1 Analysis of a set of points
24
25 The class *PEquation* from  *GProp* package allows analyzng 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. 
26
27 @subsubsection occt_modat_1_1_2 Basic Interpolation and Approximation
28
29 Packages *Geom2dAPI* and *GeomAPI* provide simple methods for approximation and interpolation with minimal programming
30
31 #### 2D Interpolation
32
33 The 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. 
34
35 #### 3D Interpolation
36
37 The 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. 
38
39 @image html /user_guides/modeling_data/images/modeling_data_image003.png "Approximation of a BSpline from scattered points"
40 @image latex /user_guides/modeling_data/images/modeling_data_image003.png "Approximation of a BSpline from scattered points"
41
42 This class may be instantiated as follows:
43 ~~~~~ 
44 GeomAPI_Interpolate Interp(Points); 
45 ~~~~~
46
47 From this object, the BSpline curve may be requested as follows: 
48 ~~~~~
49 Handle(Geom_BSplineCurve) C = Interp.Curve(); 
50 ~~~~~
51
52 #### 2D Approximation
53
54 The 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. 
55
56 #### 3D Approximation
57
58 The 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. 
59
60 The 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: 
61
62 ~~~~~
63 GeomAPI_PointsToBSpline 
64 Approx(Points,DegMin,DegMax,Continuity, Tol); 
65 ~~~~~
66
67 From this object, the BSpline curve may be requested as follows: 
68
69 ~~~~~
70 Handle(Geom_BSplineCurve) K = Approx.Curve(); 
71 ~~~~~
72
73 #### Surface Approximation 
74
75 The class **PointsToBSplineSurface** from GeomAPI package allows building a BSpline surface, which approximates or interpolates a set of points. 
76
77 @subsubsection occt_modat_1_1_3 Advanced Approximation
78
79 Packages *AppDef* and *AppParCurves* provide low-level functions, allowing more control over the approximations.
80
81 #### Approximation by multiple point constraints
82
83 *AppDef* package provides low-level tools to allow parallel approximation of groups of points into Bezier or B-Spline curves using multiple point constraints. 
84
85 The following low level services are provided: 
86
87 * Definition of an array of point constraints:
88
89   The class *MultiLine* allows defining a given number of multipoint constraints in order to build the multi-line, multiple lines passing through ordered multiple point constraints. 
90
91   @image html /user_guides/modeling_data/images/modeling_data_image004.png "Definition of a MultiLine using Multiple Point Constraints"
92   @image latex /user_guides/modeling_data/images/modeling_data_image004.png "Definition of a MultiLine using Multiple Point Constraints"
93
94   In this image:
95   * *Pi*, *Qi*, *Ri* ... *Si* can be 2D or 3D points. 
96   * Defined as a group: *Pn*, *Qn*, *Rn,* ... *Sn* form a MultipointConstraint. They possess the same passage, tangency and curvature constraints. 
97   * *P1*, *P2*, ... *Pn*, or the *Q*, *R*, ... or *S* series represent the lines to be approximated. 
98
99 * Definition of a set of point constraints:
100
101   The class **MultiPointConstraint** allows defining a multiple point constraint and  computing the approximation of sets of points to several curves. 
102
103 * Computation of an approximation of a Bezier curve from a set of points: 
104
105   The class *Compute* allows making an approximation of a set of points to a Bezier curve 
106
107 * Computation of an approximation of a BSpline curve from a set of points: 
108
109 The class **BSplineCompute** allows making an approximation of a set of points to a BSpline curve. 
110
111 * Definition of Variational Criteria:
112
113 The 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. 
114
115 #### Approximation by parametric or geometric constraints
116
117
118 *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. 
119
120 The algorithms used include: 
121 - the least squares method 
122 - a search for the best approximation within a given tolerance value. 
123
124 The following low-level services are provided: 
125
126 * Association of an index to an object:
127
128 The class *ConstraintCouple* allows you associating an index to an object to compute faired curves using *AppDef_TheVariational*.
129
130 * Definition of a set of approximations of Bezier curves: 
131
132 The class *MultiCurve* allows defining the approximation of a multi-line made up of multiple Bezier curves.
133
134 * Definition of a set of approximations of BSpline curves:
135
136 The class *MultiBSpCurve* allows defining the approximation of a multi-line made up of multiple BSpline curves.
137  
138 * Definition of points making up a set of point constraints
139
140 The class *MultiPoint* allows defining groups of 2D or 3D points making up a multi-line. 
141
142 @subsection occt_modat_1_2 Direct Construction
143
144 Direct 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. 
145
146 For 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. 
147
148 @subsubsection occt_modat_1_2_1 Non-persistent entities
149
150 The following algorithms used to build entities from non-persistent *gp* entities are provided by *gce* package. 
151 - 2D line parallel to another at a distance, 
152 - 2D line parallel to another passing through a point, 
153 - 2D circle passing through two points, 
154 - 2D circle parallel to another at a distance, 
155 - 2D circle parallel to another passing through a point, 
156 - 2D circle passing through three points, 
157 - 2D circle from a center and a radius, 
158 - 2D hyperbola from five points, 
159 - 2D hyperbola from a center and two apexes, 
160 - 2D ellipse from five points, 
161 - 2D ellipse from a center and two apexes, 
162 - 2D parabola from three points, 
163 - 2D parabola from a center and an apex, 
164 - line parallel to another passing through a point, 
165 - line passing through two points, 
166 - circle coaxial to another passing through a point, 
167 - circle coaxial to another at a given distance, 
168 - circle passing through three points, 
169 - circle with its center, radius, and normal to the plane, 
170 - circle with its axis (center + normal), 
171 - hyperbola with its center and two apexes, 
172 - ellipse with its center and two apexes, 
173 - plane passing through three points, 
174 - plane from its normal, 
175 - plane parallel to another plane at a given distance, 
176 - plane parallel to another passing through a point, 
177 - plane from an array of points, 
178 - cylinder from a given axis and a given radius, 
179 - cylinder from a circular base, 
180 - cylinder from three points, 
181 - cylinder parallel to another cylinder at a given distance, 
182 - cylinder parallel to another cylinder passing through a point, 
183 - cone from four points, 
184 - cone from a given axis and two passing points, 
185 - cone from two points (an axis) and two radii, 
186 - cone parallel to another at a given distance, 
187 - cone parallel to another passing through a point, 
188 - all transformations (rotations, translations, mirrors,scaling transformations, etc.).
189
190 Each class from *gp* package, such as *Circ, Circ2d, Mirror, Mirror2d*, etc., has the corresponding *MakeCirc, MakeCirc2d, MakeMirror, MakeMirror2d*, etc. class from *gce* package. 
191
192 It is possible to create a point using a *gce* package class, then question it to recover the corresponding *gp* object. 
193
194 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.cpp}
195   gp_Pnt2d Point1,Point2; 
196   ...
197   //Initialization of Point1 and Point2 
198   gce_MakeLin2d L = gce_MakeLin2d(Point1,Point2); 
199   if (L.Status() == gce_Done() ){ 
200     gp_Lin2d l = L.Value(); 
201   }
202 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
203
204 This 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: 
205
206 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.cpp}
207 gp_Lin2d l = gce_MakeLin2d(Point1,Point2); 
208 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
209
210 @subsubsection occt_modat_1_2_2 Persistent entities
211
212 *GC* and *GCE2d* packages provides an implementation of algorithms used to build entities from *Geom* and *Geom2D* packages. They implement the same algorithms as the *gce* package but create **persistent** entities, and also contain algorithms for trimmed surfaces and curves. The following algorithms are available: 
213 - arc of a circle trimmed by two points, 
214 - arc of a circle trimmed by two parameters, 
215 - arc of a circle trimmed by one point and one parameter, 
216 - arc of an ellipse from an ellipse trimmed by two points, 
217 - arc of an ellipse from an ellipse trimmed by two parameters, 
218 - arc of an ellipse from an ellipse trimmed by one point and one parameter, 
219 - arc of a parabola from a parabola trimmed by two points, 
220 - arc of a parabola from a parabola trimmed by two parameters, 
221 - arc of a parabola from a parabola trimmed by one point and one parameter, 
222 - arc of a hyperbola from a hyperbola trimmed by two points, 
223 - arc of a hyperbola from a hyperbola trimmed by two parameters, 
224 - arc of a hyperbola from a hyperbola trimmed by one point and one parameter, 
225 - segment of a line from two points, 
226 - segment of a line from two parameters, 
227 - segment of a line from one point and one parameter, 
228 - trimmed cylinder from a circular base and a height, 
229 - trimmed cylinder from three points, 
230 - trimmed cylinder from an axis, a radius, and a height, 
231 - trimmed cone from four points, 
232 - trimmed cone from two points (an axis) and a radius, 
233 - trimmed cone from two coaxial circles. 
234
235 Each class from *GCE2d* package, such as *Circle, Ellipse, Mirror*, etc., has the corresponding *MakeCircle, MakeEllipse, MakeMirror*, etc. class from *Geom2d* package. 
236 Besides, the class *MakeArcOfCircle* returns an object of type *TrimmedCurve* from *Geom2d*. 
237
238 Each class from *GC* package, such as *Circle, Ellipse, Mirror*, etc., has the corresponding *MakeCircle, MakeEllipse, MakeMirror*, etc. class from *Geom* package. 
239 The following classes return objects of type *TrimmedCurve* from *Geom*: 
240 - *MakeArcOfCircle*
241 - *MakeArcOfEllipse* 
242 - *MakeArcOfHyperbola* 
243 - *MakeArcOfParabola* 
244 - *MakeSegment* 
245
246 @subsection occt_modat_1_3 Conversion to and from BSplines
247
248 The following algorithms to convert geometric curves or surfaces into their BSpline or Bezier equivalents are provided by *GeomConvert*, *Geom2dConvert* and *Convert* packages: 
249 - Conversion of a conic into a rational BSpline. 
250 - Conversion of an elementary surface into a rational Bspline. 
251 - Conversion of a BSpline or Bezier curve into two or more Bezier curves or surfaces. 
252 - Conversion of a BSpline curve or surface into two or more BSplinecurves or surfaces with constraints on continuity. 
253 - Conversion of a set of joining Bezier curves into a BSplinecurve. 
254 - Conversion of a polynomial representation into a BSpline curve. 
255
256 @subsection occt_modat_1_4 Points on Curves
257
258 The following characteristic points exist on parameterized curves in 3d space: 
259 - points equally spaced on a curve, 
260 - points distributed along a curve with equal chords, 
261 - a point at a given distance from another point on a curve. 
262
263 *GCPnts* package provides algorithms to calculate such points: 
264 - *AbscissaPoint* calculates a point on a curve at a given distance from another point on the curve.
265 - *UniformAbscissa* calculates a set of points at a given abscissa on a curve.
266 - *UniformDeflection* calculates a set of points at maximum constant deflection between the curve and the polygon that results from the computed points. 
267
268 ### Example: Visualizing a curve. 
269
270
271 Let 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: 
272
273 **2D case :** 
274 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.cpp}
275   Handle(Geom2d_Curve) mycurve = ... ; 
276   Geom2dAdaptor_Curve C (mycurve) ; 
277 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
278
279 **3D case :** 
280 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.cpp}
281   Handle(Geom_Curve) mycurve = ... ; 
282   GeomAdaptor_Curve C (mycurve) ; 
283 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
284
285 The algorithm is then constructed with this object:
286
287 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.cpp}
288   GCPnts_UniformDeflection myAlgo () ; 
289   Standard_Real Deflection = ... ; 
290   myAlgo.Initialize ( C , Deflection ) ; 
291   if ( myAlgo.IsDone() ) 
292   {
293     Standard_Integer nbr = myAlgo.NbPoints() ; 
294     Standard_Real param ; 
295      for ( Standard_Integer i = 1 ; i <= nbr ; i++ ) 
296     { 
297       param = myAlgo.Parameter (i) ; 
298       ...
299     } 
300   }
301 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
302
303
304 @subsection occt_modat_1_5 Extrema
305
306 The classes to calculate the minimum distance between points, curves, and surfaces in 2d and 3d are provided by *GeomAPI* and *Geom2dAPI* packages.
307
308 These packages calculate the extrema of distance between: 
309 - point and a curve, 
310 - point and a surface, 
311 - two curves, 
312 - a curve and a surface, 
313 - two surfaces. 
314
315 @subsubsection occt_modat_1_5_1 Extrema between Curves
316
317 The *Geom2dAPI_ExtremaCurveCurve* class allows calculation of all extrema between two 2D geometric curves. Extrema are the lengths of the segments orthogonal to two curves. 
318
319 The *GeomAPI_ExtremaCurveCurve* class allows calculation of all extrema between two 3D geometric curves. Extrema are the lengths of the segments orthogonal to two curves. 
320
321 @subsubsection occt_modat_1_5_2 Extrema between Curve and Surface
322
323 The *GeomAPI_ExtremaCurveSurface* class allows calculation of all  extrema between a 3D curve and a surface. Extrema are the lengths of the segments orthogonal to the curve and the surface. 
324
325 @subsubsection occt_modat_1_5_3 Extrema between Surfaces
326
327 The *GeomAPI_ExtremaSurfaceSurface* class allows calculation of all extrema between two surfaces. Extrema are the lengths of the segments orthogonal to two surfaces. 
328
329 @section occt_modat_2 2D Geometry
330
331 *Geom2d* package defines geometric objects in 2dspace. All  geometric entities are STEP processed. The objects are non-persistent and are handled by reference. The following objects are available: 
332 - point, 
333 - Cartesian point, 
334 - vector,
335 - direction, 
336 - vector with magnitude, 
337 - axis, 
338 - curve,
339 - line, 
340 - conic: circle, ellipse, hyperbola, pparabola, 
341 - rounded curve: trimmed curve, NURBS curve, Bezier curve. 
342 - offset curve
343
344 Before creating a geometric object, it is necessary to decide how the object is handled. 
345 The 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. 
346 If 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: 
347 - handled by reference and 
348 - handled by value. 
349
350 @section occt_modat_3 3D Geometry
351
352 The *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. The following non-persistent and reference-handled objects are available: 
353 - Point 
354 - Cartesian point 
355 - Vector
356 - Direction
357 - Vector with magnitude 
358 - Axis
359 - Curve
360 - Line 
361 - Conic: circle, ellipse, hyperbola, parabola 
362 - Offset curve
363 - Elementary surface: plane, cylinder, cone, sphere, torus
364 - Bounded curve: trimmed curve, NURBS curve, Bezier curve
365 - Bounded surface: rectangular trimmed surface, NURBS surface,Bezier surface
366 - Swept surface: surface of linear extrusion, surface of revolution
367 - Offset surface. 
368
369 If 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: 
370 - handled by reference and 
371 - handled by value. 
372
373 @subsection occt_modat_4 Local Properties of Curves and Surfaces
374
375 Packages **GeomLProp**, **Geom2dLProp**  provide algorithms calculating the local properties of curves and surfaces
376
377 A curve (for one parameter) has the following local properties: 
378 - Point 
379 - Derivative
380 - Tangent 
381 - Normal
382 - Curvature
383 - Center of curvature. 
384
385 A surface (for two parameters U and V) has the following local properties: 
386 - point
387 - derivative for U and V)
388 - tangent line (for U and V)
389 - normal
390 - max curvature 
391 - min curvature 
392 - main directions of curvature
393 - mean curvature
394 - Gaussian curvature
395
396 The following methods are available:
397 * *CLProps* - calculates the local properties of a curve (tangency, curvature,normal); 
398 * *CurAndInf2d* - calculates the maximum and minimum curvatures and the inflection points of 2d curves; 
399 * *SLProps* - calculates the local properties of a surface (tangency, the normal and curvature). 
400 * *Continuity* - calculates regularity at the junction of two curves. 
401
402 Note 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. 
403
404
405 @section occt_modat_5 Topology
406
407 Open CASCADE Technology Topology allows accessing and manipulating objects data 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. 
408
409 To provide its descriptions, OCCT abstract topology offers the following services: 
410 - Keeping track of Location of shapes 
411 - Naming shapes, sub-shapes, their orientations and states 
412 - Manipulating shapes and sub-shapes 
413 - Exploring topological data structures 
414 - Using lists and maps of shapes 
415
416
417 @subsection occt_modat_5_1  Shape Location
418
419 A local coordinate system can be viewed as either of the following: 
420 - A right-handed trihedron with an origin and three orthonormal vectors. The **gp_Ax2** package corresponds to this definition. 
421 - A transformation of a +1 determinant, allowing the transformation of coordinates between local and global references frames. This corresponds to the **gp_Trsf**. 
422
423 *TopLoc* package distinguishes two notions: 
424 - *TopLoc_Datum3D* class provides the elementary reference coordinate, represented by a right-handed orthonormal system of axes or by a right-handed unitary transformation. 
425 - *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. 
426
427 @image html /user_guides/modeling_data/images/modeling_data_image005.png "Structure of TopLoc_Location"
428 @image latex /user_guides/modeling_data/images/modeling_data_image005.png "Structure of TopLoc_Location"
429
430 Two 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. 
431
432 For example, consider three elementary coordinates: 
433 R1, R2, R3 
434 The composite coordinates are: 
435 C1 = R1  * R2, 
436 C2 = R2  * R3 
437 C3 = C1  * R3 
438 C4 = R1  * C2 
439
440 **NOTE** C3 and C4 are equal because they are both R1 * R2 * R3.  
441
442 The TopLoc package is chiefly targeted at the topological data structure, but it can be used for other purposes. 
443
444 Change of coordinates
445 ---------------------
446
447 *TopLoc_Datum3D* class represents a change of elementary coordinates. Such changes must be shared so this class inherits from *MMgt_TShared*. The coordinate is represented by a transformation *gp_Trsfpackage*. This transformation has no scaling factor. 
448
449
450 @subsection occt_modat_5_2 Naming shapes, sub-shapes, their orientation and state
451
452 The **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: 
453 - Topological type (TopAbs_ShapeEnum) 
454 - Orietation (TopAbs_Orientation) 
455 - StateTopAbs_State) 
456
457
458 @subsubsection occt_modat_5_2_1 Topological types
459
460 TopAbs contains the *TopAbs_ShapeEnum* enumeration,which lists the different topological types: 
461 - COMPOUND - a group of any type of topological objects.
462 - COMPSOLID - a composite solid is a set of solids connected by their faces. It expands the notions of WIRE and SHELL to solids.
463 - SOLID - a part of space limited by shells. It is three dimensional.
464 - SHELL - a set of faces connected by their edges. A shell can be open or closed.
465 - 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.
466 - 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.
467 - EDGE - a topological element corresponding to a restrained curve. An edge is generally limited by vertices. It has one dimension.
468 - VERTEX - a topological element corresponding to a point. It has zero dimension.
469 - SHAPE - a generic term covering all of the above.
470
471 A 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. 
472
473 The 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. 
474 @image html /user_guides/modeling_data/images/modeling_data_image006.png "ShapeEnum"
475 @image latex /user_guides/modeling_data/images/modeling_data_image006.png "ShapeEnum"
476
477 @subsubsection occt_modat_5_2_2 Orientation
478
479 The 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: 
480 - Curve limited by a vertex. 
481 - Surface limited by an edge. 
482 - Space limited by a face. 
483
484 In 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**. 
485
486 For 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. 
487
488 For 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. 
489
490 For a space limited by a face the default region is found on the negative side of the normal to the surface. 
491
492 Based 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. 
493
494 | Orientation | Description |
495 | :--------- | :--------------------------------- |
496 | FORWARD       | The interior is the default region. |
497 | REVERSED      | The interior is the region complementary to the default. |
498 | INTERNAL      | The interior includes both regions. The boundary lies inside the material. For example a surface inside a solid. |
499 | EXTERNAL      | The interior includes neither region. The boundary lies outside the material. For  example an edge in a wire-frame model. |
500
501 @image html /user_guides/modeling_data/images/modeling_data_image007.png "Four Orientations"
502 @image latex /user_guides/modeling_data/images/modeling_data_image007.png "Four Orientations"
503
504 The 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 - with the intersection vertex as the boundary. Thus an orientation can be associated with an intersection vertex as in the following figure: 
505
506 | Orientation | Association |
507 | :-------- | :-------- |
508 | FORWARD       | Entering |
509 | REVERSED      | Exiting |
510 | INTERNAL      | Touching from inside |
511 | EXTERNAL      | Touching from outside |
512
513 @image html /user_guides/modeling_data/images/modeling_data_image008.png "Four orientations of intersection vertices"
514 @image latex /user_guides/modeling_data/images/modeling_data_image008.png "Four orientations of intersection vertices"
515
516
517 Along with the Orientation enumeration the *TopAbs* package defines four methods: 
518
519 @subsubsection occt_modat_5_2_3 State
520
521 The **TopAbs_State** enumeration described the position of a vertex or a set of vertices with respect to a region. There are four terms: 
522
523 |Position  | Description |
524 | :------ | :------- |
525 |IN        | The point is interior. |
526 |OUT       | The point is exterior. |
527 |ON        | The point is on the boundary(within tolerance). |
528 |UNKNOWN   | The state of the point is indeterminate. |
529
530 The 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. 
531
532 @image html /user_guides/modeling_data/images/modeling_data_image009.png "The four states"
533 @image latex /user_guides/modeling_data/images/modeling_data_image009.png "The four states"
534
535 The 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. 
536
537 @image html /user_guides/modeling_data/images/modeling_data_image010.png  "State specifies the parts of an edge intersecting a face"
538 @image latex /user_guides/modeling_data/images/modeling_data_image010.png  "State specifies the parts of an edge intersecting a face"
539
540 @subsection occt_modat_5_3 Manipulating shapes and sub-shapes
541
542 The *TopoDS* package describes the topological data structure with the following characteristics: 
543 - reference to an abstract shape with neither orientation nor location. 
544 - Access to the data structure through the tool classes. 
545
546 As 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. 
547
548 OCCT 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. 
549
550 Listing 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. 
551
552 The 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. 
553 - An orientation tells how the referenced shape is used in a boundary (*Orientation* from *TopAbs*). 
554 - A local reference coordinate (*Location* from *TopLoc*) allows referencing a shape at a position different from that of its definition. 
555
556 The **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. 
557
558 The **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. 
559
560 The class representing the underlying abstract shape is never referenced directly. The *TopoDS_Shape* class is always used to refer to it. 
561
562 The 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. 
563
564 @image html /user_guides/modeling_data/images/modeling_data_image011.png "Structure of a shell formed from two faces"
565 @image latex /user_guides/modeling_data/images/modeling_data_image011.png "Structure of a shell formed from two faces"
566
567 @image html /user_guides/modeling_data/images/modeling_data_image012.png "Data structure of the above shell"
568 @image latex /user_guides/modeling_data/images/modeling_data_image012.png "Data structure of the above shell"
569
570 In 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. 
571
572 The wire TW1 references the edges from TE1 to TE4; TW2 references from TE4 to TE7. 
573
574 The 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). 
575
576 **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. 
577
578 Two 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. 
579
580 The 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. 
581
582 The 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. 
583
584 The three references from *TSh2* to the underlying face *TFcyl* have associated local coordinate systems, which correspond to the successive positions of the hole. 
585 @image html /user_guides/modeling_data/images/modeling_data_image013.png "Data structure containing two versions of a solid"
586 @image latex /user_guides/modeling_data/images/modeling_data_image013.png "Data structure containing two versions of a solid"
587
588 Classes inheriting TopoDS_Shape
589 ------------------------------
590 *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. 
591
592  *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. 
593
594 The 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. 
595
596 *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. 
597
598 *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. 
599
600 *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*. 
601
602 Although 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*. 
603
604 There 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. 
605
606 The 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. 
607
608
609 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.cpp}
610   #include <TopoDS_Vertex.hxx> 
611   #include <TopoDS_Edge.hxx> 
612   #include <TopoDS_Shape.hxx> 
613
614
615   void ProcessEdge(const TopoDS_Edge&); 
616
617   void Process(const TopoDS_Shape& aShape) { 
618     if (aShape.Shapetype() == TopAbs_VERTEX) { 
619       TopoDS_Vertex V; 
620       V = TopoDS::Vertex(aShape); // Also correct 
621       TopoDS_Vertex V2 = aShape; // Rejected by the compiler 
622       TopoDS_Vertex V3 = TopoDS::Vertex(aShape); // Correct 
623     } 
624     else if (aShape.ShapeType() == TopAbs_EDGE){ 
625       ProcessEdge(aShape) ; // This is rejected 
626       ProcessEdge(TopoDS::Edge(aShape)) ; // Correct 
627     } 
628     else { 
629       cout <<"Neither a vertex nor an edge ?"; 
630       ProcessEdge(TopoDS::Edge(aShape)) ; 
631       // OK for compiler but an exception will be raised at run-time 
632     }
633   } 
634 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
635
636
637
638 @subsection occt_modat_5_4 Exploration of Topological Data Structures
639
640 The *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. 
641
642 The TopExp package provides the class *TopExp_Explorer* to find all sub-objects of a given type.  An explorer is built with: 
643 - The shape to be explored. 
644 - The type of shapes to be found e.g. VERTEX, EDGE with the exception of SHAPE, which is not allowed. 
645 - 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. 
646
647
648
649 The 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*: 
650
651
652 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.cpp}
653   void test() { 
654     TopoDS_Shape S; 
655     TopExp_Explorer Ex; 
656     for (Ex.Init(S,TopAbs_FACE); Ex.More(); Ex.Next()) { 
657       ProcessFace(Ex.Current()); 
658     } 
659   } 
660 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
661
662 Find all the vertices which are not in an edge 
663
664 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.cpp}
665 for (Ex.Init(S,TopAbs_VERTEX,TopAbs_EDGE); ...) 
666 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
667
668
669 Find all the faces in a SHELL, then all the faces not in a SHELL: 
670
671
672 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.cpp}
673   void test() { 
674     TopExp_Explorer Ex1, Ex2; 
675     TopoDS_Shape S; 
676     for (Ex1.Init(S,TopAbs_SHELL);Ex1.More(); Ex1.Next()){ 
677       // visit all shells 
678       for (Ex2.Init(Ex1.Current(),TopAbs_FACE);Ex2.More(); 
679         Ex2.Next()){ 
680         //visit all the faces of the current shell 
681         ProcessFaceinAshell(Ex2.Current()); 
682         ... 
683       } 
684     } 
685     for(Ex1.Init(S,TopAbs_FACE,TopAbs_SHELL);Ex1.More(); Ex1.Next()){ 
686       // visit all faces not ina shell. 
687       ProcessFace(Ex1.Current()); 
688     }
689   }
690 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
691
692 The 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. 
693
694 The *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. 
695
696 **Example** 
697 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.cpp}
698   void TopExp::MapShapes (const TopoDS_Shape& S, 
699               const TopAbs_ShapeEnum T, 
700               TopTools_IndexedMapOfShape& M) 
701   { 
702     TopExp_Explorer Ex(S,T); 
703     while (Ex.More()) { 
704       M.Add(Ex.Current()); 
705       Ex.Next(); 
706     }
707   }
708 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
709
710 In the following example all  faces and all  edges of an object are drawn in accordance with the following rules: 
711 - The faces are represented by a network of *NbIso* iso-parametric lines with *FaceIsoColor* color. 
712 - The edges are drawn in a color, which indicates the number of faces sharing the edge:
713         - *FreeEdgeColor* for edges, which do not belong to a face (i.e. wireframe element). 
714         - *BorderEdgeColor* for an edge belonging to a single face. 
715         - *SharedEdgeColor* for an edge belonging to more than one face. 
716 - The methods *DrawEdge* and *DrawFaceIso* are also available to display individual edges and faces. 
717
718 The following steps are performed: 
719 1. 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. 
720 2. Exploring the faces. Each face is drawn. 
721 3. Exploring the edges and for each of them increment the counter of faces in the array. 
722 4. From the Map of edges, drawing each edge with the color corresponding to the number of faces. 
723
724 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.cpp}
725   void DrawShape ( const TopoDS_Shape& aShape, 
726   const Standard_Integer nbIsos, 
727   const Color FaceIsocolor, 
728   const Color FreeEdgeColor, 
729   const Color BorderEdgeColor, 
730   const Color SharedEdgeColor) 
731   { 
732     // Store the edges in aMap. 
733     TopTools_IndexedMapOfShape edgemap; 
734     TopExp::MapShapes(aShape,TopAbs_EDGE,edgeMap); 
735     // Create an array set to zero. 
736     TColStd_Array1OfInteger faceCount(1,edgeMap.Extent()); 
737     faceCount.Init (0); 
738     // Explore the faces. 
739     TopExp_Explorer expFace(aShape,TopAbs_FACE); 
740     while (expFace.More()) { 
741       //Draw the current face. 
742       DrawFaceIsos(TopoDS::Face(expFace.Current()),nbIsos,FaceIsoColor); 
743       // Explore the edges ofthe face. 
744       TopExp_Explorer expEdge(expFace.Current(),TopAbs_EDGE); 
745       while (expEdge.More()) { 
746         //Increment the face count for this edge. 
747         faceCount(edgemap.FindIndex(expEdge.Current()))++; 
748         expEdge.Next(); 
749       } 
750       expFace.Next(); 
751     } 
752     //Draw the edges of theMap 
753     Standard_Integer i; 
754     for (i=1;i<=edgemap.Extent();i++) { 
755       switch (faceCount(i)) { 
756         case 0 : 
757         DrawEdge(TopoDS::Edge(edgemap(i)),FreeEdgeColor); 
758         break; 
759         case 1 : 
760         DrawEdge(TopoDS::Edge(edgemap(i)),BorderEdgeColor); 
761         break; 
762         default : 
763         DrawEdge(TopoDS::Edge(edgemap(i)),SharedEdgeColor); 
764         break; 
765       }
766     } 
767   } 
768 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
769
770 @subsection occt_modat_5_5 Lists and Maps of Shapes
771
772 **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*. 
773
774
775 * *TopTools_Array1OfShape, HArray1OfShape* -  Instantiation of the *TCollection_Array1* and *TCollection_HArray1* with *TopoDS_Shape*. 
776 * *TopTools_SequenceOfShape* - Instantiation of the *TCollection_Sequence* with *TopoDS_Shape*. 
777 * *TopTools_MapOfShape* - Instantiation of the *TCollection_Map*. Allows the construction of sets of shapes. 
778 * *TopTools_IndexedMapOfShape* -        Instantiation of the *TCollection_IndexedMap*. Allows the construction of tables of shapes and other data structures. 
779
780 With a *TopTools_Map*, a set of references to Shapes can be kept without duplication. 
781 The following example counts the size of a data structure as a number of *TShapes*. 
782
783
784 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.cpp}
785   #include <TopoDS_Iterator.hxx> 
786   Standard_Integer Size(const TopoDS_Shape& aShape) 
787   { 
788     // This is a recursive method. 
789     // The size of a shape is1 + the sizes of the subshapes. 
790     TopoDS_Iterator It; 
791     Standard_Integer size = 1; 
792     for (It.Initialize(aShape);It.More();It.Next()) { 
793       size += Size(It.Value()); 
794     } 
795     return size; 
796   } 
797 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
798
799 This program is incorrect if there is sharing in the data structure. 
800
801 Thus 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: 
802
803
804 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.cpp}
805   #include <TopoDS_Iterator.hxx> 
806   #include <TopTools_MapOfShape.hxx> 
807
808   void MapShapes(const TopoDS_Shape& aShape, 
809   TopTools_MapOfShape& aMap)
810   { 
811     //This is a recursive auxiliary method. It stores all subShapes of aShape in a Map.
812     if (aMap.Add(aShape)) { 
813       //Add returns True if aShape was not already in the Map. 
814       TopoDS_Iterator It; 
815       for (It.Initialize(aShape);It.More();It.Next()){ 
816         MapShapes(It.Value(),aMap); 
817       } 
818     } 
819   }
820
821   Standard_Integer Size(const TopoDS_Shape& aShape) 
822   { 
823     // Store Shapes in a Mapand return the size. 
824     TopTools_MapOfShape M; 
825     MapShapes(aShape,M); 
826     return M.Extent();
827   }
828 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
829
830 **Note** For more details about Maps please, refer to the TCollection documentation. (Foundation Classes Reference Manual) 
831
832 The 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: 
833 - All Shapes in the structure are put into an *IndexedMap*. 
834 - A table of Shapes is created in parallel with the map to receive the copies. 
835 - The structure is copied using the auxiliary recursive function,which copies from the map to the array. 
836
837 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.cpp}
838   #include <TopoDS_Shape.hxx> 
839   #include <TopoDS_Iterator.hxx> 
840   #include <TopTools_IndexedMapOfShape.hxx> 
841   #include <TopTools_Array1OfShape.hxx> 
842   #include <TopoDS_Location.hxx> 
843
844   TopoDS_Shape Copy(const TopoDS_Shape& aShape, 
845   const TopoDS_Builder& aBuilder) 
846   { 
847     // Copies the wholestructure of aShape using aBuilder. 
848     // Stores all thesub-Shapes in an IndexedMap. 
849     TopTools_IndexedMapOfShape theMap; 
850     TopoDS_Iterator It; 
851     Standard_Integer i; 
852     TopoDS_Shape S; 
853     TopLoc_Location Identity; 
854     S = aShape; 
855     S.Location(Identity); 
856     S.Orientation(TopAbs_FORWARD); 
857     theMap.Add(S); 
858     for (i=1; i<= theMap.Extent(); i++) { 
859       for(It.Initialize(theMap(i)); It.More(); It.Next()) { 
860         S=It.Value(); 
861         S.Location(Identity); 
862         S.Orientation(TopAbs_FORWARD); 
863         theMap.Add(S); 
864       }
865     } 
866   } 
867 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
868
869
870 In 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*. 
871
872 **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.
873
874
875 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.cpp}
876   //Create an array to store the copies. 
877   TopTools_Array1OfShapetheCopies(1,theMap.Extent());
878
879   // Use a recursivefunction to copy the first element. 
880   void AuxiliaryCopy (Standard_Integer, 
881   const TopTools_IndexedMapOfShape &, 
882   TopTools_Array1OfShape &, 
883   const TopoDS_Builder&); 
884
885   AuxiliaryCopy(1,theMap,theCopies,aBuilder); 
886
887   // Get the result with thecorrect local reference and orientation. 
888   S = theCopies(1); 
889   S.Location(aShape.Location()); 
890   S.Orientation(aShape.Orientation()); 
891   return S; 
892 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
893
894 Below 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. 
895
896
897 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.cpp}
898   void AuxiliaryCopy(Standard_Integer index, 
899   const TopTools_IndexedMapOfShapes& sources, 
900   TopTools_Array1OfShape& copies, 
901   const TopoDS_Builder& aBuilder) 
902   { 
903     //If the copy is a null Shape the copy is not done. 
904     if (copies(index).IsNull()) { 
905       copies(index) =sources(index).EmptyCopied(); 
906       //Insert copies of the sub-shapes. 
907       TopoDS_Iterator It; 
908       TopoDS_Shape S; 
909       TopLoc_Location Identity; 
910       for(It.Initialize(sources(index)),It.More(), It.Next ()) {
911         S = It.Value(); 
912         S.Location(Identity); 
913         S.Orientation(TopAbs_FORWARD); 
914         AuxiliaryCopy(sources.FindIndex(S),sources,copies,aBuilder); 
915         S.Location(It.Value().Location());S.Orientation(It.Value().Orientation()); aBuilder.Add(copies(index),S);
916       }
917     }
918   }
919 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
920
921 @subsubsection occt_modat_5_5_1 Wire Explorer
922
923 BRepTools_WireExplorer class can access edges of a wire in their order of connection. 
924
925 For example, in the wire in the image we want to recuperate the edges in the order {e1, e2, e3,e4, e5} :
926
927 @image html /user_guides/modeling_data/images/modeling_data_image014.png "A wire composed of 6 edges."
928 @image latex /user_guides/modeling_data/images/modeling_data_image014.png "A wire composed of 6 edges.
929
930 *TopExp_Explorer*, however, recuperates the lines in any order.
931  
932 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.cpp}
933   TopoDS_Wire W = ...; 
934   BRepTools_WireExplorer Ex; 
935   for(Ex.Init(W); Ex.More(); Ex.Next()) { 
936     ProcessTheCurrentEdge(Ex.Current()); 
937     ProcessTheVertexConnectingTheCurrentEdgeToThePrevious 
938     One(Ex.CurrentVertex()); 
939   } 
940 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~