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