0024854: Merge of Technical Overview from opencascade.org site into the documentation
[occt.git] / dox / technical_overview / technical_overview.md
1 Technical Overview {#technical_overview}
2 ========================================
3
4 @tableofcontents
5
6 Open CASCADE Technology is an object-oriented C++ class library designed for rapid production of sophisticated domain-specific design applications. 
7
8 A typical application developed using OCCT deals with two or three-dimensional (2D or 3D) geometric modeling
9 in general-purpose or specialized Computer Aided Design (CAD) systems, manufacturing
10 or analysis applications, simulation applications, or illustration tools. 
11
12 @figure{/technical_overview/images/technical_overview_over.png}
13
14 OCCT Library is designed to be truly modular and extensible. It provides C++ classes for:
15   * Defining data structures (geometric modeling, display and graphic selection) 
16   * Implementing complex algorithms 
17   * Providing Application Programming Interfaces (APIs) 
18
19 The classes are grouped into packages. 
20 To prevent any class-name conflicts, C++ class-names are prefixed by a package name. 
21 For example, all classes defining 3D geometric objects belong to the *Geom* package. 
22 In Geom, the class implementing Bezier surfaces is called *BezierSurface*, thus its full name is <i>Geom_BezierSurface</i>.
23
24 Packages are then archived into toolkits (libraries), to which you can link your application. Finally, toolkits are grouped into seven modules.
25
26 This modular structure is illustrated in the diagram below.
27
28 @figure{/technical_overview/images/technical_overview_schema.png}
29
30 Refer to the Technical Overview and User's Guides for details about the services provided in each module. 
31
32 * @ref OCCT_TOVW_SECTION_2 "Foundation Classes"; 
33 * @ref OCCT_TOVW_SECTION_3 "Modeling Data"; 
34 * @ref OCCT_TOVW_SECTION_4 "Modeling Algorithms";
35 * @ref OCCT_TOVW_SECTION_4a "Mesh";
36 * @ref OCCT_TOVW_SECTION_5 "Visualization";
37 * @ref OCCT_TOVW_SECTION_6 "Data Exchange";
38 * @ref OCCT_TOVW_SECTION_7 "Application Framework". 
39
40 In addition, @ref OCCT_TOVW_SECTION_7a "Open CASCADE Test Harness", also called Draw, provides testing tools for other modules. 
41
42
43 @section OCCT_TOVW_SECTION_2 Foundation Classes
44
45 Foundation Classes provide a variety of general-purpose services such as:
46
47   * Primitive types, strings and various types of quantities 
48   * Automated management of heap memory 
49   * Exception handling 
50   * Classes for manipulating data collections
51   * Math tools such as vectors, matrices and primitive geometric types 
52   * Basic services for saving data in ASCII files 
53
54 These services are organized into the following toolkits:
55   * @ref OCCT_TOVW_SECTION_2_1 "Kernel Classes" 
56   * @ref OCCT_TOVW_SECTION_2_2 "Math Utilities" 
57   * @ref occt_fcug_5 "Basic Data Storage"
58
59 The technical overview provides only a basic description of the libraries. 
60 For more details see @ref occt_user_guides__foundation_classes "Foundation Classes User's Guide"
61
62 See also: our web site at <a href="http://www.opencascade.org/support/training/">E-learning and Training</a>.
63
64 @subsection OCCT_TOVW_SECTION_2_1 Kernel Classes
65
66 ### Root Classes
67
68 Root Classes, primarily implemented in the Standard package, are the predefined classes on which
69 all other Open CASCADE Technology classes are built. They provide:
70
71   * Primitive types such as Boolean, Character, Integer or Real 
72   * Memory manager based on reference counting for optimizing the allocation and deallocation of large numbers of small C++ objects 
73   * <i>Standard_Transient</i> class automating memory management through smart pointers
74   * OCCT <i>Handle</i>; most of OCCT classes inherit from this base class.
75   * Management of exceptions,
76   * Encapsulation of C++ streams.
77
78 ### Quantities
79
80 Quantity classes provide the following services:
81
82   * Definition of primitive types representing most of mathematical and physical quantities
83   * Unit conversion tools.    
84   * Resources to manage time information such as dates and time periods 
85   * Resources to manage color definition 
86
87 A mathematical quantity is characterized by the name and the value (real).
88 A physical quantity is characterized by the name, the value (real) and the unit. 
89 The unit may be either an international unit complying with the International Unit System (SI) 
90 or a user defined unit. The unit is managed by the physical quantity user.
91
92 The fact that both physical and mathematical quantities are manipulated as real
93 values means that :
94
95   * They are defined as aliases of real values, so all functions provided by the <i>Standard_Real</i> class are available on each quantity.
96   * It is possible to mix several physical quantities in a mathematical or physical formula involving real values.
97
98 <i>Quantity</i> package includes all commonly used basic physical quantities. 
99
100 ### Exceptions
101
102 Exception classes list all the exceptions, which can be raised by any OCCT function.
103
104 Each exception inherits from Standard_Failure either directly or by inheriting from
105 another exception.
106
107 Exceptions describe anomalies which can occur during the execution of a method. With
108 the raising of an exception, the normal course of program execution is abandoned.
109 The execution of actions in response to this situation is called the treatment of
110 the exception.
111
112
113 The methods try & catch are redefined in OCCT to work properly on any platform. Nevertheless
114 they call native mechanisms each time it is possible. The only reason not to use
115 native exceptions is that they may not work properly on some compilers. In this case,
116 a specific OCCT code is used instead. 
117
118
119 ### Strings
120
121 Strings are classes that handle dynamically sized sequences of characters based on
122 ASCII/Unicode UTF-8 (normal 8-bit character type)
123 and UTF-16/UCS-2 (16-bit character type). They provide editing operations with built-in
124 memory management which make the relative objects easier to use than ordinary character
125 arrays.
126
127 String classes provide the following services to manipulate character strings:
128  * Editing operations on string objects, using a built-in string manager 
129  * Handling of dynamically-sized sequences of characters 
130  * Conversion from/to ASCII and UTF-8 strings. 
131
132 Strings may also be manipulated by handles and therefore, can be shared.
133
134 These classes are implemented in <i>TCollection</i> and <i>NCollection</i> packages.
135
136 ### Collections
137
138 Apart from strings, the <i> TCollection</i> package contains classes of dynamically sized
139 aggregates of data. They include a wide range of collections.
140
141   * Arrays (unidimensional and bidimensional) are generally used for quick access to an item. Note that an array is a fixed-sized aggregate. 
142   * Sequences are ordered collections of non-unique objects. A sequence item is longer to access than an array item: only an exploration in sequence is efficient (but sequences are not adapted for numerous explorations).  Arrays and sequences are commonly used as data structures for more complex objects.
143   * Maps are dynamic structures, where the size is constantly adapted to the number of inserted items and access to an item is the fastest. Maps structures are commonly used in cases of numerous explorations: they are typically internal data structures for complex algorithms.
144   * Lists are similar to sequences but with different algorithms to explore them. 
145   * Specific iterators for sequences and maps.
146
147 Most collections follow value semantics: their instances are the actual collections, not handles to a collection. Only arrays and sequences may also be manipulated by handle, and therefore shared.
148
149
150 Collection classes are generic (C++ template-like), so they can contain 
151 a variety of objects which do not necessarily inherit from
152 a unique root class. When you need to use a collection of a given object type, you
153 must instantiate the collection for this specific type. Once the code for this declaration
154 is compiled, all functions available on the generic collection are available on your
155 instantiated class.
156
157 Each collection directly used as an argument in Open CASCADE Technology public syntax
158 is instantiated in an OCCT component using the corresponding generic class in package
159 <i> TCollection</i>, by means of compiling the CDL declaration of the instance. 
160 Thus OCCT generic classes require compilation of definitions in the CDL language and therefore
161 can only be instantiated in WOK.
162
163 If you are not using CDL in your project (CDL compilation under WOK is necessary
164 to instantiate any generic Collection from package <i>TCollection</i>), then you should
165 use the Collections defined in <i> NCollection</i> package. It contains definitions of the
166 same generic collection classes described above, but in a form of C++ templates.
167 Therefore, to instantiate any collection type no additional support is required beyond
168 the ANSI C++ compiler.
169
170 @subsection OCCT_TOVW_SECTION_2_2 Math Utilities
171
172 ### Vectors and Matrices
173
174 The <i> Vector</i> and <i> Matrix </i> classes provide commonly used mathematical algorithms which
175 include:
176
177   * Basic calculations involving vectors and matrices; 
178   * Computation of eigenvalues and eigenvectors of a square matrix; 
179   * Solvers for a set of linear algebraic equations; 
180   * Algorithms to find the roots of a set of non-linear equations; 
181   * Algorithms to find the minimum function of one or more independent variables. 
182
183 These classes also provide a data structure to represent any expression,
184 relation, or function used in mathematics, including the assignment of variables.
185
186 Vectors and matrices have arbitrary ranges which must be defined at declaration time
187 and cannot be changed after declaration. 
188
189 ~~~
190     math_Vector v(1, 3);
191     // a vector of dimension 3 with range (1..3)
192
193     math_Matrix m(0, 2, 0, 2);
194     // a matrix of dimension 3x3 with range (0..2, 0..2)
195
196     math_Vector v(N1, N2);
197     // a vector of dimension N2-N1+1 with range (N1..N2)
198 ~~~
199
200 Vector and Matrix objects follow "value semantics", that is, they cannot be shared
201 and are copied though assignment.
202
203 ~~~
204     math_Vector v1(1, 3), v2(0, 2);
205
206     v2 = v1; // v1 is copied into v2
207                 // a modification of v1 does not affect v2
208 ~~~
209
210 Vector and Matrix elements can be retrieved using indexes, which must be in the range
211 defined upon Vector/Matrix creation. The elements can be initialized with some numerical
212 value upon creation as well.
213
214 ~~~
215     math_Vector v(1, 3);
216     math_Matrix m(1, 3, 1, 3);
217     Standard_Real value;
218
219     v(2) = 1.0;
220     value = v(1);
221     m(1, 3) = 1.0;
222     value = m(2, 2);
223 ~~~
224
225 Some operations on Vector and Matrix objects may not be legal. In this case an exception
226 is raised. Two standard exceptions are used:
227  *<i>Standard_DimensionError</i> exception is raised when two matrices or vectors involved
228 in an operation are of incompatible dimensions.
229  *<i>Standard_RangeError</i>exception is raised if an attempt to access outside the range
230 defined upon creation of a vector or a matrix is made.
231
232 ~~~
233     math_Vector v1(1, 3), v2(1, 2), v3(0, 2);
234
235     v1 = v2;            // error: Standard_DimensionError is raised
236     v1 = v3;            // OK: ranges are not equal, but dimensions are compatible
237     v1(0) = 2.0;        // error: Standard_RangeError is raised
238 ~~~
239
240
241 ### Fundamental Geometry Types
242
243 The Fundamental Geometry Types component groups the following packages:
244 * geometric processor package <i> gp</i>;
245 * <i>GeomAbs</i> package, which provides enumerations generally used in geometry;
246
247 <i>gp</i> package is a STEP-compliant implementation of basic geometric and algebraic
248 entities, used to define and manipulate elementary data structures.
249
250 In particular, <i>gp</i> provides:
251
252   * descriptions of primitive geometric shapes, such as:
253           * Points; 
254           * Vectors; 
255           * Lines; 
256           * Circles and conics; 
257           * Planes and elementary surfaces;
258   * positioning of these shapes in space or in a plane by means of an axis or a coordinate system;
259   * definition and application of geometric transformations to these shapes:
260           * Translations; 
261           * Rotations; 
262           * Symmetries; 
263           * Scaling transformations; 
264           * Composed transformations;
265   * Tools (coordinates and matrices) for algebraic computation.
266
267 These functions are defined in 3D space and in the plane.
268
269 <i> gp</i> curves and surfaces are analytic: there is no parameterization and no orientation 
270 on <i>gp</i> entities, i.e. these entities do not provide functions which work with these properties. 
271 If you need, you may use more evolved data structures provided by <i> Geom</i> 
272 (in 3D space) and <i> Geom2d</i> (in the plane). However, the definition of <i> gp</i> entities 
273 is identical to the one of equivalent <i> Geom</i> and <i> Geom2d</i> entities, and they are located
274 in the plane or in space with the same kind of positioning systems. 
275 They implicitly contain the orientation, which they express 
276 on the <i> Geom </i> and <i> Geom2d </i> entities, and they induce the definition of their parameterization.
277
278
279 Therefore, it is easy to give an implicit parameterization to <i> gp</i> curves and surfaces,
280 which is the parametarization of the equivalent <i> Geom</i> or <i> Geom2d</i> entity. This property
281 is particularly useful when computing projections or intersections, or for operations
282 involving complex algorithms where it is particularly important to manipulate the
283 simplest data structures, i.e. those of <i> gp</i>. Thus, the <i> ElCLib</i> and <i> ElSLib</i> packages
284 provide functions to compute:
285
286   * the point of parameter u on a 2D or 3D gp curve,
287   * the point of parameter (u,v) on a gp elementary surface, and
288   * any derivative vector at this point.
289
290 Note: the <i> gp</i> entities cannot be shared when they are inside more complex data structures.
291
292
293 ### Common Mathematical Algorithms
294
295 Common mathematical algorithms provided in OCCT include:
296
297   * Algorithms to solve a set of linear algebraic equations, 
298   * Algorithms to find the minimum of a function of one or more independent variables,
299   * Algorithms to find roots of one or of a set of non-linear equations, 
300   * An algorithm to find the eigenvalues and eigenvectors of a square matrix.
301
302 @section OCCT_TOVW_SECTION_3 Modeling Data
303
304 Modeling Data supplies data structures to represent 2D and 3D geometric models.
305
306 @figure{/technical_overview/images/technical_overview_md.png}
307
308 These services are organized into the following toolkits:
309
310   * @ref OCCT_TOVW_SECTION_3_1 "2D Geometry Types"
311   * @ref OCCT_TOVW_SECTION_3_2 "3D Geometry Types"
312   * @ref OCCT_TOVW_SECTION_3_3 "Geometry Utilities" 
313   * @ref OCCT_TOVW_SECTION_3_4 "Topology" 
314    
315 There are also some packages that help to find local and global @ref OCCT_TOVW_SECTION_3_5 "Properties of Shapes".
316  
317 The technical overview provides only a basic description of the libraries.
318 For more details see @ref occt_user_guides__modeling_data "Modeling Data User's Guide"
319
320 3D geometric models are stored in OCCT native BREP format.
321 See @ref occt_user_guides__brep_wp "BREP Format Description White Paper" for details on the format.
322
323 See also: our web site at <a href="http://www.opencascade.org/support/training/">E-learning and Training</a>.
324
325 @subsection OCCT_TOVW_SECTION_3_1 2D Geometry Types
326
327 <i> Geom2d</i> package provides an implementation of 2D geometric objects, defined in the way similar to STEP standard (ISO 10303, part 42).
328
329 In particular, it provides classes for:
330 * description of points, vectors and curves,
331 * their positioning in the plane using coordinate systems,
332 * their geometric transformation, by applying translations, rotations, symmetries, scaling transformations and combinations thereof.
333
334 The key characteristic of <i> Geom2d </i> curves is that they are parameterized. 
335 Each class provides functions to work with the parametric equation of the curve, 
336 and, in particular, to compute the point of parameter u on a curve and the derivative vectors of order 1, 2.., N at this point.
337
338 As a consequence of the parameterization, a <i> Geom2d </i> curve is naturally oriented.
339
340 Parameterization and orientation differentiate elementary <i>Geom2d </i>curves from their
341 equivalent as provided by <i> gp</i> package. <i>  Geom2d</i> package provides conversion
342 functions to transform a <i> Geom2d</i> object into a <i> gp</i> object, and vice-versa, when this is possible.
343
344 Moreover, <i> Geom2d</i> package provides more complex curves, including Bezier curves,
345 BSpline curves, trimmed curves and offset curves.
346
347 <i> Geom2d </i> objects are organized according to an inheritance structure over several levels.
348
349 Thus, 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.
350
351 This 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.
352
353 Finally, <i> Geom2d</i> objects can be shared within more complex data structures. This is why they are used within topological data structures, for example.
354
355 <i>Geom2d</i>package uses the services of the <i> gp</i> package to:
356   * implement elementary algebraic calculus and basic analytic geometry,
357   * describe geometric transformations which can be applied to <i> Geom2d</i> objects,
358   * describe the elementary data structures of <i>Geom2d</i> objects.
359
360 However, the <i> Geom2d</i> package essentially provides data structures and not algorithms.
361 You can refer to the <i> GCE2d </i> package to find more evolved construction algorithms for <i> Geom2d </i> objects.
362
363 @subsection OCCT_TOVW_SECTION_3_2 3D Geometry Types
364
365 The <i> Geom</i> package provides an implementation of 3D geometric objects, defined in the way similar to STEP standard (ISO 10303, part 42). 
366
367 In particular, it provides classes for:
368
369   * description of points, vectors, curves and surfaces,
370     * their positioning in 3D space using axis or coordinate systems, and
371     * their geometric transformation, by applying translations, rotations, symmetries, scaling transformations and combinations thereof.
372
373 The key characteristic of Geom curves and surfaces is that they are parameterized.
374 Each class provides functions to work with the parametric equation of the curve or
375 surface, and, in particular, to compute:
376
377    * the point of parameter u on a curve, or
378    * the point of parameters (u, v) on a surface.
379
380 together with the derivative vectors of order 1, 2, ... N at this point.
381
382 As a consequence of this parameterization, a Geom curve or surface is naturally oriented.
383
384 Parameterization and orientation differentiate elementary Geom curves and surfaces from the classes of the same (or similar) names found in the <i> gp</i> package. 
385 The <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.
386
387 Moreover, the <i> Geom </i>package provides more complex curves and surfaces, including:
388   * Bezier and BSpline curves and surfaces,
389   * swept surfaces, for example surfaces of revolution and surfaces of linear extrusion,
390   * trimmed curves and surfaces, and
391   * offset curves and surfaces.
392
393 Geom objects are organized according to an inheritance structure over several levels.
394 Thus, 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.
395
396 This 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.
397
398 Finally, Geom objects can be shared within more complex data structures. This is why they are used within topological data structures, for example.
399
400 The <i> Geom</i> package uses the services of the <i> gp</i> package to:
401   * implement elementary algebraic calculus and basic analytic geometry,
402   * describe geometric transformations which can be applied to Geom objects,
403   * describe the elementary data structures of Geom objects.
404
405 However, the Geom package essentially provides data structures, not algorithms.
406
407 You can refer to the <i> GC</i> package to find more evolved construction algorithms for
408 Geom objects.
409
410 @subsubsection OCCT_TOVW_SECTION_3_2_1 Adaptors for Curves and Surfaces
411
412 Some Open CASCADE Technology general algorithms may work theoretically on numerous types of curves or surfaces. 
413 To do this, they simply get the services required of the analysed  curve or surface through an interface so as to a single API,  whatever the type of curve or surface. These interfaces are called adaptors.
414 For example, <i> Adaptor3d_Curve </i> is the abstract class which provides  the required services by an algorithm which uses any 3d curve.
415
416 <i> GeomAdaptor </i>package provides interfaces:
417
418   * On a Geom curve;
419   * On a curve lying on a Geom surface;
420   * On a Geom surface;
421
422 <i> Geom2dAdaptor</i> package provides interfaces :
423
424   * On a <i>Geom2d</i> curve.
425
426 <i> BRepAdaptor </i> package provides interfaces:
427
428   * On a Face
429   * On an Edge
430
431 When you write an algorithm which operates on geometric objects, use <i> Adaptor3d</i> (or <i> Adaptor2d</i>) objects. 
432
433 As 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*.
434 These interfaces are easy to use: simply create an adapted curve or surface from a *Geom2d* curve, 
435 and then use this adapted curve as an argument for the algorithm which requires it.
436
437 @subsection OCCT_TOVW_SECTION_3_3 Geometry Utilities
438
439 This library provides standard high-level functions in 2D and 3D geometry such as:
440
441   * Direct construction of algorithms; 
442   * Approximation of curves and surfaces from points; 
443   * Conversion of more elementary geometry to BSpline curves and surfaces; 
444   * Calculation of points on a 2D or 3D curve; 
445   * Calculation of extrema between two geometries. 
446
447 @subsubsection OCCT_TOVW_SECTION_3_3_1 Direct Construction
448
449 The <i> gp</i>, <i> Geom2d</i> and <i> Geom</i> packages describe elementary data structures of simple geometric
450 objects. The constructors of these objects are elementary: the construction arguments
451 are fields by which the objects are represented in their data structure.
452
453
454 On the other hand, the <i> gce</i>, <i> GCE2d</i> and <i> GC</i> packages provided 
455 by the Direct Construction component construct the same types of objects 
456 as <i> gp</i>, <i> Geom2d </i>and <i> Geom</i> respectively.
457 However, the former implement geometric construction algorithms that translate the
458 constructor's arguments into the data structure specific to each object.
459
460
461 Algorithms implemented by these packages are simple: there is no creation of objects
462 defined by advanced positional constraints (for more information on this subject,
463 see <i> Geom2dGcc</i> and <i> GccAna</i> which describe geometry by constraints).
464
465
466 <i> gce</i>, <i> GCE2d</i> and <i> GC </i>each offer a series of classes of construction algorithms.
467
468
469 For example, the class <i>gce_MakeCirc</i> provides a framework 
470 for defining eight problems encountered in the geometric construction of circles, 
471 and implementing the eight related construction algorithms.
472
473 The object created (or implemented) is an algorithm which can be consulted to find out, in particular:
474
475   * its result, which is a <i>gp_Circ</i>, and
476   * its status. Here, the status indicates whether or not the construction was successful.
477
478 If it was unsuccessful, the status gives the reason for the failure.
479
480 ~~~~
481     gp_Pnt P1 (0.,0.,0.);
482     gp_Pnt P2 (0.,10.,0.);
483     gp_Pnt P3 (10.,0.,0.);
484     gce_MakeCirc MC (P1,P2,P3);
485     if (MC.IsDone()) {
486                 const gp_Circ& C = MC.Value();
487     }
488 ~~~~
489
490 In addition, <i> gce</i>, <i> GCE2d</i> and <i> GC</i> each have a <i>Root</i> class. This class is the root of
491 all the classes in the package which return a status. The returned status (successful
492 construction or construction error) is described by the enumeration <i> gce_ErrorType</i>.
493
494 Note: classes which construct geometric transformations do not return a status, and
495 therefore do not inherit from Root.
496
497 @subsubsection OCCT_TOVW_SECTION_3_3_2 Approximations
498
499 Approximation of Curves and Surfaces groups together a variety of functions used in 2D and 3D geometry for:
500
501   * the interpolation of a set of 2D points using a 2D BSpline or Bezier curve;
502   * the approximation of a set of 2D points using a 2D BSpline or Bezier curve;
503   * the interpolation of a set of 3D points using a 3D BSpline or Bezier curve, or a BSpline surface;
504   * the approximation of a set of 3D points using a 3D BSpline or Bezier curve, or a BSpline surface.
505
506 You can program approximations in two ways:
507
508   * Using high-level functions, designed to provide a simple method for obtaining approximations with minimal programming,
509   * Using low-level functions, designed for users requiring more control over the approximations.
510
511 The low-level functions provide a second API with functions to:
512
513   * Define compulsory tangents for an approximation. These tangents have origins and extremities.
514   * Approximate a set of curves in parallel to respect identical parameterization.
515   * Smooth approximations. This is to produce a faired curve.
516
517 The classes <i> AppDef_MultiPointConstraints</i> and <i> AppDef_MultiLines </i> allow organizing the data.
518 The classes <i> AppDef_Compute</i>, <i> AppDef_BSplineCompute</i> and <i> AppDef_TheVariational </i> 
519 classes perform the approximation itself using Bezier curves, BSpline curves, and smooth BSpline curves, respectively.
520
521 You can also find functions to compute:
522   * The minimal box which includes a set of points
523   * The mean plane, line or point of a set of coplanar, collinear or coincident points.
524   
525 #### Example: How to approximate a curve with respect to tangencies
526
527 To approximate a curve with respect to tangencies, follow these steps:
528
529   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.
530   2. Create an object of type <i> AppDef_MultiLine </i>from the <i> AppDef_MultiPointConstraint</i>.
531   3. Use <i> AppDef_BSplineCompute</i>, which instantiates <i>Approx_BSplineComputeLine</i> to perform the approximation.
532
533 @subsubsection OCCT_TOVW_SECTION_3_3_3 Conversion to and from BSplines
534  
535 The Conversion to and from BSplines component has two distinct purposes:
536   * Firstly, it provides a homogeneous formulation which can be used to describe any curve or surface. 
537   This is useful for writing algorithms for a single data structure model. 
538   The BSpline formulation can be used to represent most basic geometric objects provided 
539   by the components which describe geometric data structures ("Fundamental Geometry Types", "2D Geometry Types" and "3D Geometry Types" components).
540   * Secondly, it can be used to divide a BSpline curve or surface into a series of curves or surfaces, 
541   thereby providing a higher degree of continuity. This is useful for writing algorithms 
542   which require a specific degree of continuity in the objects to which they are applied. 
543   Discontinuities are situated on the boundaries of objects only.
544
545 The "Conversion to and from BSplines" component is composed of three packages.
546
547 The <i> Convert </i> package provides algorithms to convert the following into a BSpline curve or surface:
548
549   * a bounded curve based on an elementary 2D curve (line, circle or conic) from the <i> gp </i> package,
550   * a bounded surface based on an elementary surface (cylinder, cone, sphere or torus) from the <i> gp</i> package,
551   * a series of adjacent 2D or 3D Bezier curves defined by their poles.
552
553 These algorithms compute the data needed to define the resulting BSpline curve or surface. 
554 This elementary data (degrees, periodic characteristics, poles and weights, knots and multiplicities) 
555 may then be used directly in an algorithm, or can be used to construct the curve or the surface 
556 by calling the appropriate constructor provided by the classes <i>Geom2d_BSplineCurve, Geom_BSplineCurve </i> or <i>Geom_BSplineSurface</i>.
557
558 The <i>Geom2dConvert</i> package provides the following:
559
560   * a global function which is used to construct a BSpline curve from a bounded curve based on a 2D curve from the Geom2d package,
561   * 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,
562   * global functions used to construct the BSpline curves created by this splitting algorithm, or by other types of segmentation of the BSpline curve,
563   * an algorithm which converts a 2D BSpline curve into a series of adjacent Bezier curves.
564
565 The <i> GeomConvert</i> package also provides the following:
566
567   * a global function used to construct a BSpline curve from a bounded curve based on a curve from the Geom package,
568   * 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,
569   * global functions to construct BSpline curves created by this splitting algorithm, or by other types of BSpline curve segmentation,
570   * an algorithm, which converts a BSpline curve into a series of adjacent Bezier curves,
571   * a global function to construct a BSpline surface from a bounded surface based on a surface from the Geom package,
572   * 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,
573   * global functions to construct BSpline surfaces created by this splitting algorithm, or by other types of BSpline surface segmentation,
574   * an algorithm, which converts a BSpline surface into a series of adjacent Bezier surfaces,
575   * an algorithm, which converts a grid of adjacent Bezier surfaces into a BSpline surface.
576
577 @subsubsection OCCT_TOVW_SECTION_3_3_4 Calculation of Points on Curves
578
579 The Making Points on Curves component comprises high level functions providing an Application Programming Interface for complex algorithms that compute points on a 2D or 3D curve. The functions use various methods.
580
581 The algorithms result in the following:
582
583   * a point on a curve, situated at a given curvilinear distance from another point on the curve
584   * a distribution of points situated at constant curvilinear intervals along a curve
585   * a distribution of points at a constant rise (i.e. respecting a criterion of maximum rise between the curve and the polygon that results from the computed points) along a curve
586   * the length of a curve.
587
588 @subsection OCCT_TOVW_SECTION_3_4 Topology
589
590 Topological library allows you to build pure topological data structures..
591
592 Topology defines relationships between simple geometric entities. In this way, 
593 you can model complex shapes as assemblies of simpler entities. 
594 Due to a built-in non-manifold (or mixed-dimensional) feature, you can build models mixing:
595
596   * 0D entities such as points; 
597   * 1D entities such as curves; 
598   * 2D entities such as surfaces; 
599   * 3D entities such as volumes. 
600
601 You can, for example, represent a single object made of several distinct bodies 
602 containing embedded curves and surfaces connected or non-connected to an outer boundary.
603
604 Abstract topological data structure describes a basic entity - a shape, 
605 which can be divided into the following component topologies:
606
607   * Vertex - a zero-dimensional shape corresponding to a point in geometry; 
608   * Edge - a shape corresponding to a curve, and bound by a vertex at each extremity;
609   * Wire - a sequence of edges connected by their vertices; 
610   * Face - part of a plane (in 2D geometry) or a surface (in 3D geometry) bounded by a closed wire;
611   * Shell - a collection of faces connected by some edges of their wire boundaries; 
612   * Solid - a part of 3D space bound by a shell; 
613   * Compound solid - a collection of solids. 
614
615 The wire and the solid can be either infinite or closed.
616
617 A face with 3D underlying geometry may also refer to a collection of connected triangles 
618 that approximate the underlying surface. The surfaces can be undefined 
619 leaving the faces represented by triangles only. If so, the model is purely polyhedral.
620
621 Topology defines the relationship between simple geometric entities, 
622 which can thus be linked together to represent complex shapes.
623
624 Abstract Topology is provided by six packages. 
625 The first three packages describe the topological data structure used in Open CASCADE Technology:
626
627   * <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.
628   * <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.
629   * <i> TopoDS</i> package describes classes to model and build data structures that are purely topological.
630
631 Three additional packages provide tools to access and manipulate this abstract topology:
632
633   * <i> TopTools</i> package provides basic tools to use on topological data structures.
634   * <i> TopExp</i> package provides classes to explore and manipulate the topological data structures described in the TopoDS package.
635   * <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.
636
637 @subsection OCCT_TOVW_SECTION_3_5 Properties of Shapes
638
639 @subsubsection OCCT_TOVW_SECTION_3_5_1 Local Properties of Shapes
640
641 <i>BRepLProp</i> package provides the Local Properties of Shapes component, 
642 which contains algorithms computing various local properties on edges and faces in a BRep model.
643
644 The local properties which may be queried are:
645
646   * for a point of parameter u on a curve which supports an edge :
647     * the point,
648     * the derivative vectors, up to the third degree,
649     * the tangent vector,
650     * the normal,
651     * the curvature, and the center of curvature;
652   * for a point of parameter (u, v) on a surface which supports a face :
653     * the point,
654     * the derivative vectors, up to the second degree,
655     * the tangent vectors to the u and v isoparametric curves,
656     * the normal vector,
657     * the minimum or maximum curvature, and the corresponding directions of curvature;
658   * the degree of continuity of a curve which supports an edge, built by the concatenation of two other edges, at their junction point.
659
660 Analyzed edges and faces are described as <i> BRepAdaptor</i> curves and surfaces, 
661 which provide shapes with an interface for the description of their geometric support. 
662 The base point for local properties is defined by its u parameter value on a curve, or its (u, v) parameter values on a surface.
663
664 @subsubsection OCCT_TOVW_SECTION_3_5_2 Local Properties of Curves and Surfaces
665
666 The "Local Properties of Curves and Surfaces" component provides algorithms for computing various local 
667 properties on a Geom curve (in 2D or 3D space) or a surface. It is composed of:
668
669   * <i> Geom2dLProp</i> package, which allows computing Derivative and Tangent vectors (normal and curvature) of a parametric point on a 2D curve;
670   * <i> GeomLProp </i> package, which provides local properties on 3D curves and surfaces
671   * <i> LProp </i> package, which provides an enumeration used to characterize a particular point on a 2D curve.
672
673 Curves are either <i> Geom_Curve </i> curves (in 3D space) or <i> Geom2d_Curve </i> curves (in the plane). 
674 Surfaces are <i> Geom_Surface </i> surfaces. The point on which local properties are calculated 
675 is defined by its u parameter value on a curve, and its (u,v) parameter values on a surface.
676
677 It is possible to query the same local properties for points as mentioned above, and additionally for 2D curves:
678
679   * the points corresponding to a minimum or a maximum of curvature;
680   * the inflection points.
681   
682   
683 #### Example: How to check the surface concavity
684
685 To check the concavity of a surface, proceed as follows:
686
687   1. Sample the surface and compute at each point the Gaussian curvature.
688   2. If the value of the curvature changes of sign, the surface is concave or convex depending on the point of view.
689   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>.
690   
691 @subsubsection OCCT_TOVW_SECTION_3_5_3 Global Properties of Shapes
692
693 The Global Properties of Shapes component provides algorithms for computing the global 
694 properties of a composite geometric system in 3D space, and frameworks to query the computed results.
695
696 The global properties computed for a system are :
697
698   * mass,
699   * mass center,
700   * matrix of inertia,
701   * moment about an axis,
702   * radius of gyration about an axis,
703   * principal properties of inertia such as principal axis, principal moments, and principal radius of gyration.
704
705 Geometric systems are generally defined as shapes. Depending on the way they are analyzed, these shapes will give properties of:
706
707   * lines induced from the edges of the shape,
708   * surfaces induced from the faces of the shape, or
709   * volumes induced from the solid bounded by the shape.
710
711 The 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.
712
713 The Global Properties of Shapes component is composed of:
714 * 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),
715 * a framework for computing global properties for a set of points (<i>GProp_PGProps</i>),
716 * and 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.
717     
718 @subsection OCCT_TOVW_SECTION_3_6 Examples
719
720 ### How to compute the curve length
721
722 To compute curve length, use the method <i>AbscissaPoint::Length</i> from <i> GCPnts</i>.
723
724 This function is used only for initializing a framework to compute the length of a curve (or a series of curves).
725
726 The adapted curves are:
727
728   * Adaptor_Curve2d for 2D curves
729   * Adaptor_Curve for 3D curves.
730
731 The adapted curve is created in the following way:
732
733 In 2D:
734
735 ~~~~~~~~~~~
736     Handle(Geom2d_Curve) mycurve = ... ;
737     Geom2dAdaptor_Curve C (mycurve) ;
738 ~~~~~~~~~~~
739
740 In 3D:
741
742 ~~~~~~~~~
743     Handle(Geom_Curve) mycurve = ... ;
744     GeomAdaptor_Curve C (mycurve) ;
745 ~~~~~~~~~
746
747
748 The length of the curve is then computed using this curve object:
749
750 ~~~~~~~~
751     GCPnts_AbscissaPoint myAlgo () ;
752     Standard_Real L = myAlgo.Length( C ) ;
753 ~~~~~~~~
754
755
756
757
758
759 ### How to extract the underlying geometry from shapes
760
761
762 To extract the underlying geometry from a Shape, use the following methods:
763
764   * <i> BRep_Tool::Surface</i> to get the geometric surface from a face.
765   * <i> BRep_Tool::Curve</i> to get the 3d geometric curve from an edge.
766   * <i> BRep_Tool::CurveOnSurface</i> to get the 2d geometric curve of an edge, defined in the parametric space of a face.
767   * <i> BRep_Tool::Pnt </i> to get the 3D point from a vertex.
768
769 Some of these methods have a location as argument.
770
771 For example, when you use <i> S1 = BRep_Tool::Surface(F,L), </i> you then get the surface stored in <i> TShape</i>.
772
773 To use this surface in the same position as the face, you have to apply 
774 a transformation to it corresponding to the location of the face as follows:
775
776 ~~~~~~~~~~~~
777     gp_Trsf T(L) ;
778     S2 = S1->Moved(T) ;
779 ~~~~~~~~~~~~
780
781 The same method used without location as argument is <i>S3 = BRep_Tool : : Surface(F)</i> 
782 returns a Surface in position, according to the location. S3 and S2 are geometrically equivalent surfaces.
783
784 Warning: with the first method, you get a pointer on the surface stored in the shape. 
785 Do not modify the surface because you will modify the shape and may produce an inconsistent model.
786 With the second method, you get a copy of the surface on which the location has been applied.
787 Note: you can use also a topological object directly just as if it 
788 were a geometric one by using the services of <i> BRepAdaptor </i>classes.
789
790 ### How to get the coordinates of a vertex
791
792
793 To recover the UV coordinates of vertices, 
794 use <i> BRep_Tool::Parameters const TopoDS_Vertex& V,const TopoDS_Face& F), </i> 
795 which returns the U and V parameters of the vertex V on the face F as a <i> gp_Pnt2d</i>. 
796
797 ### How to explore a Wire
798
799
800 To explore the edges of a wire in a contiguous order, use <i> BrepTools_WireExplorer</i> class.
801
802 ~~~~
803     TopoDS_Wire myWire =&ldots;.
804     BRepTools_WireExplorer Ex;
805     for (Ex.Init(myWire); Ex.More(); Ex.Next()) {
806     TopoDS_Edge currentedge = Ex.Current();
807     // Process current edge
808     }
809 ~~~~
810
811 ### How to merge bspline curves
812
813
814 To merge joined bspline curves use the following methods:
815
816 ~~~~
817     void GeomConvert::ConcatG1
818     TColGeom_Array1OfBSplineCurve& ArrayOfCurves,
819       const TColStd_Array1OfReal& ArrayOfToler,
820     Handle(TColGeom_HArray1OfBSplineCurve) & ArrayOfConcatenated,
821     const Standard_Boolean ClosedG1Flag,
822       const Standard_Real ClosedTolerance)
823 ~~~~
824
825 This method concatenates according to G1 (tangency continuity along the curve) the 
826 <i>ArrayOfCurves</i> as far as possible. The following arguments are used:
827
828   * <i> ArrayOfCurves</i> must have dimension bounds [0, N-1], N   * number of curves to be merged.
829   * <i> ArrayOfToler</i> contains the biggest tolerance of the two points shared by two consecutive curves. Its dimension is: [0, N-2].
830   * <i> ArrayOfConcatenated</i> contains results of operation: one or more, when impossible to merge all curves from <i> ArrayOfCurves </i> into one, new bspline curves are created.
831   * <i> ClosedG1Flag </i> indicates if the <i> ArrayOfCurves </i> is closed or not.
832   * If <i> ClosedG1Flag = Standard_True, ClosedTolerance </i> contains the biggest tolerance of the two points which are at the closure, otherwise its value is 0.0.
833
834 ~~~~
835     void GeomConvert::ConcatC1
836     TColGeom_Array1OfBSplineCurve& ArrayOfCurves,
837       const TColStd_Array1OfReal& ArrayOfToler,
838     Handle(TColStd_HArray1OfInteger)& ArrayOfIndices,
839     Handle(TColGeom_HArray1OfBSplineCurve)& ArrayOfConcatenated,
840     const Standard_Boolean ClosedG1Flag,
841       const Standard_Real ClosedTolerance,
842       const Standard_Real AngularTolerance)
843 ~~~~
844
845 This method concatenates according to C1 (first derivative continuity along the curve) the <i> 
846 ArrayOfCurves</i> as far possible. The following arguments are used (additionally to the mentioned above):
847
848 * <i> ArrayOfIndices</i> contains indices that define curves from <i> ArrayOfCurves</i> which are beginning curves for each group of curves merged into a new curve.
849 * <i> AngularTolerance</i> is used to check the continuity of tangencies.
850
851 ~~~~
852     void GeomConvert::ConcatC1
853     TColGeom_Array1OfBSplineCurve& ArrayOfCurves,
854       const TColStd_Array1OfReal& ArrayOfToler,
855     Handle(TColStd_HArray1OfInteger)& ArrayOfIndices,
856     Handle(TColGeom_HArray1OfBSplineCurve)& ArrayOfConcatenated,
857       const Standard_Boolean ClosedG1Flag,
858       const Standard_Real ClosedTolerance)
859 ~~~~
860 This method is the same as the previous one, except for that <i> AngularTolerance = Precision::Angular() </i>
861
862 It is also possible to use class <i> GeomConvert_CompCurveToBSplineCurve</i>. 
863 This class provides methods to concatenate several restricted curves to a bspline curve. 
864 Non-bspline curves are converted to bspline before concatenation.
865
866 Constructor:
867 ~~~~~~~~~~
868     GeomConvert_CompCurveToBSplineCurve::
869     GeomConvert_CompCurveToBSplineCurve(const Handle(Geom_BoundedCurve)& BasisCurve, const Convert_ParameterisationType Parameterization)
870     BasisCurve   * beginning curve;
871 ~~~~~~~~~~
872
873 Parameterization defines the ways of conversion in bspline (by default <i> Convert_TgtThetaOver2</i>).
874
875 The method to add a new curve is:
876 ~~~~
877     Standard_Boolean GeomConvert_CompCurveToBSplineCurve::
878     Add(const Handle(Geom_BoundedCurve)& NewCurve,
879     const Standard_Real Tolerance,
880     const Standard_Boolean After,
881     const Standard_Boolean WithRatio,
882     const Standard_Integer MinM)
883 ~~~~
884
885 It returns False if the curve is not C0 with the <i> BSplineCurve</i>.
886
887 Tolerance is used to check the continuity and decrease the Multiplicity 
888 at the common Knot until <i> MinM </i>. If <i> MinM = 0 </i>, the common Knot can be removed.
889
890 The parameter after defines the place for a new curve when it is possible to put 
891 the new curve before or after the <i> BasisCurve</i> (in fact, it is case when concatenated curve can be closed). 
892 It does not change the shape of the curve, but defines its first and last points.
893
894 If <i> WithRatio = Standard_True </i> the algorithm tries to reach C1 continuity.
895
896 The method to get a result is <i> Handle(Geom_BSplineCurve) GeomConvert_CompCurveToBSplineCurve::BSplineCurve() const </i>
897
898 @section OCCT_TOVW_SECTION_4 Modeling Algorithms
899
900 Modeling Algorithms module groups a wide range of 
901 topological algorithms used in modeling and geometric algorithms, called by them.
902
903 @figure{/technical_overview/images/technical_overview_ma.png}
904
905 These services are organized into the following libraries:
906
907   * @ref OCCT_TOVW_SECTION_4_1 "Geometric Tools" 
908   * @ref OCCT_TOVW_SECTION_4_2 "Topological Tools" 
909   * @ref OCCT_TOVW_SECTION_4_3 "Construction of Primitives" 
910   * @ref OCCT_TOVW_SECTION_4_4 "Boolean Operations"
911   * @ref OCCT_TOVW_SECTION_4_5 "Fillets and Chamfers" 
912   * @ref OCCT_TOVW_SECTION_4_6 "Offsets and Drafts" 
913   * @ref OCCT_TOVW_SECTION_4_7 "Features" 
914   * @ref OCCT_TOVW_SECTION_4_8 "Hidden Line Removal"
915   * @ref OCCT_TOVW_SECTION_4_9 "Sewing"  
916   * @ref OCCT_TOVW_SECTION_4_10 "Shape Healing" 
917
918 The technical overview provides only a basic description of the libraries.
919 For more details see @ref occt_user_guides__modeling_algos "Modeling Algorithms User's Guide".
920
921 See also: our web site at <a href="http://www.opencascade.org/support/training/">E-learning and Training</a>.
922
923 @subsection OCCT_TOVW_SECTION_4_1 Geometric Tools
924
925 This library provides algorithms to:
926
927   * Calculate the intersection of two 2D curves, surfaces, or a 3D curve and a surface;
928   * Project points onto 2D and 3D curves, points onto surfaces, and 3D curves onto surfaces;
929   * Construct lines and circles from constraints; 
930   * Construct curves and surfaces from constraints; 
931   * Construct curves and surfaces by interpolation.
932
933 OPEN CASCADE company also provides a product known as <a href="http://www.opencascade.org/support/products/ssp/">Surfaces from Scattered Points</a>, which allows constructing surfaces from scattered points. This algorithm accepts or constructs an initial B-Spline surface and looks for its deformation (finite elements method) which would satisfy the constraints. Using optimized computation methods, this algorithm is able to construct a surface from more than 500 000 points.
934
935 SSP product is not supplied with Open CASCADE Technology, but can be purchased separately.
936
937 @subsubsection OCCT_TOVW_SECTION_4_1_1 Intersections
938
939 The Intersections component is used to compute intersections between 2D or 3D geometrical
940 objects: 
941
942   * the intersections between two 2D curves
943   * the self-intersections of a 2D curve
944   * the intersection between a 3D curve and a surface
945   * the intersection between two surfaces.
946
947 @subsubsection OCCT_TOVW_SECTION_4_1_2 Projections
948
949 The Projections component provides functionality for 2D and 3D geometry objects for computing the following:
950
951   * the projections of a 2D point onto a 2D curve
952   * the projections of a 3D point onto a 3D curve or surface
953   * the projection of a 3D curve onto a surface.
954   * the planar curve transposition from the 3D to the 2D parametric space of an underlying plane and v. s.
955   * the positioning of a 2D gp object in the 3D geometric space.
956
957 @subsubsection OCCT_TOVW_SECTION_4_1_3 Lines and Circles from Constraints
958
959 The Lines and Circles from Constraints component provides numerous 
960 construction algorithms for 2D circles or lines described with numeric or 
961 geometric constraints in relation to other curves. These constraints enable the following to be imposed:
962
963   * the radius of a circle,
964   * the angle that a straight line makes with another straight line,
965   * the tangency of a straight line or circle in relation to a curve,
966   * the passage of a straight line or circle through a point,
967   * the circle with center in a point or curve.
968
969 For example, these algorithms enable to easily construct a circle of a given radius,
970 centered on a straight line and tangential to another circle.
971
972 The implemented algorithms are more complex than those provided 
973 by the Direct Constructions component for building 2D circles or lines.
974
975 The expression of a tangency problem generally leads to several results, according
976 to the relative positions of the solution and the circles or straight lines in relation
977 to which the tangency constraints are expressed. For example, consider the following
978 case of a circle of a given radius (a small one) which is tangential to two secant
979 circles C1 and C2:
980
981 @figure{/technical_overview/images/technical_overview_occ_0005.png,"Example of a Tangency Constraint"}
982
983 This diagram clearly shows that there are 8 possible solutions.
984
985 In order to limit the number of solutions, we can try to express the relative position
986 of the required solution in relation to the circles to which it is tangential. For
987 example, if we specify that the solution is inside the circle C1 and outside the
988 circle C2, only two solutions referenced 3 and 4 on the diagram respond to the problem
989 posed.
990
991 This technique of qualification of a solution, in relation to the curves to which
992 it is tangential, can be used in all algorithms for constructing a circle or a straight
993 line by geometric constraints. Four qualifiers are used, which specify the following:
994
995   * the solution(s) must enclose the argument, or
996   * the solution(s) must be enclosed by the argument, or
997   * the solution(s) and the argument must be external to one another, or
998   * the relative position is not qualified, i.e. all solutions apply.
999
1000 These definitions are very easy to interpret on a circle, where it is easy to identify
1001 the interior and exterior sides. In fact, for any kind of curve the interior is defined
1002 as the left-hand side of the curve in relation to its orientation.
1003
1004 OCCT implements several categories of algorithms:
1005
1006   * analytic algorithms, where solutions are obtained by the resolution of an equation, such algorithms are used when the geometries which are worked on (tangency arguments,   position of the center, etc.) are points, lines or circles;
1007   * geometric algorithms, where the solution is generally obtained by calculating the intersection of parallel or bisecting curves built from geometric arguments;
1008   * iterative algorithms, where the solution is obtained by a process of iteration.
1009
1010 For each kind of geometric construction of a constrained line or circle, OCCT provides
1011 two types of access to the user:
1012
1013   * algorithms from the package <i> Geom2dGcc </i> automatically select the algorithm best suited to the problem, both in the general case and in all types of specific cases; the used arguments  are *Geom2d* objects, while the computed solutions are <i> gp </i> objects;
1014   * algorithms from the package <i> GccAna</i> resolve the problem analytically, and can only be used when the geometries to be worked on are lines or circles; both the used arguments and the computed solutions  are <i> gp </i> objects.
1015
1016 The provided algorithms compute all solutions, which correspond to the stated geometric
1017 problem, unless the solution is found by an iterative algorithm.
1018
1019 Iterative algorithms compute only one solution, closest to an initial
1020 position. They can be used in the following cases:
1021
1022   * to build a circle, when an argument is more complex than a line or a circle, and where 
1023   the radius is not known or difficult to determine: this is the case for a circle tangential 
1024   to three geometric elements, or tangential to two geometric elements and centered on a curve;
1025   * to build a line, when a tangency argument is more complex than a line or a circle.
1026
1027 Qualified curves (for tangency arguments) are provided either by:
1028
1029   * the <i> GccEnt</i> package, for direct use by <i> GccAna</i> algorithms, or
1030   * the <i> Geom2dGcc </i> package, for general use by <i> Geom2dGcc </i> algorithms.
1031
1032 The <i> GccEnt</i> and <i> Geom2dGcc</i> packages also provide simple functions for building qualified curves in a very efficient way.
1033
1034 The <i> GccAna </i>package also provides algorithms for constructing bisecting loci between
1035 circles, lines or points. Bisecting loci between two geometric objects are such that
1036 each of their points is at the same distance from the two geometric objects. They
1037 are typically curves, such as circles, lines or conics for <i> GccAna</i> algorithms. 
1038 Each elementary solution is given as an elementary bisecting locus object (line, circle,
1039 ellipse, hyperbola, parabola), described by the <i>GccInt</i> package.
1040
1041 Note: Curves used by <i> GccAna </i> algorithms to define the geometric problem to be solved,
1042 are 2D lines or circles from the <i> gp</i> package: they are not explicitly parameterized.
1043 However, these lines or circles retain an implicit parameterization, corresponding
1044 to that which they induce on equivalent Geom2d objects. This induced parameterization
1045 is the one used when returning parameter values on such curves, for instance with
1046 the functions <i> Tangency1, Tangency2, Tangency3, Intersection2</i> and <i> CenterOn3</i> provided
1047 by construction algorithms from the <i> GccAna </i> or <i> Geom2dGcc</i> packages.
1048
1049 @subsubsection OCCT_TOVW_SECTION_4_1_4 Curves and Surfaces from Constraints
1050
1051 The Curves and Surfaces from Constraints component groups together high level functions
1052 used in 2D and 3D geometry for:
1053
1054   * creation of faired and minimal variation 2D curves
1055   * construction of ruled surfaces
1056   * construction of pipe surfaces
1057   * filling of surfaces
1058   * construction of plate surfaces
1059   * extension of a 3D curve or surface beyond its original bounds.
1060
1061 #### 2D Curves from constraints
1062
1063 Elastic beam curves have their origin in traditional methods of modeling applied 
1064 in boat-building, where a long thin piece of wood, a lathe, was forced to pass
1065 between two sets of nails and in this way, take the form of a curve based on the
1066 two points, the directions of the forces applied at those points, and the properties
1067 of the wooden lathe itself.
1068
1069 Maintaining these constraints requires both longitudinal and transversal forces to
1070 be applied to the beam in order to compensate for its internal elasticity. The longitudinal
1071 forces can be a push or a pull and the beam may or may not be allowed to slide over
1072 these fixed points.
1073
1074 The class <i> Batten</i> produces curves defined on the basis of one or more constraints
1075 on each of the two reference points. These include point and angle of tangency settings.
1076 The class <i> MinimalVariation</i> produces curves with minimal variation in curvature. 
1077 The exact degree of variation is provided by curvature settings.
1078
1079 #### Ruled Surfaces
1080
1081 A ruled surface is built by ruling a line along the length of two curves.
1082
1083 #### Pipe Surfaces
1084
1085
1086 A pipe is built by sweeping a curve (the section) along another curve (the path).
1087
1088 The following types of construction are available:
1089   * pipes with a circular section of constant radius,
1090   * pipes with a constant section,
1091   * pipes with a section evolving between two given curves.
1092
1093
1094 #### Surface filling
1095
1096 It is often convenient to create a surface from two or more curves which will form
1097 the boundaries that define the new surface.
1098
1099 A case in point is the intersection of two fillets at a corner. If the radius of
1100 the fillet on one edge is different from that of the fillet on another, it becomes
1101 impossible to sew together all the edges of the resulting surfaces. This leaves a
1102 gap in the overall surface of the object which you are constructing.
1103
1104 @figure{/technical_overview/images/technical_overview_occ_0006.png,"Intersecting filleted edges with differing radiuses"}
1105
1106 These algorithms allow you to fill this gap from two, three or four curves. This
1107 can be done with or without constraints, and the resulting surface will be either
1108 a Bezier or a BSpline surface in one of a range of filling styles.
1109
1110
1111 This package was designed with a view to handling gaps produced during fillet construction.
1112 Satisfactory results cannot be guaranteed for other uses.
1113
1114 #### Plate surfaces
1115
1116 In CAD, it is often necessary to generate a surface which has no exact mathematical
1117 definition, but which is defined by respective constraints. These can be of a mathematical,
1118 a technical or an aesthetic order.
1119
1120
1121 Essentially, a plate surface is constructed by deforming a surface so that it conforms
1122 to a given number of curve or point constraints. In the figure below, you can see
1123 four segments of the outline of the plane, and a point which have been used as the
1124 curve constraints and the point constraint respectively. The resulting surface can
1125 be converted into a BSpline surface by using the function <i> MakeApprox </i>.
1126
1127
1128 The surface is built using a variational spline algorithm. It uses the principle
1129 of deformation of a thin plate by localised mechanical forces. If not already given
1130 in the input, an initial surface is calculated. This corresponds to the plate prior
1131 to deformation. Then, the algorithm is called to calculate the final surface. It
1132 looks for a solution satisfying constraints and minimizing energy input.
1133
1134 @figure{/technical_overview/images/technical_overview_occ_0007.png,"Surface generated from four curves and a point"}
1135
1136 @figure{/technical_overview/images/technical_overview_occ_0008.png,"Surface generated from two curves and a point"}
1137
1138 #### Extension of a 3D curve or surface beyond its original bounds
1139
1140 The extension is performed according to a geometric requirement and a continuity
1141 constraint. It should be a small extension with respect to the size of the original
1142 curve or surface.
1143
1144 @subsubsection OCCT_TOVW_SECTION_4_1_5 Interpolation
1145
1146 The Interpolation Laws component provides definitions of functions: <i> y=f(x) </i>.
1147
1148 In particular, it provides definitions of:
1149
1150   * a linear function,
1151   * an <i> S </i> function, and
1152   * an interpolation function for a range of values.
1153
1154 Such functions can be used to define, for example, the evolution law of a fillet along the edge of a shape.
1155
1156 The validity of the function built is never checked: the Law package does not know for what 
1157 application or to what end the function will be used. In particular, if the function is used 
1158 as the evolution law of a fillet, it is important that the function is always positive. The user must check this.
1159
1160 @subsection OCCT_TOVW_SECTION_4_2 Topological Tools
1161
1162 This library provides algorithms to:
1163   * Tessellate shapes 
1164   * Validate shapes 
1165   * Determine the local properties of shapes 
1166   * Determine the global properties of shapes 
1167   * Perform geometric transformations
1168   * Find planes in which edges are located
1169   * Convert shapes to NURBS geometry.
1170
1171 It also furnishes a complete brep data structure for topological data structures defined in the @ref OCCT_TOVW_SECTION_3_4 "Topology" library of the Modeling Data module. The following  standard topological objects can be created:
1172   * Vertices
1173   * Edges
1174   * Faces
1175   * Wires
1176   * Polygonal wires
1177   * Shells
1178   * Solids.
1179
1180 The classes provided by the API have the following features:
1181   * The constructors of classes provide different construction methods;
1182   * The class retains different tools used to build objects as fields;
1183   * The class provides a casting method to obtain the result automatically with a function-like call. 
1184
1185 For example, to build a vertex V on a point P, you can use:
1186
1187 ~~~
1188     V = BRepBuilderAPI_MakeVertex(P);
1189 ~~~
1190 or
1191
1192 ~~~
1193     BRepBuilderAPI_MakeVertex MV(P);
1194     V = MV.Vertex();
1195 ~~~ 
1196
1197 For error handling, the <i> BRepBuilderAPI</i> commands raise only the 
1198 <i> 0StdFail_NotDone</i> exception. When <i> IsDone</i> is false for a command, 
1199 the error description can be requested from the command.
1200
1201 @subsection OCCT_TOVW_SECTION_4_3 Construction of Primitives
1202
1203 This library contained in <i> BRepPrimAPI</i> package provides an API (Application Programming Interface) for:
1204
1205   * Construction of primitives such as:
1206     * Boxes;
1207     * Cones;
1208     * Cylinders;
1209     * Prisms.
1210
1211 It is possible to create partial solids, such as a sphere limited by longitude. In real models, primitives can be used  for easy creation of specific sub-parts.
1212
1213   * Construction by sweeping along a profile:
1214     * Linear;
1215     * Rotational (through an angle of rotation).
1216
1217 Sweeps are objects obtained by sweeping a profile along a path. 
1218 The profile can be any topology and the path is usually a curve or a wire. 
1219 The profile generates objects according to the following rules:
1220
1221   * Vertices generate Edges
1222   * Edges generate Faces.
1223   * Wires generate Shells.
1224   * Faces generate Solids.
1225   * Shells generate Composite Solids.
1226
1227 It is not allowed to sweep Solids and Composite Solids. Swept constructions along complex profiles such as BSpline curves also available in the <i> BRepOffsetAPI </i> package. This API provides simple, high level calls for the most common operations.
1228
1229 @subsection OCCT_TOVW_SECTION_4_4 Boolean Operations 
1230
1231 Boolean operations allow creating new shapes from old ones by using:
1232   * Common 
1233   * Cut 
1234   * Fuse 
1235   * Section 
1236   
1237 From the viewpoint of Topology these are topological operations followed by blending (putting fillets onto edges created after the topological operation).
1238
1239 Topological operations are the most convenient way to create real industrial parts. As most industrial parts consist of several simple elements such as gear wheels, arms, holes, ribs, tubes and pipes. It is usually easy to create those elements separately and then to combine them by Boolean operations in the whole final part.
1240
1241 There exist two libraries providing Boolean Operations: 
1242   * Old Boolean Operations (BOA) provided by <i>BRepAlgo</i> package designed and developed in Open CASCADE 6x in 2000; its architecture and content are out of date.
1243   * New Boolean Operations (NBOA) provided by <i>BRepAlgoAPI</i> package designed and developed in 2001 and completely revised in 2013.
1244
1245 New Boolean Operations provide the following major benefits:
1246
1247   * The NBOA have an expandable architecture of inner sub-algorithms, which  allows to create specific algorithms for the Customers using existing inner sub-algorithms as root algorithms and to reduce the time for the development. 
1248   * The architecture of inner sub-algorithms of NBOA provides their reusability with maximal independence from the environment of NBOA. The fact allows to create specific algorithms for the Customers using these sub-algorithms as they are or as root classes and thus to reduce the time for the development. 
1249   * The architecture of NBOA is history-based. The implementation of NBOA internally sets up a correspondence between any sub-shape of the argument and its image in the result. The history is not imposed and thus it is not error-prone as it was in BOA. The fact allows direct and safely usage of the algorithm in parametric modeling.   
1250   * NBOA provide a general algorithm. It correctly processes without using the workarounds even the cases that cannot be properly processed by BOA.
1251   * The implementation of NBOA is based on NCollection classes. The usage of opportunities given by local memory allocators ( <i> NCollection_IncAllocator</i>) allows improving memory management and saving memory resources. 
1252   * NBOA use modern algorithms of OCC as auxiliary tools. For e.g. the algorithm of unbalanced binary tree of overlapped bounding boxes <i> NCollection_UBTree</i>. The usage of the algorithm allows to improve the performance of NBOA if there is a big number of sub-shapes in the arguments.
1253
1254 Boolean Operations have the following types of the arguments and produce the following results:
1255 * For arguments having the same shape type (e.g. SOLID / SOLID) the type of the resulting shape will be a COMPOUND, containing shapes of this type;
1256 * For arguments having different shape types (e.g. SHELL / SOLID) the type of the resulting shape will be a COMPOUND, containing shapes of the type that is the same as that of the low type of the argument. Example: For SHELL/SOLID the result is a COMPOUND of SHELLs. 
1257 * For arguments with different shape types some of Boolean Operations can not be done using the default implementation, because of a non-manifold type of the result. Example: the FUSE operation for SHELL and SOLID can not be done, but the CUT operation can be done, where SHELL is the object and SOLID is the tool.
1258 * It is possible to perform Boolean Operations on arguments of the COMPOUND shape type. In this case each compound must not be heterogeneous, i.e. it must contain equidimensional shapes (EDGEs or/and WIREs, FACEs or/and SHELLs, SOLIDs). SOLIDs inside the COMPOUND must not contact (intersect or touch) each other. The same condition should be respected for SHELLs or FACEs, WIREs or EDGEs.
1259 * Boolean Operations for COMPSOLID type of shape are not supported.
1260
1261 @subsection OCCT_TOVW_SECTION_4_5 Fillets and Chamfers
1262
1263 This library provides algorithms to make fillets and chamfers on shape edges.
1264 The following cases are addressed:
1265
1266   * Corners and apexes with different radii; 
1267   * Corners and apexes with different concavity. 
1268
1269 If there is a concavity, both surfaces that need to be extended and those, which do not, are processed.
1270
1271 @subsection OCCT_TOVW_SECTION_4_6 Offsets, Drafts and Sweeps
1272
1273 These classes provide the following services:
1274
1275   * Creation of offset shapes and their variants such as: 
1276     * Hollowing; 
1277     * Shelling; 
1278     * Lofting; 
1279   * Creation of tapered shapes using draft angles;
1280   * Creation of sweeps.
1281
1282 @subsection OCCT_TOVW_SECTION_4_7 Features
1283
1284 This library contained in *BRepFeat* package is necessary for creation and manipulation of both form and mechanical features in a Boundary Representation framework.
1285
1286 ### Form Features
1287
1288 The form features are depressions or protrusions including the following types:
1289
1290   * Cylinder;
1291   * Draft Prism;
1292   * Prism;
1293   * Revolved feature;
1294   * Pipe.
1295
1296 Depending on whether you wish to make a depression or a protrusion, 
1297 you can choose either to remove matter (Boolean cut: Fuse equal to 0) or to add it (Boolean fusion: Fuse equal to 1).
1298
1299 The semantics of form feature creation is based on the construction of shapes:
1300
1301   * for a certain length in a certain direction;
1302   * up to the limiting face;
1303   * from the limiting face at a height;
1304   * above and/or below a plane.
1305
1306 The shape defining the construction of a feature can be 
1307 either a supporting edge or a concerned area of a face.
1308
1309 In case of supporting edge, this contour can be attached to a face of the basis shape by binding. When the contour is bound to this face, the information that the contour will slide on the face becomes available 
1310 to the relevant class methods. In case of the concerned area of a face, you can, for example, cut it out and move it at a different height, which defines the limiting face of a protrusion or depression.
1311
1312 Topological definition with local operations of this sort makes calculations simpler 
1313 and faster than a global operation. The latter would entail a second phase 
1314 of removing unwanted matter to get the same result.
1315
1316 ### Mechanical Features
1317
1318 Mechanical features include ribs, protrusions and grooves (or slots), 
1319 depressions along planar (linear) surfaces or revolution surfaces.
1320
1321 The semantics of mechanical features is based on giving thickness to a contour. 
1322 This thickness can either be
1323
1324   * unilateral 
1325   * on one side of the contour 
1326   * or bilateral 
1327   * on both sides. 
1328
1329 As in the semantics of form features, the thickness is defined 
1330 by construction of shapes in specific contexts.
1331
1332 However, in case of mechanical features, development contexts differ. 
1333 Here they include extrusion:
1334
1335   * to a limiting face of the basis shape;
1336   * to or from a limiting plane;
1337   * to a height.
1338   
1339 ### Splitting and Gluing  
1340   
1341 It can be required to perform low-level splitting/gluing operations on shapes. Open CASCADE provides the following algorithms for that:
1342
1343 - **Split shape** allows defining particular faces in a shape and new edges which should split that faces. Upon completion the algorithm gives the part of the shape which is situated on the left side of the line composed from new edges. In combination with the Section algorithm it is a powerful tool for partitioning shapes.
1344 - **Glue shapes** allows to defining pairs of faces and pairs of edges of two neighboring shapes to glue. Upon completion the algorithm gives the glued shape with cut out parts of faces inside the shape.
1345
1346   
1347
1348 @subsection OCCT_TOVW_SECTION_4_8 Hidden Line Removal
1349
1350 This library provides two algorithms: <i> HLRBRep_Algo</i> and <i> HLRBRep_PolyAlgo</i>  to define the lines of a shape hidden in a given projection.  These lines can be shown or hidden to have the precision required in industrial design. To do this, the Hidden Line Removal component provides 
1351
1352 These algorithms remove or indicate lines hidden by surfaces. 
1353
1354 For a given projection, they calculate a set of lines characteristic of the object  being represented. They are also used in conjunction with extraction utilities,   which reconstruct a new, simplified shape from a selection of calculation results. 
1355 This new shape is made up of edges, which represent the lines of the visualized shape in a plane.   This plane is the projection plane.
1356
1357 The algorithm <i> HLRBRep_Algo</i> allows working with the shape itself,  while <i> HLRBRep_PolyAlgo </i>works with its polyhedral simplification. When you use <i> HLRBRep_Algo</i>, you obtain an exact result, whereas, when you use <i> HLRBRep_PolyAlgo</i>, you reduce computation time but obtain polygonal segments.
1358
1359
1360 @subsection OCCT_TOVW_SECTION_4_9 Sewing
1361
1362 Sewing allows creation of connected topology (shells and wires) from a set of separate topological elements (faces and edges). For example, Sewing can be used to create of shell from a compound of separate faces. 
1363
1364 It is important to distinguish between sewing and other procedures, which modify the geometry, such as filling holes or gaps, gluing, bending curves and surfaces, etc.
1365
1366 Sewing does not change geometrical representation of the shapes. Sewing applies to topological elements (faces, edges) which are not connected but can be connected because they are geometrically coincident : it adds the information about topological connectivity. Already connected elements are left untouched in case of manifold sewing.
1367
1368 Let us define several terms:
1369 * **Floating edges** do not belong to any face;
1370 * **Free boundaries** belong to one face only;
1371 * **Shared edges** belong to several faces, (i.e. two faces in a manifold topology).
1372 * **Sewn faces** should have edges shared with each other.
1373 * **Sewn edges** should have vertices shared with each other.
1374
1375 ### Sewing Algorithm
1376
1377 The sewing algorithm is one of the basic algorithms used for shape processing, therefore its quality is very important.
1378
1379 There are two implementations of sewing algorithm: 
1380 * **Standard** provided by *BRepAlgo_Sewing*, and
1381 * **Advanced** provided by *ShapeUpgrade_Sewing*, which is a sub-class of *BRepAlgo_Sewing*. 
1382
1383 The only difference between them is that Advanced sewing performs some additional fixes provided by Shape Healing (use of *ShapeFix_Shape*) and improves some particular cases, such as closed surfaces. The principle and architecture of the algorithm itself remain the same.
1384
1385 Class *BRepAlgo_Sewing* provides methods implementing sewing algorithms: 
1386 * loading initial data for global or local sewing; 
1387 * setting customization parameters, such as special operation modes, tolerances and output results;
1388 * applying analysis methods that can be used to obtain connectivity data required by external algorithms;
1389 * sewing of the loaded shapes. 
1390
1391 Sewing supports working mode with big value tolerance. It is not necessary to repeat sewing step by step while smoothly increasing tolerance.
1392
1393 It is also possible to sew edges to wire and to sew locally separate faces and edges from a shape.
1394
1395 The Sewing algorithm can be subdivided into several independent stages, some of which can be turned on or off using Boolean or other flags. 
1396
1397 In brief, the algorithm should find a find a set of merge candidates for each free boundary, filter them according to certain criteria, and finally merge the found candidates and  build the resulting sewn shape.
1398
1399 Each stage of the algorithm or the whole algorithm can be adjusted with the following parameters: 
1400 * **Working tolerance** defines the maximal distance between topological elements which can be sewn. It is not ultimate that such elements will  be actually sewn as many other criteria are applied to make the final decision.
1401 * **Minimal tolerance** defines the size of the smallest element (edge) in the resulting shape. It is declared that no edges with size less than this value are created after sewing. If encountered, such topology becomes degenerated.
1402 * **Non-manifold mode** enables sewing of non-manifold topology. 
1403
1404
1405 ### Tolerance Management
1406
1407 To produce a closed shell, Sewing allows specifying the value of working tolerance, exceeding the size of small faces belonging to the shape.
1408
1409 However, if we produce an open shell, it is possible to get incorrect sewing results if the value of working tolerance is too large (i.e. it exceeds the size of faces lying on an open boundary).
1410
1411 The following recommendations can be proposed for tuning-up the sewing process:
1412 - Use as small working tolerance as possible. This will reduce the sewing time and, consequently, the number of incorrectly sewn edges for shells with free boundaries.
1413 - Use as large minimal tolerance as possible. This will reduce the number of small geometry in the shape, both original and appearing after cutting.
1414 - If it is expected to obtain a shell with holes (free boundaries) as a result of sewing, the working tolerance should be set to a value not greater than the size of the smallest element (edge) or smallest distance between elements of such free boundary. Otherwise the free boundary may be sewn only partially.
1415 - It should  be mentioned that the Sewing algorithm is unable to understand which small (less than working tolerance) free boundary should be kept and which should be sewn.
1416
1417 ### Manifold and Non-manifold Sewing
1418
1419 To create one or several shells from a set of faces, sewing merges edges, which belong to different faces or one closed face. 
1420
1421 Face sewing supports manifold and non manifold modes. Manifold mode can produce only a manifold shell. Sewing should be used in the non manifold mode to create non manifold shells.
1422
1423 Manifold sewing of faces merges only two nearest edges belonging to different faces or one closed face with each other. Non manifold sewing of faces merges all edges at a distance less than the specified tolerance.
1424
1425 For a complex topology it is advisable to apply first the manifold sewing and then the non manifold sewing a minimum possible working tolerance. However, this is not necessary for a easy topology. 
1426
1427 Giving a large tolerance value to non manifold sewing will cause a lot of incorrectness since all nearby geometry will be sewn.
1428
1429 ### Local Sewing
1430 If a shape still has some non-sewn faces or edges after sewing, it is possible to use local sewing with a greater tolerance.
1431
1432 Local sewing is especially good for open shells. It allows sewing an unwanted hole in one part of the shape and keeping a required hole, which is smaller than the working tolerance specified for the local sewing in the other part of the shape. Local sewing is much faster than sewing on the whole shape.
1433
1434 All preexisting connections of the whole shape are kept after local sewing. 
1435
1436 @subsection OCCT_TOVW_SECTION_4_10 Shape Healing
1437
1438 Shape Healing library provides algorithms to modify the geometry and topology of OCCT shapes and to make them maximally appropriate for use by OCCT, including, but not limited to the following operations:
1439 * analyze shape characteristics and, in particular, identify the shapes that do not comply with OCCT geometry and topology  validity rules by analyzing geometrical objects and topology: 
1440         - check edge and wire consistency;
1441         - check edge order in a wire;
1442         - check the orientation of face boundaries;
1443         - analyze shape tolerances;
1444         - return closed and open wires in a boundary.
1445 * fix incorrect or problem shapes:
1446         - provide consistency between a 3D curve and its corresponding parametric curve;
1447         - repair defective wires;
1448         - fit the shapes to a user-defined tolerance value;
1449         - fill gaps between patches and edges. 
1450 * upgrade and change shape characteristics:
1451         - reduce curve and surface degree;
1452         - split shapes to obtain C1 continuity;
1453         - convert any types of curves or surfaces to Bezier or Bspline curves or surfaces and back;
1454         - split closed surfaces and revolution surfaces.
1455
1456 Each sub-domain of Shape Healing has its own scope of functionality:
1457
1458 | Sub-domain | Description | Impact on the shape |
1459 | :--- | :---- | :---- |
1460 | Analysis | Exploring shape properties, computing shape features, detecting violation of OCCT requirements. | The shape itself is not modified. |
1461 | Fixing  | Fixing shape to meet the OCCT requirements. | The shape may change its original form: modification, removal or creation of sub-shapes, etc.) |
1462 | Upgrade | Shape improvement for better usability in OCCT or other algorithms. | The shape is replaced with a new one, but geometrically they are the same. |
1463 | Customization | The shape representation is modified to fit specific needs. | The shape is not modified, only the form of its representation is modified. |
1464 | Processing | Mechanism of shape modification via a user-editable resource file. | |
1465
1466 The technical overview provides only a basic description of the libraries. 
1467 For more details refer to @ref occt_user_guides__shape_healing "Shape Healing User's guide".
1468
1469 See also: our web site at <a href="http://www.opencascade.org/support/training/">E-learning and Training</a>.
1470
1471
1472 @subsection OCCT_TOVW_SECTION_4_11 Examples
1473
1474 ### How to compute the state of a point on a face:
1475
1476
1477 Use <i> BRepTools::Pnt </i> to get the point from your vertex.
1478 Your shape must be of the <i> TopoDS_Shape </i>type.
1479 If it is, you can use <i> BRepTopAdaptor_FClass2d </i>class. For example:
1480
1481 ~~~~~
1482     BRepTopAdaptor_FClass2d::Load (to load the solid )
1483     BRepTopAdaptor_FClass2d::Perform (to compute the state of the point )
1484     BRepTopAdaptor_FClass2d::State (to get the TopAbs_State). 
1485 ~~~~~
1486
1487
1488 ### How to compute the state of a point in a solid:
1489
1490
1491 Use <i>BRepTools::Pnt </i> to get the point from your vertex.
1492 Your shape must be of the <i> TopoDS_Solid</i> type.
1493
1494 If it is, you can use the <i> BRepClass3d_SolidClassifier </i> class, for example:
1495
1496 ~~~~~
1497     BRepClass3d_SolidClassifier::Load (to load the solid)
1498     BRepClass3d_SolidClassifier::Perform (to compute the state of the point)
1499     BRepClass3d_SolidClassifier::State (to get a TopAbs_State object)
1500     BRepClass3d_SolidClassifier inherits BRepclass3d_SClassifier
1501 ~~~~~
1502
1503 ### How to connect a set of contiguous but independent faces
1504
1505
1506 A unique topological object can be obtained in this way using the class 
1507 <i> Sewing</i> from the <i> BRepOffsetAPI </i>package which produces a shell as a result.
1508
1509 ~~~~~
1510     BRepOffsetAPI_Sewing Sew;
1511     Sew.Add(Face1); 
1512     Sew.Add(Face2); 
1513     ...
1514     Sew.Add(Facen); 
1515     Sew.Perform();
1516     TopoDS_Shape result= Sew.SewedShape();
1517 ~~~~~
1518
1519 @note The sewing algorithm uses a tolerance to assemble the faces by sewing them along common edges. You must therefore check the gap between faces before sewing or adjust the value of the tolerance according to the real gap of the geometry.
1520
1521 If all faces have been sewed correctly, the result is a shell. Otherwise, it is a compound. After a successful sewing operation all faces have a coherent orientation.
1522
1523 For more information, refer to the entry for this class in reference documentation.
1524
1525 ### How to check the orientation of a solid
1526
1527 If you want to create a solid from a closed shell, you must first check the orientation to determine if you have to reverse the shell or not (for example after creating a closed shell from a sewing operation). To do this, use the <i> PerformInfinitePoint</i> method from the <i> BrepClass3D_SolidClassifier</i> class.
1528
1529 ~~~~~
1530     BRepClass3d_SolidClassifier clas3d(aShell);
1531     clas3d.PerformInfinitePoint(Precision::Confusion());
1532     if (clas3d.State() == TopAbs_IN)
1533     newShell.Reverse();
1534     BRepBuilderAPI_MakeSolid aSolid(aShell);
1535 ~~~~~
1536
1537
1538
1539 @section OCCT_TOVW_SECTION_4a Mesh
1540
1541 In addition to support of exact geometrical representation of 3D objects Open CASCADE Technology provides functionality to work with tessellated representations of the objects, in the form of mesh.
1542
1543 Open CASCADE Technology mesh functionality provides:
1544 - data structures to store surface mesh data associated to shapes, and some basic algorithms to handle these data
1545 - data structures and algorithms to build surface triangular mesh from *BRep* objects (shapes).
1546 - tools to extend 3D visualization capabilities of Open CASCADE Technology with displaying meshes along with associated pre- and post-processor data.
1547
1548 Additionally, Open CASCADE Technology includes two mesh converters:
1549 - VRML converter translates Open CASCADE shapes to VRML 1.0 files (Virtual Reality Modeling Language). Open CASCADE shapes may be translated in two representations: shaded or wireframe. A shaded representation present shapes as sets of triangles computed by a mesh algorithm while a wireframe representation present shapes as sets of curves.
1550 - STL converter translates Open CASCADE shapes to STL files. STL (STtereoLithography) format is widely used for rapid prototyping.
1551
1552 Open CASCADE SAS also offers Advanced Mesh Products:
1553 - <a href="http://www.opencascade.org/support/products/omf">Open CASCADE Mesh Framework (OMF)</a>
1554 - <a href="http://www.opencascade.org/support/products/emesh">Express Mesh</a>
1555
1556 Besides, we can efficiently help you in the fields of surface and volume meshing algorithms, mesh optimization algorithms etc. If you require a qualified advice about meshing algorithms, do not hesitate to benefit from the expertise of our team in that domain.
1557
1558 The projects dealing with numerical simulation can benefit from using SALOME - an Open Source Framework for CAE with CAD data interfaces, generic Pre- and Post- F.E. processors and API for integrating F.E. solvers.
1559
1560 Learn more about SALOME platform on http://www.salome-platform.org
1561
1562 @subsection OCCT_TOVW_SECTION_4a_1 Shape Translation 
1563
1564 @subsubsection OCCT_TOVW_SECTION_4a_1_1 STL Format
1565
1566 OCCT includes a module for translating OCCT shapes to STL (Stereolithography) format. 
1567 STL is a format designed for rapid prototyping. 
1568 It is intended to send geometric data (volumic) to stereolithography machines, 
1569 which can read and interpret such data. These machines can transform a volumic model 
1570 to a physical prototype made of plastic, by using laser to coagulate material, 
1571 which corresponds to the volume, and set free the material around. 
1572 STL defines these surfaces by triangles. 
1573 Thus, no machining is required to switch from a virtual model to a physical one.
1574
1575 Since STL files can only include solids described by their mesh structures, 
1576 OCCT shapes, which are intended to be written, must be solids, 
1577 components of solids or closed shells with a correct orientation.
1578
1579 When translating shapes to STL format, remember that all references 
1580 to shapes mean references to OCCT shapes unless otherwise explicitly defined. 
1581 In addition, sets of faces or unclosed shells may also be translated but visualization in foreign viewers may be incorrect.
1582
1583 @subsection OCCT_TOVW_SECTION_4a_1_2 VRML Format
1584
1585 The Virtual Reality Modeling Language (VRML) is a language for describing multi-participant interactive simulations, virtual worlds networked via the Internet and hyperlinked with the World Wide Web. VRML is a format designed for animated visualization of solids.
1586 OCCT includes a module for translating OCCT shapes to VRML (Virtual Reality Modeling Language). 
1587 OCCT shapes may be translated in two representations (states): shaded or wireframe. 
1588 Since shaded VRML format files include only solids described by their mesh structures, the OCCT shapes intended to be written must be solids, components of solids or closed shells with a correct orientation.
1589
1590 Please, note:
1591
1592   * all references to shapes indicate OCCT shapes unless otherwise explicitly stated;
1593   * sets of faces or unclosed shells may also be translated to shaded VRML format but visualization with foreign viewers may be incorrect.
1594   
1595 @section OCCT_TOVW_SECTION_5 Visualization
1596
1597 Visualization in Open CASCADE Technology is based on the separation of modeling data you want to display and select, and on the graphical presentation of its structure.
1598
1599 For visualizing data structures, OCCT provides ready-to-use algorithms, which create graphic presentations from geometric models. These data structures may be used with the viewers supplied, and can be customized to take the specificity of your application into account.
1600
1601 Display is managed through presentation services, and selection in its turn is managed through selection services. With these services, data structures and algorithms are provided to display objects of an application and to support graphical selection of these objects.
1602
1603 Application Interactive Services (AIS) are provided to manage displaying, detection and selection of graphical presentations. These services associate data structures and interactive objects.
1604
1605 The technical overview provides only a basic description of the libraries.
1606 For more details see @ref occt_user_guides__visualization "Visualization User's Guide".
1607
1608 See also: our web site at <a href="http://www.opencascade.org/support/training/">E-learning and Training</a>.
1609
1610 @figure{/technical_overview/images/technical_overview_viz.png}
1611
1612 @subsection OCCT_TOVW_SECTION_5_1 3D Graphics
1613
1614 3D Graphics provided by  <i>Graphic3d</i> package supports three-dimensional manipulation  of 3d graphic objects called structures. Structures, are made up of groups that unite primitives, such as polylines, planar polygons with or without holes, text and markers, and attributes,  such as color, transparency, reflection, line type, line width, and text font.
1615 A group is the smallest editable element of a structure.
1616
1617 A structure can be displayed, erased, highlighted and transformed.
1618 Structures can be connected to form a hierarchy of structures, composed by transformations.
1619 The viewer can perform global manipulation of structures.
1620
1621 <i> Visual3d </i> package contains the group of classes required to implement commands for 3D viewer. The viewer manages views and light sources.
1622
1623 Most types of primitives supported by <i> Graphic3d</i> can be dumped to a vector file format such as PDF and PostScript. Export to vector formats is implemented with help of <i> GL2PS</i> library.
1624
1625 @subsection OCCT_TOVW_SECTION_5_2 3D Visualization
1626
1627 This library provides services for:
1628
1629   * Selection of 3D data structures 
1630   * Presentation of 3D data structures 
1631
1632 Access to 3D presentation and selection is provided through AIS (Application Interactive Services). 
1633 This package is a high-level interface that offers access to the lower-level presentation and selection services. 
1634 AIS expand this underlying functionality with standard 3D selection attributes, presentation management,  and standard 3D presentation attributes, and manages it in the definition of GUI viewers. To implement these services, AIS package includes the following:
1635
1636   * Interactive context 
1637   * Interactive objects 
1638   * A graphic attributes manager 
1639   * Selection filters 
1640
1641 ### Interactive Context
1642
1643 Interactive context pilots 3D visualizations and selections. 
1644 The interactive context allows you to manage, in a transparent way, graphic and "selectable" behavior of interactive objects which is not yet defined in the predefined types of these objects.
1645
1646 AIS have two operating context types. The default neutral point type allows easily visualizing and selecting entire interactive objects, which have been loaded into the context. 
1647 Opening a local context allows preparing and using a temporary selection environment to select a part of an interactive object.
1648
1649 ### Interactive Objects
1650
1651 Entities which are visualized and selected in the AIS viewer are objects.  They connect the underlying reference geometry of a model to its graphic representation in AIS. You can use predefined OCCT classes of standard interactive objects for which all necessary functions have already been programmed, or, in case you are an advanced user, you can implement your own classes of interactive objects.
1652
1653 ### Graphic Attributes Manager
1654
1655 Graphic attributes manager, or AIS Drawer, stores graphic attributes  for specific interactive objects and for interactive objects controlled by interactive context.
1656
1657 Initially, all drawer attributes are filled out with the predefined  values which will define the default 3D object appearance.
1658
1659 When an interactive object is visualized, the required graphic attributes are first taken from its own drawer if one exists, or from the context drawer if no specific drawer for that type of object exists.
1660
1661 ### Selection Filters
1662
1663 An important aspect in selection is the filtering of entities you to select. 
1664 Selection filters allow you to refine the dynamic detection context, which you want to put into effect. Some of these filters can be used at the Neutral Point, others in an open local context only. You can also program your own filters and load them into the context.
1665
1666
1667 @subsection OCCT_TOVW_SECTION_5_3 Application Interactive Services (AIS)
1668
1669 Application Interactive Services provide the means to create links between an application GUI viewer and the packages which are used to manage selection and presentation. The tools AIS defined for this include different sorts of entities: the selectable viewable objects themselves and the context and attribute managers to define their selection and display.
1670
1671 To orient the user as he works in a modeling environment, views and selections must be comprehensible. 
1672 There must be several different sorts of selectable and viewable object defined. 
1673 These must also be interactive, that is, connecting graphic representation and the underlying reference geometry. These entities are called Interactive Objects, and are divided into four types:
1674   * the Datum
1675   * the Relation
1676   * the Object
1677   * None.
1678
1679 The Datum groups together the construction elements such as lines, circles, points, trihedrons, plane trihedrons, planes and axes.
1680 The Relation is made up of constraints on one or more interactive shapes and the corresponding reference geometry. For example, you might want to constrain two edges in a parallel relation. This constraint is considered as an object in its own right, and is shown as a sensitive primitive. This takes the graphic form of a perpendicular arrow marked with the || symbol and lying between the two edges.
1681
1682 The Object type includes topological shapes, and connections between shapes.
1683
1684 None, in order not to eliminate the object, tells the application to look further until it finds an object definition in its generation which is accepted.
1685
1686 Inside these categories, you have the possibility of an additional characterization by means of a signature. The signature provides an index to the further characterization. By default, the Interactive Object has a None type and a signature of 0 (equivalent to None.) 
1687 If you want to give a particular type and signature to your interactive object, you must redefine the two virtual methods: <i> Type</i> and <i> Signature</i>.
1688
1689 In the C++ inheritance structure of the package, each class representing a specific Interactive Object inherits <i> AIS_InteractiveObject</i>. Among these inheriting classes, <i> AIS_Relation</i> functions as the abstract mother class for inheriting classes defining display of specific relational constraints and types of dimension. Some of these include:
1690
1691   * display of constraints based on relations of symmetry, tangency, parallelism and concentricity
1692   * display of dimensions for angles, offsets, diameters, radii and chamfers.
1693
1694 No viewer can show everything at once with any coherence or clarity. 
1695 Views must be managed carefully both sequentially and at any given instant. 
1696 Another function of the view is that of a context to carry out design in. 
1697 The design changes are applied to the objects in the view and then extended 
1698 to the underlying reference geometry by a solver. 
1699 To make sense of this complicated visual data, several display and selection tools are required. 
1700 To facilitate management, each object and each construction element has a selection priority. 
1701 There are also means to modify the default priority.
1702
1703 To define an environment of dynamic detection, you can use standard filter classes or create your own. 
1704 A filter questions the owner of the sensitive primitive in local context to determine 
1705 if it has the desired qualities. If it answers positively, it is kept. If not, it is rejected.
1706
1707 The standard filters supplied in AIS include:
1708
1709   * <i> AIS_AttributeFilter</i>
1710   * <i> AIS_SignatureFilter</i>
1711   * <i> AIS_TypeFilter</i>.
1712
1713 Only the type filter can be used in the default operating mode, the neutral point. 
1714 The others can only be used in open local contexts.
1715
1716 Neutral point and local context constitute the two operating modes of the 
1717 central entity which pilots visualizations and selections, the Interactive Context. 
1718 It is linked to a main viewer and if you like, a trash bin viewer as well.
1719
1720 The neutral point, which is the default mode, allows you to easily visualize and select interactive objects which have been loaded into the context. Opening local contexts allows you to prepare and use a temporary selection environment without disturbing the neutral point. 
1721 A set of functions allows you to choose the interactive objects which you want to act on, the selection modes which you want to activate, and the temporary visualizations which you will execute. When the operation is finished, you close the current local context and return to the state in which you were before opening it (neutral point or previous local context).
1722
1723 An interactive object can have a certain number of graphic attributes, which are specific to it, such as visualization mode, color, and material. By the same token, the interactive context has a set of graphic attributes, the Drawer which is valid by default for the objects it controls. 
1724 When an interactive object is visualized, the required graphic attributes are first taken from the object's own <i> Drawer</i> if one exists, or from the context drawer for the others.
1725
1726
1727 @subsection OCCT_TOVW_SECTION_5_4 Presentation
1728
1729 ### Presentation Management
1730    
1731 <i> PrsMgr</i> package provides low level services and is only to be used when you do not want to use the services provided by AIS. It manages the display through the following services:
1732   * supplying a graphic structure for the object to be presented
1733   * recalculating presentations when required, e.g. by moving the object or changing its color
1734   * defining the display mode of the object to be presented; in the case of <i> AIS_Shape</i>, for example, this determines whether the object is to be displayed in wireframe (0) or shading (1) mode.
1735
1736 Note that each new Interactive Object must have all its display modes defined.
1737
1738 ### Presentations of Geometry
1739
1740 The Presentations of Geometry component provides services for advanced programmers to extend the Application Interactive Services component, AIS. 
1741 This would prove necessary in situations where new Interactive Objects were required.
1742
1743 The <i> StdPrs </i>package provides standard display tools for specific geometries and topologies whereas <i> Prs3d</i> provides those for generic objects. 
1744 Among these classes are definitions of the display of the specific geometry or topology in various display modes such as wireframe, shading or hidden line removal mode.
1745
1746 ### Presentation of Dimensions
1747
1748  <i> DsgPrs </i> package provides tools for display of dimensions, relations and XYZ trihedrons.
1749
1750 @subsection OCCT_TOVW_SECTION_5_5 Selection
1751
1752 Selection of 3D data structures is provided using various algorithms. 
1753   
1754 ### Basic Selection
1755
1756 The <i> SelectBasics </i>package provides the following services:
1757
1758   * the root definition of the sensitive primitive, a selectable entity in a view
1759   * the definition of the owner of a sensitive primitive; this entity relates the primitive to the application entity which is to be selected in the view.
1760
1761 ### Standard Selections
1762
1763  The <i> StdSelect</i> package provides the following services:
1764
1765   * definition of selection modes for topological shapes
1766   * definition of several filter standard <i> Selection2d.ap </i> classes
1767   * 3D viewer selectors.
1768
1769 Note that each new Interactive Object must have all its selection modes defined.
1770 The <i>Select3D</i> package provides the following services:
1771
1772   * definition of standard   3D sensitive primitives such as points, curves and faces;
1773   * recovery of the bounding boxes in the 2D graphic selection space, if required;
1774   * a 3D-2D projector.
1775
1776 ### Selection Management
1777  
1778 The <i> SelectMgr</i> package provides low level services and classes 
1779 <i> SelectMgr_SelectionManager</i> and <i> SelectMgr_ViewerSelector </i>.
1780 They can be used when you do not want to use the services provided by <i> AIS</i>.
1781
1782 <i> SelectMgr </i> manages the process of dynamic selection through the following services:
1783
1784   * activating and deactivating selection modes for Interactive Objects
1785   * adding and removing viewer selectors
1786   * definitions of abstract filter classes
1787
1788 The principle of graphic selection consists in representing the objects which you want 
1789 to select by a bounding box in the selection view. 
1790 The object is selected when you use the mouse to designate the zone produced by the object.
1791
1792 To realize this, the application creates a selection structure 
1793 which is independent of the point of view. This structure is made up 
1794 of sensitive primitives which have one owner object associated to each of them. 
1795 The role of the sensitive primitive is to reply to the requests of the selection algorithm 
1796 whereas the owner's purpose is to make the link between 
1797 the sensitive primitive and the object to be selected. 
1798 Each selection structure corresponds to a selection mode which defines the elements that can be selected.
1799
1800 For example, to select a complete geometric model, 
1801 the application can create a sensitive primitive for each face 
1802 of the interactive object representing the geometric model. 
1803 In this case, all the primitives share the same owner. 
1804 On the other hand, to select an edge in a model, 
1805 the application must create one sensitive primitive per edge.
1806
1807 ~~~~
1808
1809 void InteractiveBox::ComputeSelection
1810       (const Handle(SelectMgr_Selection)& Sel,
1811        const Standard_Integer Mode){
1812   
1813 switch(Mode){
1814 case 0:
1815 // locating the whole box by making its faces sensitive ...
1816          {
1817        Handle(SelectMgr_EntityOwner) Ownr = new
1818        SelectMgr_EntityOwner(this,5);
1819        for(Standard_Integer I=1;I<=Nbfaces;I++){
1820        Sel->Add(new Select3D_SensitiveFace
1821                (Ownr,[array of the vertices] face I);
1822        break;
1823        }
1824
1825 case 1:         // locates the   edges
1826          {
1827   
1828        for(Standard_Integer i=1;i<=12;i++){
1829                         // 1 owner per edge...
1830          Handle(mypk_EdgeOwner) Ownr =
1831                   new mypk_EdgeOwner(this,i,6);
1832                         // 6->priority
1833          Sel->Add(new
1834          Select3D_SensitiveSegment
1835                   (Ownr,firstpt(i),lastpt(i));
1836        }
1837        }
1838 }
1839
1840 ~~~~
1841
1842 The algorithms for creating selection structures store the sensitive primitives in a 
1843 <i> SelectMgr_Selection </i> object. To do this, a set of ready-made sensitive primitives is supplied 
1844 in the <i> Select2D </i>and <i> Select3D </i>packages. New sensitive primitives can be defined through inheritance 
1845 from <i> SensitiveEntity</i>. For the application to make its own objects selectable,
1846  it must define owner classes inheriting <i> SelectMgr_EntityOwner</i>.
1847
1848 For any object inheriting from <i> AIS_InteractiveObject</i>, you redefine 
1849 its <i> ComputeSelection</i> functions. In the example below there are different modes 
1850 of selection on the topological shape contained within the interactive object, 
1851 selection of the shape itself, the vertices, the edges, the wires, the faces.
1852
1853 ~~~~
1854     void MyPack_MyClass::ComputeSelection(
1855                 const Handle(SelectMgr_Selection)& aSelection,
1856                 const Standard_Integer aMode)
1857     {
1858        switch(aMode){
1859        case 0:
1860        StdSelect_BRepSelectionTool::Load(
1861           aSelection,this,myShape,TopAbs_SHAPE);
1862        break;
1863        }
1864        case 1:
1865        StdSelect_BRepSelectionTool::Load(
1866           aSelection,this,myShape,TopAbs_VERTEX);
1867        break;
1868        }
1869        case 2:
1870        StdSelect_BRepSelectionTool::Load(
1871           aSelection,this,myShape,TopAbs_EDGE);
1872        break;
1873        }
1874        case 3:
1875        StdSelect_BRepSelectionTool::Load(
1876           aSelection,this,myShape,TopAbs_WIRE);
1877        break;
1878        }
1879        case 4:
1880        StdSelect_BRepSelectionTool::Load(
1881           aSelection,this,myShape,TopAbs_FACE);
1882        break;
1883        }
1884     }
1885 ~~~~
1886
1887 The <i> StdSelect_BRepSelectionTool </i> object provides a high level service 
1888 which will make the shape <i> myShape</i> selectable when the <i> AIS_InteractiveContext</i> is asked to display your object.
1889
1890 Note:
1891
1892 The traditional way of highlighting selected entity owners 
1893 adopted by Open CASCADE Technology assumes that each entity owner 
1894 highlights itself on its own. This approach has two drawbacks: 
1895
1896   * each entity owner has to maintain its own <i>Prs3d_Presentation object</i>, that results in large memory overhead for thousands of owners;
1897   * drawing selected owners one by one is not efficient from the OpenGL usage viewpoint.
1898
1899 That is why a different method has been introduced. 
1900 On the basis of <i> SelectMgr_EntityOwner::IsAutoHilight() </i> return value 
1901 <i> AIS_LocalContext </i> object either uses the traditional way of highlighting 
1902 ( <i> IsAutoHilight() </i> returned true) or groups such owners according to their 
1903 Selectable Objects and finally calls <i> SelectMgr_SelectableObject::HilightSelected()</i> or 
1904 <i> ClearSelected()</i>, passing a group of owners as an argument. 
1905
1906 Hence, an application can derive its own interactive object and redefine <i> HilightSelected()</i>,
1907  <i> ClearSelected()</i> and <i> HilightOwnerWithColor()</i> virtual methods 
1908  to take advantage of such OpenGL technique as arrays of primitives. 
1909  In any case, these methods should at least have empty implementation.
1910
1911  The <i> AIS_LocalContext::UpdateSelected(const Handle(AIS_InteratciveObject)&, Standard_Boolean) 
1912  </i> method can be used for efficient redrawing a selection presentation for a given interactive object from an application code.
1913
1914 Additionally, the <i> SelectMgr_SelectableObject::ClearSelections() </i> 
1915 method now accepts an optional Boolean argument. 
1916 This parameter defines whether all object selections should be flagged for further update or not. 
1917 This improved method can be used to re-compute an object selection (without redisplaying the object completely) 
1918 when some selection mode is activated not for the first time.
1919
1920
1921 @subsection OCCT_TOVW_SECTION_5_6 Attribute Management
1922
1923 The Attribute Management tool-kit provides services for advanced programmers to extend 
1924 the Application Interactive Services component, AIS. This would prove necessary 
1925 in situations where new Interactive Objects were required.
1926
1927 The <i> Prs3d </i> package provides the following services:
1928
1929   * a presentation object (the context for all modifications to the display, its presentation will be displayed in every view of an active viewer)
1930   * an attribute manager governing how objects such as color, width, and type of line are displayed; these are generic objects, whereas those in <i>StdPrs </i> are specific geometries and topologies.
1931   * generic algorithms providing default settings for objects such as points, curves, surfaces and shapes
1932   * a root object which provides the abstract framework for the DsgPrs definitions at work in display of dimensions, relations and trihedrons.
1933
1934
1935 @subsection OCCT_TOVW_SECTION_5_7 Mesh Visualization Services
1936
1937 <i> MeshVS</i> (Mesh Visualization Service) component extends 3D visualization capabilities 
1938 of Open CASCADE Technology. It provides flexible means of displaying meshes along with associated pre- and post-processor data. 
1939
1940 From a developer's point of view, it is easy to integrate the *MeshVS* component into any mesh-related application with the following guidelines:
1941
1942 * Derive a data source class from the *MeshVS_DataSource* class. 
1943 * Re-implement its virtual methods, so as to give the <i> MeshVS</i> component access to the application data model. This is the most important part of the job, since visualization performance is affected by performance of data retrieval methods of your data source class.
1944 * Create an instance of <i> MeshVS_Mesh</i> class. 
1945 * Create an instance of your data source class and pass it to a <i> MeshVS_Mesh </i> object through the <i> SetDataSource()</i> method.
1946 * Create one or several objects of <i> MeshVS_PrsBuilder</i>-derived classes (standard, included in the <i> MeshVS</i> package, or your custom ones). 
1947 * Each <i> PrsBuilder</i> is responsible for drawing a <i> MeshVS_Mesh</i> presentation in a certain display mode(s) specified as a <i> PrsBuilder</i> constructor's argument. Display mode is treated by <i> MeshVS</i> classes as a combination of bit flags (two least significant bits are used to encode standard display modes: wireframe, shading and shrink). 
1948 * Pass these objects to the <i> MeshVS_Mesh::AddBuilder()</i> method. <i> MeshVS_Mesh</i> takes advantage of improved selection highlighting mechanism: it highlights its selected entities itself, with the help of so called "highlighter" object. You can set one of <i> PrsBuilder</i> objects to act as a highlighter with the help of a corresponding argument of the <i> AddBuilder()</i> method.
1949
1950 Visual attributes of the <i> MeshVS_Mesh </i> object (such as shading color, shrink coefficient and so on)  are controlled through <i> MeshVS_Drawer</i> object. It maintains a map "Attribute ID --> attribute value"  and can be easily extended with any number of custom attributes.
1951
1952 In all other respects, <i> MeshVS_Mesh</i> is very similar to any other class derived from <i> AIS_InteractiveObject</i> and it should be used accordingly (refer to the description of <i> AIS package</i> in the documentation).
1953
1954 @subsection OCCT_TOVW_SECTION_5_8 Images and Drivers
1955
1956 ### Images
1957
1958 The *Image* package provides classes *PixMap*, defining low-level image bitmap in arbitrary formats (RGB, RGBA, Grayscale), and *AlienPixMap*, providing import / export from / to external image files in formats supported by FreeImage library.
1959
1960 ### Drivers
1961
1962 The <i> Xw </i>package contains the common X graphic interface. It uses <i> XWindow </i> bitmap fonts that cannot be modified.
1963
1964 The <i> WNT</i> package contains the common Windows NT graphic interface.
1965
1966 The <i> Cocoa</i> package provides interaction with Cocoa API on Mac OS X.
1967
1968 @subsection OCCT_TOVW_SECTION_5_9 New Interactive Services (NIS)
1969
1970 New Interactive Services package provides the API similar to the traditional AIS but with some important differences/improvements:
1971
1972   * Each type of <i> InteractiveObject</i> should have a corresponding Drawer class that defines the presentation of the Object type using direct OpenGl calls. This is a much faster way to display 3D objects, providing for more than 1 million separate selectable entities in one view.
1973   * The abstract type <i> NIS_InteractiveObject</i> does not support any properties (color, material, other aspects). The relevant properties should be defined in the specializations of the Drawer class, and the API to set/modify should be implemented in the specializations of InteractiveObject class. 
1974   * Interactive selection is managed by <i> InteractiveObject</i> methods instead of special selector classes and data types. This is possible since in NIS the selection is based on 3D representation (by a ray or a box corresponding to the view direction) without intermediate 2D projection.
1975   * Many <i> InteractiveContext</i> instances can be attached to a <i> V3d_View</i>, these instances being independent containers of interactive objects; removal (detaching) of <i> InteractiveContext</i> instance destroys the contained objects.
1976   * All data types and algorithms are designed to provide the best performance for both OpenGl (server side) and application. On the other hand, the API is open to any feature supported by any version of OpenGl. This allows building custom presentations quickly and efficiently.
1977   * Standard <i> NIS_View</i> subclasses <i> V3d_View</i> thus providing all its public API, such as scene definition (view orientation, lights, background, etc.) and the standard view transformations (pan/zoom/rotate,fitAll,...). The traditional AIS-based presentations (e.g., <i> AIS_Shape</i>) are also supported, they can be rendered together with NIS presentations in the same view window.
1978
1979 The DRAW test plugin, <i> TKViewerTest</i>, has been modified 
1980 to manage <i> AIS_InteractiveContext</i> and <i> NIS_InteractiveContext</i> together in one view window.
1981
1982 @subsection OCCT_TOVW_SECTION_5_10 Voxels
1983
1984 A voxel is a sub-volume box with constant scalar/vector value. 
1985 The object in voxel representation is split into many small sub-volumes (voxels) and its properties are distributed through voxels.
1986
1987 Voxels are used for analysis and visualization of 3D-dimensional distribution of data. 
1988 Medicine (mainly, tomography), computational physics (hydrodynamics, aerodynamics, nuclear physics) 
1989 and many other industries use voxels for 3D data visualization and analysis of physical processes.
1990
1991 Open CASCADE Technology provides several basic data containers for voxels 
1992 with fast access to the data and optimal allocation of data in memory. 
1993 Also, a special visualization toolkit allows visualizing voxels 
1994 as colored or black/white points and cubes, displaying only the voxels visible from the user's point of view.
1995
1996 See @ref occt_user_guides__voxels_wp "Voxels User's Guide" for more information.
1997
1998 @subsection OCCT_TOVW_SECTION_5_11 Examples
1999
2000 ### How to change graphic attributes of an interactive object
2001
2002 The set of graphic attributes of an interactive object is defined in AIS_Drawer. 
2003 Each interactive object can have its own visualization attributes.
2004
2005 By default, the interactive object takes the graphic attributes of 
2006 the interactive context in which it is visualized 
2007 (visualization mode, deflection, values for the calculation of presentations, 
2008 number of isoparametric lines, color, type of line, material, etc.)
2009
2010 In the <i> AIS_InteractiveObject</i> abstract class, several standard attributes 
2011 have been privileged. These include: color, thickness of line, material, and transparency. 
2012 Consequently, a certain number virtual functions which allow us to act on these attributes have been proposed. 
2013 Each new class of interactive object can use them as they are or 
2014 can redefine these functions to bring about the changes it should produce in the behavior of the class.
2015
2016 Other attributes can be changed by acting directly on the drawer of the object. 
2017 An interactive object has a specific drawer as soon as you change an attribute on it. 
2018 If you do not modify any graphic attribute on it, the default drawer of the interactive context is referenced and used.
2019
2020 To get the <i> AIS_Drawer</i> of an object, call method <i> AIS_InteractiveObject::Attributes </i>.
2021
2022 To set the <i> AIS_Drawer</i> of an object, call method <i> AIS_InteractiveObject::SetLocalAttributes </i>. 
2023
2024 ### How to dump a scene from the viewer
2025
2026 You can dump the contents of a <i> V3D_View</i> in a file with the same scale or 
2027 with a different scale according to the required paper size (format) 
2028 and the aspect ratio of the view. This is provided by method <i>V3d_View::Dump</i>. For example:
2029
2030 ~~~~
2031 CString filename ("myView3D.bmp");
2032 myView->Dump (filename, Aspect_FOSP_A4);
2033 ~~~~
2034
2035 <i> myView</i> is a <i> V3d_View</i>, where OCCT objects are displayed using, for example, AIS services.
2036
2037 Please, note:
2038
2039   * The file name extension can be any among ".xwd", ".png", or ".bmp" formats both on UNIX or NT.
2040   * Be careful about dump time requirements of the resulting file, especially for the A formats.
2041   * The GIF format generates very small files, BMP and XWD generates much larger files (4 to 6 times the size of a GIF).
2042   * The time to generate these files is very short with the XWD format but 2 to 4 times longer for the other formats.
2043   * After getting an image file of your view, you can use any standard application for editing or sending the image file to a printer (i.e.: Microsoft Photo Editor on Windows or Image Viewer on SUN system)
2044
2045 ### How to add and remove objects from Selections
2046
2047
2048 You can add or remove an object from a selection in one of two ways. You can use:
2049
2050   * <i> AIS_InteractiveContext::AddOrRemoveCurrentObject</i> method at neutral points;
2051   * <i> AddOrRemoveCurrent </i> method if a local context is opened.
2052
2053  
2054 ### How to detect overlapped objects
2055
2056
2057 When objects overlap each other and cause difficulties in selection, 
2058 you can use the mechanism provided with the <i> AIS_InteractiveContext</i> 
2059 to successively highlight all the objects found under the selection. 
2060 This allows you to choose and validate the required object.
2061
2062 ~~~~
2063     If ( myAISContext->HasNextDetected()) {
2064
2065     // if up key is pressed
2066     myAISContext ->HilightNextDetected(myView);
2067
2068     // if down key is pressed
2069     myAISContext ->HilightPreviousDetected(myView);
2070
2071     }
2072 ~~~~
2073
2074
2075
2076 ### Get mouse coordinates in 3D view
2077
2078
2079 To switch from pixel mouse position on the screen to 3D coordinates 
2080 in <i> V3d_View</i>, use <i>V3d_View::Convert</i> method.
2081
2082 ~~~~
2083     Handle(V3d_View) aview
2084     aView->Convert(Xp,Yp,X,Y,Z)
2085 ~~~~
2086
2087 Where <i> Xp</i>, <i> Yp</i> are the mouse coordinates in pixels and X,Y,Z the real coordinates in 3D space.
2088
2089 ### 3D Viewer Objects
2090
2091 The <i> V3d </i>  package contains the set of commands and services of the 3D Viewer. 
2092 It provides a set of high level commands to control views and viewing modes. 
2093 This package is complementary to the <i> Visual3D</i> graphic package.
2094
2095 <i> CSF_WALKTHROUGH</i> variable enables you to manage the perspective of the view 
2096 in the viewer by defining <i> setenv CSF_WALKTHROUGH </i> "Yes".
2097
2098 If you use the syntax <i> unsetenv CSF_WALKTHROUGH </i>, you make sure that the variable 
2099 is deactivated. In this case, the eye is located outside the 3D bounding box of the view. 
2100 This is the default behavior for managing the view perspective.
2101
2102 @section OCCT_TOVW_SECTION_6 Data Exchange
2103
2104 Data Exchange is a key factor in using Open CASCADE Technology (as well as applications based thereon) concurrently with other software such as CAD systems. It provides the openness of OCCT in a multi-software environment, by allowing it to process external data and providing a good level of integration.
2105
2106 This means obtaining results of good quality, and covering the needs of exchanges from OCCT-based applications regardless of external data quality or requirements, in particular in respect of allowed data types and arrangements between them, accepted gaps between geometries.
2107
2108 This matter is addressed by Data Exchange Module, which is organized in a modular way.
2109
2110 @figure{/technical_overview/images/technical_overview_de.png}
2111
2112 Data Exchange interfaces in OCCT allow software based on OCCT to exchange data with various CAD software, thus ensuring a good level of interoperability.
2113
2114 @figure{/technical_overview/images/644_sh_09_400.png,"Image imported from STEP"}
2115
2116 Data Exchange interfaces function either in accordance with the standards (IGES, STEP), 
2117 which can be used by various software packages for CAD, PDM etc., or as direct connectors to proprietary formats.
2118
2119 * **Standardized Data Exchange** interfaces allow to querying and examining a file, results of conversion and its validity. They are designed to support extensions (new standards) in a common modular architecture.
2120         * @ref OCCT_TOVW_SECTION_6_3 "STEP" (AP203 : Mechanical Design, this covers General 3D CAD; AP214: Automotive Design) 
2121         * @ref OCCT_TOVW_SECTION_6_2 "IGES" (up to 5.3) 
2122         * @ref OCCT_TOVW_SECTION_4a_1 "VRML and STL" meshes. 
2123 * @ref OCCT_TOVW_SECTION_6_4 "Extended data exchange" allows extending the scope of exchange by translating  additional data attached to geometric *BREP* data.
2124 * <a href="http://www.opencascade.org/support/products/dataex/">Advanced Data Exchange Components</a> are available in addition to standard Data Exchange interfaces to provide direct mapping and data adaptation (also using @ref OCCT_TOVW_SECTION_6_3_3 "Shape Healing") with CAD software supporting the following formats:
2125         * <a href="http://www.opencascade.org/support/products/dataex/acis/">ACIS SAT</a>
2126         * <a href="http://www.opencascade.org/support/products/dataex/parasolid/">Parasolid</a>
2127         * <a href="http://www.opencascade.org/support/products/dataex/dxf/">DXF</a> 
2128
2129 These components are based on the same architecture as interfaces with STEP and IGES.
2130
2131 @subsection OCCT_TOVW_SECTION_6_1 General Definitions
2132
2133 OCCT general definitions for Data Exchange include several enumerations and classes used by IGES and STEP data exchange interfaces.
2134
2135 To define translation parameters and file headers, you can use:
2136
2137   * <i> Interface_InterfaceModel</i>
2138   * <i> Interface_Static</i>
2139
2140 To manage Message display, use class <i> Mesage_Messenger</i>.
2141
2142 To define the type of analysis of the source file, and to ensure the success 
2143 of the loading operation, you use the following enumerations from the <i> IFSelect</i> package:
2144
2145   * <i> PrintCount</i>
2146   * <i> ReturnStatus</i>
2147
2148 See also: our web site at <a href="http://www.opencascade.org/support/training/">E-learning and Training</a>.
2149
2150
2151 @subsection OCCT_TOVW_SECTION_6_2 IGES
2152
2153 The IGES interface reads IGES files and translates them to Open CASCADE Technology models. 
2154 IGES files produced in accordance with IGES standard versions up to and including version 5.3 can be read.
2155 The interface is able to translate one entity, a group of entities or a whole file.
2156 Before beginning a translation, you can set a range of parameters to manage the translation process.
2157 If you like, you can also check file consistency before translation.
2158
2159 The IGES interface also translates OCCT models to IGES files. 
2160 IGES files produced by this component conform to IGES standard version 5.3.
2161
2162 Other kinds of data such as colors and names can be read or written 
2163 with the help of XDE tools <i> IGESCAFControl_Reader</i> and <i> IGESCAFControl_Writer</i>. 
2164
2165 Please, note:
2166
2167   * an IGES model is an IGES file that has been loaded into memory.
2168   * an IGES entity is an entity in the IGES normal sense.
2169   * a root entity is the highest level entity of any given type, e.g. type 144 for surfaces and type 186 for solids. Roots are not referenced by other entities.
2170
2171 For more details see @ref occt_user_guides__iges "IGES User's Guide".
2172
2173 See also: our web site at <a href="http://www.opencascade.org/support/training/">E-learning and Training</a>.
2174
2175 @subsection OCCT_TOVW_SECTION_6_3 STEP
2176
2177 STEP is more and more widely used to exchange data between various kinds of softwares, involved in CAD, PDM, Analysis, etc... STEP is far more than an "exchange standard" : it provides a technology and a set of methodologies to describe the data to exchange in a modular and upgradeable way. Regarding Open Cascade, this mostly applies to CAD data but it is not a limitation, other kinds of data for specific applications can be addressed too.
2178
2179 @figure{/technical_overview/images/642_sh_08_400.png,"Image imported from STEP"}
2180
2181 Open Cascade allows its users to employ STEP in the following domains:
2182 * Exchange of data for technical applications, following the state-of-the-art definitions and rules;
2183 * Extension of case coverage, according to specific needs or to the evolution of general business uses;
2184 * Expertise on data architecture of an application, to get experience from STEP definitions and make easier the mapping to them, for a better interoperability with outer world.
2185
2186 For more details see @ref occt_user_guides__step "STEP User's Guide".
2187
2188 See also: our web site at <a href="http://www.opencascade.org/support/training/">E-learning and Training</a>.
2189
2190 @subsubsection OCCT_TOVW_SECTION_6_3_1 STEP Exchanges in Open Cascade technology
2191
2192 Beyond the upper level API, which is fitted for an easy end-use, the STEP exchange functions enter in the general frame of Exchanges in Open Cascade, adapted for STEP:
2193
2194 * Specific packages for Data definition and checking;
2195 * Physical Access supported by Drivers (Part 21 file access is embedded);
2196 * Conversion to/from Open Cascade or applicative data supported by drivers (OCC-BREP and XDE ard basically provided);
2197 * Tools for analysis, filtering, etc... including DRAW commands.
2198
2199 These modules share common architecture and capabilities with other exchange modules of Open Cascade, like Shape Healing. Also, built-in Viewer and Converter (as Plugin for Netscape, Internet Explorer ..), are based on the same technology.
2200
2201 In addition, Open Cascade provides tools to process models described using STEP: to reflect EXPRESS descriptions, to read, write and check data, to analyze the whole models ... Their key features are:
2202
2203 * Modularity by sets of data types, which can be hierarchized to reflect the original modularity describing the resources and application protocols;
2204 * Implementation as CDL/C++ classes, providing comprehensive access to their members;
2205 * Early binding is basically used, providing good performance, easy installation and use as well as the capability to support non-compiled descriptions.
2206
2207 This provides a natural way to deal with non-supported protocols when they share common definitions, as for geometry, which can then be exploited. The common frame, as the already supported data types, give a good foundation to go towards new uses of STEP, either on data definition (protocols from ISO or from industrial consortia) or on mapping with applicative data.
2208
2209
2210 @subsubsection OCCT_TOVW_SECTION_6_3_2 STEP Interface
2211
2212 The STEP interface reads STEP files produced in accordance with STEP Application Protocol 214 (Conformance Class 2 both CD and DIS versions of schema) and translates them to Open CASCADE Technology models. STEP Application Protocol 203 is also supported.
2213
2214 The STEP interface also translates OCCT models to STEP files. STEP files that are produced by this interface conform to STEP AP 203 or AP 214 (Conformance Class 2, either CD or DIS version of the schema) depending on the user's option.
2215
2216 Basic interface reads and writes geometrical, topological STEP data and assembly structures. 
2217
2218 The interface is able to translate one entity, a group of entities or a whole file.
2219
2220 Other kinds of data such as colors, validation properties, layers, names and the structure of assemblies can be read or written with the help of XDE tools - <i> STEPCAFControl_Reader</i> and <i> STEPCAFControl_Writer</i>. 
2221
2222 To choose a translation mode when exporting to a STEP format, use <i> STEPControl_STEPModelType</i>.
2223
2224 There is a set of parameters that concern the translation and can be set before the beginning of the translation.
2225
2226 Please, note:
2227 * a STEP model is a STEP file that has been loaded into memory;
2228 * all references to shapes indicate OCCT shapes unless otherwise explicitly stated;
2229 * a root entity is the highest level entity of any given type, i.e. an entity that is not referenced by any other one.
2230
2231 @subsubsection OCCT_TOVW_SECTION_6_3_3 Usage of Shape Healing after import from STEP and IGES
2232
2233 @ref OCCT_TOVW_SECTION_4_10 "Shape Healing" toolkit provides tools to heal various problems which may be encountered in shapes, and to make them valid in Open CASCADE. The Shape Healing is smoothly connected to IGES and STEP translators: the same API as for Open CASCADE IGES and STEP translators is used, only the names of API packages change.
2234
2235 Here are a few examples of typical problems that can be encountered in real IGES and STEP files, with illustrations of how Shape Healing deals with them:
2236
2237 #### Face with missing seam edge
2238
2239 The problem: Face on a periodical surface is limited by wires which make a full trip around the surface. These wires are closed in 3d but not closed in parametric space of the surface. This is not valid in Open CASCADE.
2240 The solution: Advanced Shape Healing fixes this face by inserting seam edge which combines two open wires and thus closes the parametric space. Note that internal wires are processed correctly.
2241
2242 #### Wrong orientation of wires
2243 The problem: Wires on face have incorrect orientation, so that interior and outer parts of the face are mixed.
2244 The solution: Advanced Shape Healing recovers correct orientation of wires.
2245
2246 #### Self-intersecting wire
2247 The problem: Face is invalid because its boundary wire has self-intersection (on two adjacent edges)
2248 The solution: Advanced Shape Healing cuts intersecting edges at intersection points thus making boundary valid.
2249
2250 #### Lacking edge
2251 The problem: There is a gap between two edges in the wire, so that wire is not closed
2252 The solution: Advanced Shape Healing closes a gap by inserting lacking edge.
2253
2254
2255 @subsection OCCT_TOVW_SECTION_6_4 Extended Data Exchange
2256
2257 The Extended Data Exchange (XDE) module allows extending the scope of exchange by translating  additional data attached to geometric *BREP* data, thereby improving the interoperability with external software. Data types such as colors, layers, assembly descriptions and validation properties (i.e. center of gravity, etc.) are supported. These data are stored together with shapes in an XCAF document.
2258
2259 The basis of XDE, called XCAF, is a framework based on OCAF (Open CASCADE Application Framework) intended to work with assemblies and with various kinds of data (attributes) attached to shapes. The following types of data are currently supported :
2260         - assemblies;
2261         - validation properties;
2262         - names;
2263         - colors;
2264         - layers.
2265
2266 It is also possible to add a new types of data taking the existing tools as prototypes.
2267
2268 Finally, the XDE provides reader and writer tools for reading and writing the data supported by XCAF to and from IGES and STEP files. 
2269
2270 @figure{/technical_overview/images/646_xde_11_400.png,"Shape imported using XDE"}
2271
2272 For more details see @ref occt_user_guides__xde "XDE User's Guide".
2273
2274 Here are some examples of IGES and STEP files with colors and other attributes read to XDE.
2275
2276 ### Assembly Structure
2277
2278 @figure{/technical_overview/images/610_xde_01_400.png,"Sample Assembly"}
2279
2280 XDE supports assemblies by separation the shape definition and its location. The shape itself is stored in OCAF as a simple shape object without location, and then assemblies are defined by specifying what shapes they have as components, and with what locations. This gives a flexibility to define and easily work with complex multi-level assemblies.
2281
2282 ### Validation Properties
2283 Validation properties are quite a new feature of STEP standard, currently being actively tested by CAX-IF organization and implemented in commercial STEP translators.
2284
2285 Validation properties are geometric characteristics of shapes (volume, centroid, surface area) which can be put to the STEP file by the sending system. These data should be used by the receiving system in order to validate quality of translation (by comparing these values computed by original system with the same values computed by receiving system on resulting model).
2286
2287 Extended Data Exchange supports both reading and writing validation properties, and provides some tool to check them.
2288
2289 ### Names
2290
2291 @figure{/technical_overview/images/614_xde_04_400.png,"Instance Names"}
2292
2293 XDE supports reading and writing names of shapes to and from both IGES and STEP formats. This functionality can be switched off in case of need (if these data are not needed, thus avoiding unnecessary information in the document).
2294
2295 ### Colors and Layers
2296
2297 @figure{/technical_overview/images/239_xde_12_400.png,"Motor Head"}
2298
2299 XDE can read and write colors and layers assigned to shapes or their subparts (down to level of faces and edges) to and from both IGES and STEP formats. 
2300
2301
2302 @section OCCT_TOVW_SECTION_7 Application Framework
2303
2304 Open CASCADE Application Framework (OCAF) provides a solution for handling of Application Data, based on the Application/Document paradigm. It uses an associativity engine to simplify the development of a CAD application due to the following features:
2305
2306 * @ref OCCT_TOVW_SECTION_7_2 "Data Attributes" that provide management of application data. Attributes may be organized according to the development needs; 
2307 * @ref OCCT_TOVW_SECTION_7_3 "Data storage and Persistence" services; 
2308 * Possibility to modify and recompute documents
2309 * Possibility to manage multiple documents;  
2310 * Ready-to-use modeling data attributes common to CAD/CAM applications;
2311 * Ready-to-use Undo-Redo and Copy-Paste functions.
2312
2313 Since OCAF handles your application structure, your only major development task is the creation of application-specific data and GUIs. It is the organization of application data due to which OCAF differs from any other CAD framework. In OCAF, data structures are not shape-driven, but reference-key driven. 
2314
2315 Thus, the attributes, such as shape data, color and material, are attached to a deeper invariant structure of a model than the shapes themselves. OCAF organizes and embeds these attributes in a document. 
2316
2317 For example, a geometry becomes the value of *Shape* attribute, in the same way as a number is the value of *Integer* attribute and a string is the value of *Name* attribute. OCAF documents are in their turn managed by an OCAF application.
2318
2319 For more details see @ref occt_user_guides__ocaf "OCAF User's Guide" and the OCAF white papers:
2320 * @ref occt_user_guides__ocaf_wp "Application Framework"
2321 * @ref occt_user_guides__ocaf_tree_wp "Distribution of Data through OCAF Tree"
2322 * @ref occt_user_guides__ocaf_functionmechanism_wp "Application Framework Function Mechanism"
2323
2324 See also: our web site at <a href="http://www.opencascade.org/support/training/">E-learning and Training</a>.
2325
2326 @subsection OCCT_TOVW_SECTION_7_1 How to start working with OCAF
2327
2328 To create a useful OCAF-based application, it is necessary to redefine two deferred methods: <i> Formats</i> and <i> ResourcesName</i>
2329
2330 In the <i> Formats </i> method, add the format of the documents, which need to be read by the application and may have been built in other applications.
2331
2332 For example:
2333
2334 ~~~~
2335     void myApplication::Formats(TColStd_SequenceOfExtendedString& Formats)
2336     {
2337       Formats.Append(TCollection_ExtendedString ("OCAF-myApplication"));
2338     }
2339 ~~~~
2340
2341 In the <i> ResourcesName</i> method, you only define the name of the resource file. This
2342 file contains several definitions for the saving and opening mechanisms associated
2343 with each format and calling of the plug-in file.
2344
2345 ~~~~
2346     Standard_CString myApplication::ResourcesName()
2347     {
2348       return Standard_CString ("Resources");
2349     }
2350 ~~~~
2351
2352 To obtain the saving and opening mechanisms, it is necessary to set two environment variables: <i> CSF_PluginDefaults</i>, which defines the path of the plug-in file, and <i> CSF_ResourcesDefault</i>, which defines the resource file:
2353
2354 ~~~~
2355     SetEnvironmentVariable ( "CSF_ResourcesDefaults",myDirectory);
2356     SetEnvironmentVariable ( "CSF_PluginDefaults",myDirectory);
2357 ~~~~
2358
2359 The plugin and the resource files of the application will be located in <i> myDirector</i>.
2360 The name of the plugin file must be <i>Plugin</i>.
2361
2362 ### Resource File
2363
2364 The resource file describes the documents (type and extension) and 
2365 the type of data that the application can manipulate 
2366 by identifying the storage and retrieval drivers appropriate for this data.
2367
2368 Each driver is unique and identified by a GUID generated, for example, with the <i> uuidgen </i> tool in Windows.
2369
2370 Five drivers are required to use all standard attributes provided within OCAF:
2371
2372   * the schema driver (ad696002-5b34-11d1-b5ba-00a0c9064368)
2373   * the document storage driver (ad696000-5b34-11d1-b5ba-00a0c9064368)
2374   * the document retrieval driver (ad696001-5b34-11d1-b5ba-00a0c9064368)
2375   * the attribute storage driver (47b0b826-d931-11d1-b5da-00a0c9064368)
2376   * the attribute retrieval driver (47b0b827-d931-11d1-b5da-00a0c9064368)
2377
2378 These drivers are provided as plug-ins and are located in the <i> PappStdPlugin</i> library.
2379
2380
2381 For example, this is a resource file, which declares a new model document OCAF-MyApplication:
2382
2383 ~~~~
2384 formatlist:OCAF-MyApplication
2385 OCAF-MyApplication.Description: MyApplication Document Version 1.0
2386 OCAF-MyApplication.FileExtension: sta
2387 OCAF-MyApplication.StoragePlugin: ad696000-5b34-11d1-b5ba-00a0c9064368
2388 OCAF-MyApplication.RetrievalPlugin: ad696001-5b34-11d1-b5ba-00a0c9064368
2389 OCAF-MyApplicationSchema: ad696002-5b34-11d1-b5ba-00a0c9064368
2390 OCAF-MyApplication.AttributeStoragePlugin: 47b0b826-d931-11d1-b5da-00a0c9064368
2391 OCAF-MyApplication.AttributeRetrievalPlugin: 47b0b827-d931-11d1-b5da-00a0c9064368
2392 ~~~~
2393  
2394   
2395 ### Plugin File
2396
2397 The plugin file describes the list of required plug-ins to run the application and the
2398 libraries in which plug-ins are located.
2399
2400 You need at least the <i> FWOSPlugin</i> and the plug-in drivers to run an OCAF application.
2401
2402 The syntax of each item is <i> Identification.Location Library_Name, </i> where:
2403 * Identification is GUID.
2404 * Location defines the location of the Identification (where its definition is found).
2405 * Library_Name is the name (and path to) the library, where the plug-in is located.
2406
2407 For example, this is a Plugin file:
2408
2409 ~~~~
2410 a148e300-5740-11d1-a904-080036aaa103.Location: FWOSPlugin
2411 ! base document drivers plugin
2412 ad696000-5b34-11d1-b5ba-00a0c9064368.Location: PAppStdPlugin
2413 ad696001-5b34-11d1-b5ba-00a0c9064368.Location: PAppStdPlugin
2414 ad696002-5b34-11d1-b5ba-00a0c9064368.Location: PAppStdPlugin
2415 47b0b826-d931-11d1-b5da-00a0c9064368.Location: PAppStdPlugin
2416 47b0b827-d931-11d1-b5da-00a0c9064368.Location: PAppStdPlugin
2417 ~~~~
2418  
2419 @subsection OCCT_TOVW_SECTION_7_2 Data Attributes
2420
2421 The following ready-to-use attributes are provided:
2422   * Shape attributes, which contain shapes and their evolution 
2423   * Standard attributes, a collection of common CAD/CAM attributes including: 
2424     * Real 
2425     * Integer 
2426     * Name 
2427     * Constrain 
2428   * Visualization attributes implement the Application Interactive Services in the context of Open CASCADE Application Framework.
2429   * Function attributes which regenerate any data affected by modifications made in a
2430 document 
2431
2432 ### Shape Attributes
2433
2434 A topological attribute can be seen as a hook into the topological structure. To
2435 this hook, data can be attached and references defined.
2436
2437
2438 It is used for keeping and access to topological objects and their evolution. All
2439 topological objects are stored in the one user-protected <i> TNaming_UsedShapes attribute</i>
2440 at the root label of the data framework. This attribute contains map with all topological
2441 shapes, used in this document.
2442
2443 TNaming_NamedShape attribute can be added to any other attribute. This attribute contains
2444 references (hooks) to shapes from the <i> TNaming_UsedShapes</i> attribute and evolution
2445 of these shapes. <i> TNaming_NamedShape </i> attribute contains a set of pairs of hooks: old
2446 shape and new shape (see the figure below). It allows not only get the topological
2447 shapes by the labels, but also trace evolution of the shapes and correctly resolve
2448 dependent shapes by the changed one. 
2449
2450 If a shape is newly created, the old shape for the corresponding named shape is an empty
2451 shape. If a shape is deleted, then the new shape in this named shape is empty.
2452
2453 @figure{/technical_overview/images/technical_overview_shapeattrib.png}
2454
2455
2456 ### Shape attributes in data framework. 
2457
2458 Algorithms can dispose sub-shapes of the result shape at the individual
2459 label depending on necessity: 
2460
2461   * If a sub-shape must have some extra attributes (material of each face or color of each edge). In this case a specific sub-shape is placed to the separate label (usually, sub-label of the result shape label) with all attributes of this sub-shape. 
2462   * If topological naming is needed, a necessary and sufficient (for selected sub-shapes identification) set of sub-shapes is placed to the child labels of the result shape label. As usual, as far as basic solids and closed shells are concerned, all faces of the shape are disposed. Edges and vertices sub-shapes can be identified as intersection of contiguous faces. Modified/generated shapes may be placed to one named shape and identified as this named shape and source named shape that also can be identified with used algorithms. 
2463
2464 <i> TNaming_NamedShape </i> may contain a few pairs of hooks with the same evolution. In this
2465 case topology shape, which belongs to the named shape, is a compound of new shapes.
2466
2467 The data model contains both the topology and the hooks, and functions handle both topological entities and hooks. Consider the case of a box function, which creates a solid with six faces and six hooks. Each hook is attached to a face. If you want, you can also have this function create hooks for edges and vertices as well as for faces. 
2468
2469 Not all functions can define explicit hooks for all topological entities they create, but all topological entities can be turned into hooks when necessary. This is where topological naming is necessary. 
2470
2471 Consider the following example. A box defines six hooks for the six faces, but a protrusion created on a face of the box can only define two hooks, one for the top face, and one for all the lateral faces. As the basic wire defining the protrusion may change in the future the protrusion function cannot designate the lateral faces without ambiguity, their number may change. Figure 6 illustrates this example, faces F1 to F6 of the box each have a hook. Faces F7 to F10, the lateral faces of the protrusion, share a single hook, and face F11, the top face, has one hook.
2472
2473 @figure{/technical_overview/images/technical_overview_occ_0068.png}
2474
2475 This structure raises two problems: 
2476
2477   * the value of the face F6 attribute-hook has changed; 
2478   * no data can be attached to F7. 
2479
2480 When a hook designates multiple faces like F7-F10 (or the hook on F6 if F6 was split)
2481 it is impossible to attach data to an individual face like F7. 
2482
2483 In fact, the protrusion has a trimmed face F6. As a result, the value of this face
2484 has changed and the current value of the hook attached to it needs to be found. Note
2485 that this face could have been split in two faces (for example if the function had
2486 been a slot) and both new faces would have been attached to the same hook.
2487
2488
2489 ### Standard Attributes
2490
2491
2492 Standard attributes are already existing ready-to-use attributes, which allow you
2493 to create and modify labels and attributes for many basic data types.
2494
2495 To find an attribute attached to a specific label, you use the GUID of the type of
2496 attribute you are looking for. For this, find this information using the method 
2497 <i> GetID</i> and the method <i> Find</i> for the label as follows:
2498
2499 ~~~~
2500     Standard_GUID anID = MyAttributeClass::GetID();
2501     Standard_Boolean HasAttribute = aLabel.Find(anID,anAttribute);
2502 ~~~~
2503
2504 ### Function Attributes
2505
2506 A model consists of data and algorithms manipulating with data. OCAF attributes store data. 
2507 A Function attribute stores data corresponding to a Function (see the white paper @ref occt_user_guides__ocaf_functionmechanism_wp "Application Framework Function Mechanism").
2508 This mechanism manipulates with algorithms computing the model in the optimal way following the modifications. 
2509
2510 @subsection OCCT_TOVW_SECTION_7_3 Persistent Data Storage
2511
2512 There are three schemes of persistence, which you can use to store and retrieve OCAF data (documents):
2513
2514   * <i> Standard</i> persistence schema, compatible with previous OCAF applications
2515   * <i> XmlOcaf</i> persistence, allowing the storage of all OCAF data in XML form
2516   * <i> BinOcaf</i> persistence, allowing the storage of all OCAF data in binary format form
2517
2518
2519 All schemes are independent of each other, but they guarantee that the standard OCAF
2520 attributes stored and retrieved by one schema will be storable and retrievable by
2521 the other. Therefore in any OCAF application you can use any persistence schema or
2522 even all three of them. The choice is made by the Format string of stored OCAF documents
2523 or automatically by the file header data -  * on retrieval.
2524
2525 Persistent data storage in OCAF using the <i> Standard</i> package is presented in: 
2526
2527   * Basic Data Storage 
2528   * Persistent Collections 
2529
2530 Persistent storage of shapes is presented in the following chapters:
2531
2532   * Persistent Geometry 
2533   * Persistent Topology 
2534
2535 Finally, information about opening and saving persistent data is presented in Standard
2536 Documents. 
2537
2538 @subsubsection OCCT_TOVW_SECTION_7_3_1 Basic Data Storage
2539
2540 Normally, all data structures provided by Open CASCADE Technology are run-time structures,
2541 in other words, transient data. As transient data, they exist only while an application
2542 is running and are not stored permanently. However, the Data Storage module provides
2543 resources, which enable an application to store data on disk as persistent data.
2544
2545 Data storage services also provide libraries of persistent classes and translation
2546 functions needed to translate data from transient to persistent state and vice-versa.
2547
2548 #### Libraries of persistent classes
2549
2550 Libraries of persistent classes are extensible libraries of elementary classes you
2551 use to define the database schema of your application. They include:
2552 * Unicode (8-bit or 16-bit character type) strings 
2553 * Collections of any kind of persistent data such as arrays.
2554
2555 All persistent classes are derived from the \b Persistent base class, which defines
2556 a unique way of creating and handling persistent objects. You create new persistent
2557 classes by inheriting from this base class.
2558
2559 #### Translation Functions
2560
2561 Translation functions allow you to convert persistent objects to transient ones and
2562 vice-versa. These translation functions are used to build Storage and Retrieval drivers
2563 of an application.
2564
2565 For each class of 2D and 3D geometric types, and for the general shape class in the
2566 topological data structure library, there are corresponding persistent class libraries,
2567 which allow you to translate your data with ease.
2568
2569 #### Creation of Persistent Classes
2570
2571 If you use Unix platforms as well as WOK and CDL, you can create your own persistent
2572 classes. In this case, data storage is achieved by implementing *Storage* and *Retrieval*
2573 drivers.
2574
2575 The <i> Storage </i> package is used to write and read persistent objects. 
2576 These objects are read and written by a retrieval or storage algorithm 
2577 (<i> Storage_Schema </i>object) in a container (disk, memory, network ...). 
2578 Drivers (<i> FSD_File</i> objects) assign a physical container for data to be stored or retrieved.
2579
2580 The standard procedure for an application in reading a container is as follows:
2581
2582 * open the driver in reading mode,
2583 * call the Read function from the schema, setting the driver as a parameter. This function returns an instance of the <i> Storage_Data </i> class which contains the data being read,
2584 * close the driver.
2585
2586 The standard procedure for an application in writing a container is as follows:
2587
2588 * open the driver in writing mode,
2589 * create an instance of the <i> Storage_Data </i> class, then add the persistent data to write with the function <i> AddRoot</i>,
2590 * call the function <i> Write </i> from the schema, setting the driver and the <i> Storage_Data </i> instance as parameters,
2591 * close the driver.
2592
2593 @subsubsection OCCT_TOVW_SECTION_7_3_2 Persistent Collections
2594
2595 Persistent collections are classes which handle dynamically sized collections of data that can be stored in the database. These collections provide three categories of service:
2596
2597   * persistent strings,
2598   * generic arrays of data, 
2599   * commonly used instantiations of arrays.
2600
2601 Persistent strings are concrete classes that handle sequences of characters based
2602 on both ASCII (normal 8-bit) and Unicode (16-bit) character sets.
2603
2604 Arrays are generic classes, that is, they can hold a variety of objects not necessarily inheriting from a unique root class. These arrays can be instantiated with any kind of storable or persistent object, and then inserted into the persistent data model of a user application.
2605
2606 The purpose of these data collections is simply to convert transient data into its persistent equivalent so that it can be stored in the database. To this end, the collections are used to create the persistent data model and assure the link with the database. They do not provide editing or query capabilities because it is more efficient, within the operative data model of the application, to work with transient data structures (from the <i> TCollection</i> package).
2607
2608 For this reason:
2609
2610   * the persistent strings only provide constructors and functions to convert between transient and persistent strings, and
2611   * the persistent data collections are limited to arrays. In other words, <i> PCollection</i> does not include sequences, lists, and so on (unlike <i> TCollection</i>).
2612
2613 Persistent string and array classes are found in the <i> PCollection</i> package. In addition, <i> PColStd</i> package provides standard, and frequently used, instantiations of persistent arrays, for very simple objects.
2614
2615 @subsubsection OCCT_TOVW_SECTION_7_3_3 Persistent Geometry
2616
2617 The Persistent Geometry component describes geometric data structures which can be stored in the database. These packages provide a way to convert data from the transient "world" to the persistent "world".
2618
2619 Persistent Geometry consists of a set of atomic data models parallel to the geometric data structures described in the geometry packages. Geometric data models, independent of each other, can appear within the data model of any application. The system provides the means to convert each atomic transient data model into a persistent one, but it does not provide a way for these data models to share data.
2620
2621 Consequently, you can create a data model using these components, store data in, and retrieve it from a file or a database, using the geometric components provided in the transient and persistent "worlds". In other words, you customize the system by declaring your own objects, and the conversion of the geometric components from persistent to transient and vice versa is automatically managed for you by the system.
2622
2623 However, these simple objects cannot be shared within a more complex data model. To allow data to be shared, you must provide additional tools.
2624
2625 Persistent Geometry is provided by several packages.
2626
2627 The <i> PGeom</i> package describes geometric persistent objects in 3D space, such as points,
2628 vectors, positioning systems, curves and surfaces.
2629
2630 These objects are persistent versions of those provided by the <i> Geom</i> package: for
2631 each type of transient object provided by Geom there is a corresponding type of persistent
2632 object in the <i>PGeom</i> package. In particular the inheritance structure is parallel.
2633
2634 However the <i> PGeom </i>package does not provide any functions to construct, edit or access
2635 the persistent objects. Instead the objects are manipulated as follows:
2636
2637   * Persistent objects are constructed by converting the equivalent transient <i> Geom </i> objects. To do this you use the <i>MgtGeom::Translate</i> function.
2638   * Persistent objects created in this way are used to build persistent data structures that are then stored in a file or database.
2639   * When these objects are retrieved from the file or database, they are converted back into the corresponding transient objects from the Geom package. To do this, you use <i>MgtGeom::Translate</i> function.
2640
2641 In other words, you always edit or query transient data structures within the transient
2642 data model supplied by the session.
2643 Consequently, the documentation for the <i> PGeom </i> package consists simply of a list of available objects.
2644
2645 The <i> PGeom2d </i> package describes persistent geometric objects in 2D space, such as points,
2646 vectors, positioning systems and curves. This package provides the same type of services
2647 as the <i> PGeom</i> package, but for the 2D geometric objects provided by the <i> Geom2d</i> package.
2648 Conversions are provided by the <i>MgtGeom::Translate</i> function.
2649
2650 ~~~~
2651 //Create a coordinate system
2652 Handle(Geom_Axis2Placement) aSys;
2653
2654
2655 //Create a persistent coordinate PTopoDS_HShape.cdlsystem
2656 Handle(PGeom_Axis2placement)
2657         aPSys = MgtGeom::Translate(aSys);
2658
2659 //Restore a transient coordinate system
2660 Handle(PGeom_Axis2Placement) aPSys;
2661
2662 Handle(Geom_Axis2Placement)
2663         aSys = MgtGeom::Translate(aPSys);
2664 ~~~~
2665
2666
2667 @subsubsection OCCT_TOVW_SECTION_7_3_4 Persistent Topology
2668
2669 The Persistent Topology component describes topological data structures which can be stored in the database. These packages provide a way to convert data from the transient "world" to the persistent "world".
2670
2671 Persistent Topology is based on the BRep concrete data model provided by the topology packages. Unlike the components of the Persistent Geometry package, topological components can be fully shared within a single model, as well as between several models.
2672
2673 Each topological component is considered to be a shape: a <i> TopoDS_Shape</i> object. The system's capacity to convert a transient shape into a persistent shape and vice-versa applies to all objects, irrespective of their complexity: vertex, edge, wire, face, shell, solid, and so on.
2674
2675 When a user creates a data model using BRep shapes, he uses the conversion functions that the system provides to store the data in, and retrieve it from the database. The data can also be shared.
2676
2677 Persistent Topology is provided by several packages.
2678
2679 The <i> PTopoDS</i> package describes the persistent data model associated with any BRep shape; it is the persistent version of any shape of type <i> TopoDS_Shape</i>. As is the case for persistent geometric models, this data structure is never edited or queried, it is simply stored in or retrieved from the database. It is created or converted by the <i>MgtBRep::Translate</i> function.
2680
2681 The <i> MgtBRepAbs</i> and <i> PTColStd </i> packages provide tools used by the conversion functions of topological objects.
2682
2683 ~~~~
2684 //Create a shape
2685 TopoDS_Shape aShape;
2686
2687 //Create a persistent shape
2688 PtColStd_DoubleTransientPersistentMap aMap;
2689
2690 Handle(PTopoDS_HShape) aPShape =
2691         aMap.Bind2(MgtBRep::Translate
2692                 aShape,aMap,MgtBRepAbs_WithTriangle));
2693
2694 aPShape.Nullify();
2695
2696 //Restore a transient shape
2697 Handle(PTopoDS_HShape) aPShape;
2698
2699 Handle(TopoDS_HShape) aShape =
2700         aMap.Bind1(MgtBRep::Translate
2701                 (aPShape,aMap,MgtBRepAbs_WithTriangle));
2702
2703 aShape.Nullify();
2704 ~~~~
2705
2706 @subsubsection OCCT_TOVW_SECTION_7_3_5 Standard Documents
2707
2708 Standard documents offer you a ready-to-use document containing a TDF-based data
2709 structure. The documents themselves are contained in a class inheriting from <i> TDocStd_Application</i>
2710 which manages creation, storage and retrieval of documents.
2711
2712 You can implement undo and redo in your document, and refer from the data framework
2713 of one document to that of another one. This is done by means of external link attributes,
2714 which store the path and the entry of external links. To sum up, standard documents
2715 alone provide access to the data framework. They also allow you to:
2716 *Update external links;
2717 *Manage the saving and opening of data;
2718 *Manage undo/redo functionality.
2719
2720 @section OCCT_TOVW_SECTION_7a Draw Test Harness
2721
2722 The Open CASCADE Test Harness, also called Draw, is an easy-to-use testing tool for the geometric modeling libraries. It can be used to test and demonstrate modeling components before building an entire application. It includes:
2723 - A command interpreter based on the TCL language;
2724 - A 2D and a 3D viewer based on X on Unix and Win32 API on Windows;
2725 - A set of predefined commands.
2726
2727 The Test Harness is a single program written in C++, which can be called from interpreted commands. Predefined commands provide general-purpose services such as:
2728 - Getting help;
2729 - Evaluating a script from a file;
2730 - Capturing commands in a file;
2731 - Managing views;
2732 - Displaying objects.
2733
2734 The viewers support operations such as zoom, pan, rotation and full-screen views.
2735
2736 The Test Harness also provides geometric commands to create and manipulate curves and surfaces, and topological commands to create and manipulate shapes. Geometric and topological commands implement geometry and topology resources, and provide examples of their use.
2737
2738 You can add new test harness commands to Draw in order to test or demonstrate a new functionality which you develop.
2739
2740 For more details see @ref occt_user_guides__test_harness "Draw Test Harness Manual".
2741
2742 @section OCCT_TOVW_SECTION_8 FAQ
2743
2744 @subsection OCCT_TOVW_SECTION_8_1 Memory Management
2745
2746 In a work-session, geometry modeling applications create and delete a certain number
2747 of C++ objects. In this context, memory allocation and de-allocation standard functions
2748 are not suited to the system's requirements and for this reason a specialized Memory
2749 Manager is implemented into Open CASCADE Technology. The Memory Manager is based
2750 on the following principles:
2751
2752   * small memory arrays are grouped into clusters and then recycled (clusters are never released to the system),
2753   * large arrays are allocated and de-allocated through the standard functions of the system (the arrays are released to system when they are no longer used).
2754
2755 ### The Reference Counter
2756
2757 To lighten usual programming difficulties linked to the management of object life duration, before deleting an object, the user must ensure the object is no longer referenced and the delete function is secured by a reference counter. 
2758 A smart-pointer called *Handle* automates reference counter management and automatically deletes an object when it is no longer referenced. The application never calls the delete operator explicitly. To benefit from the memory manager in OCCT, transient classes must inherit from <i>TShared</i>. The principle of allocation is as follows:
2759
2760 ~~~~
2761     Handle (TColStd_HSequenceOfInteger) H1 = new TColStd_HSequenceOfInteger;
2762     // H1 has one reference and corresponds to 48 bytes of memory
2763     {
2764       Handle (TColStd_HSequenceOfInteger) H2;
2765       H2 = H1; // H1 has two references
2766       if (argc == 3) 
2767       {
2768         Handle (TColStd_HSequenceOfInteger) H3;
2769         H3 = H1;
2770         // Here, H1 has three references
2771       }
2772          // Here, H1 has two references
2773       }
2774       // Here, H1 has 1 reference
2775     }
2776     // Here, H1 has no reference but the 48 bytes of memory are kept.
2777     Handle (TColStd_HSequenceOfInteger) H1 = new TColStd_HSequenceOfInteger;
2778     // Here, H1 has one reference and corresponds to the preceding 48 bytes of 
2779     // memory. In this case, there is no allocation of memory.
2780 ~~~~
2781
2782 ### Cycles
2783
2784 As cycles are objects which reference one another, memory management is impossible if the data structure contains any cycles, particularly if there are back references.
2785
2786 For example, objects in a graph include primitives and each one of these primitives has to know the graphic object to which it belongs (i.e. a reference to this graphic object). With normal references, the classical handle is used. With back references, a pointer is used. 
2787
2788 ### Memory Consumption
2789
2790
2791 As a general rule, it is advisable to allocate memory through significant blocks. 
2792 In this way, the user can work with blocks of contiguous data and it facilitates memory page manager processing.
2793
2794 @subsection OCCT_TOVW_SECTION_8_2 How to define a handled object without CDL
2795
2796 You can create a class manipulated by handle even if you do not use CDL (Open CASCADE Definition Language). 
2797 To do that you have to use the <i>Define_Standard_Handle</i> macro which is defined in the include file <i> Standard_DefineHandle.hxx</i>.
2798
2799 Here is an example which shows how to define a class <i> SamplePoint </i> manipulated by handle.
2800
2801 Sample_Point.hxx:
2802 ---------------
2803
2804 ~~~~
2805
2806     #ifndef _Sample_Point_HeaderFile
2807     #define _Sample_Point_HeaderFile
2808     #ifndef _Standard_Macro_HeaderFile
2809     #include <Standard_Macro.hxx>
2810     #endif
2811     #include <MMgt_TShared.hxx>
2812     #include <Standard_DefineHandle.hxx>
2813     // Handle definition
2814     //
2815
2816     DEFINE_STANDARD_HANDLE(Sample_Point,MMgt_TShared)
2817     class Sample_Point: public MMgt_TShared {
2818     public:
2819     Sample_Point();
2820     Sample_Point(const Standard_Real, const
2821     Standard_Real);
2822     void SetX(const Standard_Real x) {
2823     myX = x;
2824     }
2825     void SetY(const Standard_Real y) {
2826     myY = y;
2827     }
2828     Standard_Real X() const {
2829     return myX;
2830     }
2831     Standard_Real Y() const {
2832     return myY;
2833     }
2834     // some methods like DynamicType() or
2835     IsKind()
2836     //
2837     DEFINE_STANDARD_RTTI(Sample_Point)
2838     private:
2839     Standard_Real myX;
2840     Standard_Real myY;
2841     };
2842     #endif
2843
2844 ~~~~
2845
2846 Sample_Point.cxx:
2847 ----------------
2848
2849 ~~~~
2850
2851     #include <Sample_Point.hxx>
2852
2853     // Implementation of Handle and type mgt
2854
2855     IMPLEMENT_STANDARD_HANDLE(Sample_Point,MMgt_TShared)
2856     IMPLEMENT_STANDARD_RTTI(Sample_Point,MMgt_TShared)
2857
2858     // For ancestors, we add a IMPLEMENT_STANDARD_SUPERTYPE and
2859     // a IMPLEMENT_STANDARD_SUPERTYPE_ARRAY_ENTRY  macro.
2860     // We must respect the order: from the direct ancestor class to the base class.
2861
2862     IMPLEMENT_STANDARD_TYPE(Sample_Point)
2863     IMPLEMENT_STANDARD_SUPERTYPE(MMgt_TShared)
2864     IMPLEMENT_STANDARD_SUPERTYPE(Standard_Transient)
2865     IMPLEMENT_STANDARD_SUPERTYPE_ARRAY()
2866     IMPLEMENT_STANDARD_SUPERTYPE_ARRAY_ENTRY(MMgt_TShared)
2867     IMPLEMENT_STANDARD_SUPERTYPE_ARRAY_ENTRY(Standard_Transient)
2868     IMPLEMENT_STANDARD_SUPERTYPE_ARRAY_END()
2869     IMPLEMENT_STANDARD_TYPE_END(Sample_Point)
2870
2871    // Constructors implementation
2872
2873     Sample_Point::Sample_Point(const
2874     Standard_Real x, const Standard_Real y)
2875     {
2876     myX = x;
2877     myY = y;
2878     }
2879     Sample_Point::Sample_Point()
2880     {
2881     myX = 0.0;
2882     myY = 0.0;
2883     }
2884 ~~~~
2885
2886 @subsection OCCT_TOVW_SECTION_8_3 When is it necessary to use a handle?
2887
2888 When designing an object, the user is faced with the choice of manipulating that
2889 object by value, or by handle.
2890
2891   * If your object may have a long lifetime within the application and you want to make multiple references to it, it would be preferable to manipulate this object with a handle. The memory for the object will be allocated on the heap. The handle which points to that memory is a light object which can be rapidly passed in argument. This avoids the penalty of copying a large object. 
2892   * If your object will have a limited lifetime, for example, used within a single algorithm, it would be preferable to manipulate this object by value, non-regarding its size, because this object is allocated on the stack and the allocation and de-allocation of memory is extremely rapid, which avoids the implicit calls to 'new' and 'delete' occasioned by allocation on the heap.
2893   * Finally, if an object will be created only once during, but will exist throughout the lifetime of the application, the best choice may be a class manipulated by handle or a value declared as a global variable. 
2894
2895
2896 @subsection OCCT_TOVW_SECTION_8_4  How to cast shape handle to void
2897
2898 You can easily cast a reference to the handle object to <i> void* </i> by defining the following:
2899
2900 ~~~~
2901     void *pointer;
2902     Handle(Some_class) aHandle;
2903     // Here only a pointer will be copied
2904     Pointer = &aHandle;
2905     // Here the Handle object will be copied
2906     aHandle = * (Handle(Some_Class) *)pointer;
2907 ~~~~
2908
2909 @subsection OCCT_TOVW_SECTION_8_5 How to test correct ending of OCCT algorithms
2910
2911 Generally OCCT algorithms implement <i> IsDone</i> method, which  returns <i> true</i> 
2912 if computation has been performed successfully from beginning to end or <i> false</i> if computation has failed.
2913
2914 When <i> IsDone</i> returns <i> true</i>, the computation is successful regarding
2915 to the input data, but it does not necessary mean that you get a result. For example, if
2916 you perform a cut algorithm between two shapes without any common part, the <i> IsDone</i>
2917 method will return <i> true</i>, but the result will be empty.
2918
2919 So, in some cases, it can be necessary to analyse the structure of a result before
2920 using it again in following computations. These tests are not done systematically
2921 into algorithms to get faster computations. The application performs necessary tests
2922 depending on the context.
2923
2924 @subsection OCCT_TOVW_SECTION_8_6 How to cut, copy and paste inside a document
2925
2926 To cut, copy and paste inside a document, you must use the <i> CopyLabel</i> class from the <i> TDF</i> package.
2927 In fact, you must define a Label which contains the temporary value a cut or 
2928 copy operation (say, in <i> Lab_Clipboard</i>). You must also define two other labels:
2929
2930 * One containing the data (e.g. <i> Lab_source</i>)
2931 * One for the destination of the copy (e.g. <i> Lab_ Target</i> )
2932
2933 ~~~~
2934     Copy = copy (Lab_Source => Lab_Clipboard)
2935     Cut = copy + Lab_Source.ForgetAll() // command clear the contents of LabelSource.
2936     Paste = copy (Lab_Clipboard => Lab_target)
2937 ~~~~
2938
2939 So we need a tool to copy all (or a part) of the content of a label and its sub-label,
2940 to another place defined by a label.
2941
2942 ~~~~
2943     TDF_CopyLabel aCopy;
2944     TDF_IDFilter aFilter (Standard_False);
2945
2946     //Don't copy TDataStd_TreeNode attribute
2947
2948      aFilter.Ignore(TDataStd_TreeNode::GetDefaultTreeID());
2949      aCopy.Load(aSource, aTarget); aCopy.UseFilter(aFilter); aCopy.Perform();
2950
2951     // copy the data structure to clipboard 
2952
2953     return aCopy.IsDone(); }
2954 ~~~~
2955
2956 The filter is used to forbid copying a specified type of attribute. 
2957 You can also have a look at *TDF_Closure**, 
2958 which can be useful to determine the dependencies of the part you want to cut from the document.
2959
2960 @subsection OCCT_TOVW_SECTION_8_7 Platform-related problems 
2961
2962 ### Dynamic library loading 
2963
2964 Open CASCADE Technology uses a dynamic library loading mode. Sometimes, the error message such as the following appears:
2965
2966 ~~~~
2967  "cannot map libname.so .. under any of the filenames .."
2968 ~~~~
2969
2970 When this happens, check your *PATH* under Windows, *LD_LIBRARY_PATH* under UNIX, or *DYLD_LIBRARY_PATH* under Mac OS X. 
2971 It should contain the path where the required dynamic library is located.
2972
2973 ### Running Draw under Windows
2974
2975
2976 When running <i> DRAWEXE</i> and using axo in the Command window you may see the "Invalid command name "axo" " message :
2977
2978 Make sure that the OCCT directory name does not contain any blank spaces.
2979 It causes some problems when reading the OCCT description TCL Commands files.
2980 If you have set <i> DRAWHOME</i> and <i> DRAWDEFAULT</i>, replace \\ by / in the variable. 
2981
2982 ### Error on application start on Windows
2983
2984 If Windows shows an error message with the text *Application failed to initialize properly* 
2985 upon launching the application, check access rights for all libraries used in the application, in particular, third-party libraries. 
2986
2987 Make sure that you have all rights  necessary to access these libraries. 
2988 It is recommended to use option *Inherit access rights from parent*.
2989
2990 ### Problems with 3D viewer
2991
2992 If the 3D viewer fails to display the scene properly, or works very slowly, or exhibits
2993 another problem, make sure to have the latest version of the graphics card driver
2994 installed. If this is not possible or does not help, try to decrease 
2995 hardware acceleration level (usually found in Troubleshooting section of the graphics card properties).