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