OpenCascade/occt
1
0
Fork 0
mirror of https://git.dev.opencascade.org/repos/occt.git synced 2025-04-03 17:56:21 +03:00
Code Packages Releases Activity

0023640: Documentation for local sewing with BRepBuilderAPI_Sewing is missing

Browse Source 
Fix for bug 23640.
Merging the rest of Technical Overview content into User's Guides.

-Correct UG sections concerning Sewing.
-Correct comments in the code referring to old location of sewing algorithm.
This commit is contained in:
ysn 2015-01-29 13:21:33 +03:00 committed by bugmaster
parent 07f1a2e68c
commit e2b55410ff
20 changed files with 1911 additions and 787 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

16
dox/user_guides/boolean_operations/boolean_operations.md
View File

@ -11,6 +11,22 @@ General Fuse Algorithm is also a basis of the Partition Algorithm (PA) implement
General Fuse Algorithm has a history-based architecture designed to allow using OCAF naming functionality.
The architecture of General Fuse Algorithm is expandable, that allows creating new algorithms basing on it.
@section occt_algorithms_1_1 Difference between Old and New Boolean Operations
In OCCT there exist two libraries providing Boolean Operations:
* 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.
* New Boolean Operations (NBOA) provided by <i>BRepAlgoAPI</i> package designed and developed in 2001 and completely revised in 2013.
New Boolean Operations provide the following major benefits:
* 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.
* 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.
* 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.
* NBOA provide a general algorithm. It correctly processes without using the workarounds even the cases that cannot be properly processed by BOA.
* 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.
* 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.
@section occt_algorithms_2 Overview

420
dox/user_guides/foundation_classes/foundation_classes.md
View File

@ -5,21 +5,21 @@ Foundation Classes {#occt_user_guides__foundation_classes}
@section occt_fcug_1 Introduction
@subsection occt_fcug_1_1 Foundation Classes Overview
This manual explains how to use Open CASCADE Technology (**OCCT**) Foundation Classes. It provides basic documentation on foundation classes. For advanced information on foundation classes and their applications, see the offerings on our web site at <a href="http://www.opencascade.org/support/training/">www.opencascade.org/support/training/</a>.
Foundation Classes provide a variety of general-purpose services such as automated dynamic memory management (manipulation of objects by handle), collections, exception handling, genericity by down-casting and plug-in creation.
This manual explains how to use Open CASCADE Technology (**OCCT**) Foundation Classes. It provides basic documentation on foundation classes. For advanced information on foundation classes and their applications, see our offerings on our web site at <a href="http://www.opencascade.org/support/training/">www.opencascade.org/support/training/</a>
Foundation Classes provide a variety of general-purpose services such as automated dynamic memory management (manipulation of objects by handle), collections, exception handling, genericity by downcasting and plug-in creation.
Foundation Classes include the following:
### Root Classes
Root classes are the basic data types and classes on which all the other classes are built. They provide:
* fundamental types such as Boolean, Character, Integer or Real,
* safe handling of dynamically created objects, ensuring automatic deletion of unreferenced objects (see the Standard_Transient class),
* safe handling of dynamically created objects, ensuring automatic deletion of unreferenced objects (see *Standard_Transient* class),
* configurable optimized memory manager increasing the performance of applications that intensively use dynamically created objects,
* extended run-time type information (RTTI) mechanism facilitating the creation of complex programs,
* management of exceptions,
* encapsulation of C++ streams.
Root classes are mainly implemented in the *Standard* and *MMgt* packages.
Root classes are mainly implemented in *Standard* and *MMgt* packages.
### Strings
Strings are classes that handle dynamically sized sequences of characters based on both ASCII (normal 8-bit character type) and Unicode (16-bit character type).
@ -39,7 +39,6 @@ The *TColStd* package provides frequently used instantiations of generic classe
### Vectors and Matrices
These classes provide commonly used mathematical algorithms and basic calculations (addition, multiplication, transposition, inversion, etc.) involving vectors and matrices.
### Primitive Geometric Types
@ -82,25 +81,27 @@ These are various classes supporting date and time information and fundamental
### Application services
Foundation Classes also include implementation of several low-level services that facilitate the creation of customizable and user-friendly applications with Open CASCADE Technology. These include:
* Unit conversion tools, providing a uniform mechanism for dealing with quantities and associated physical units: check unit compatibility, perform conversions of values between different units and so on (see package *UnitsAPI*).
* Basic interpreter of expressions that facilitates the creation of customized scripting tools, generic definition of expressions and so on (see package *ExprIntrp*)
* Tools for dealing with configuration resource files (see package *Resource*) and customizable message files (see package *Message*), making it easy to provide a multi-language support in applications
* Unit conversion tools, providing a uniform mechanism for dealing with quantities and associated physical units: check unit compatibility, perform conversions of values between different units and so on (see package *UnitsAPI*);
* Basic interpreter of expressions that facilitates the creation of customized scripting tools, generic definition of expressions and so on (see package *ExprIntrp*);
* Tools for dealing with configuration resource files (see package *Resource*) and customizable message files (see package *Message*), making it easy to provide a multi-language support in applications;
* Progress indication and user break interfaces, giving a possibility even for low-level algorithms to communicate with the user in a universal and convenient way.
@section occt_fcug_2 Basics
This chapter deals with basic services such as library organization, persistence, data types, memory management, programming with handles, exception handling, genericity by downcasting and plug-in creation.
@subsection occt_fcug_1_2 Fundamental Concepts
An object-oriented language structures a system around data types rather than around the actions carried out on this data. In this context, an **object** is an **instance** of a data type and its definition determines how it can be used. Each data type is implemented by one or more classes, which make up the basic elements of the system.
@subsection occt_fcug_2_a Library organization
In Open CASCADE Technology the classes are usually defined using CDL (CASCADE Definition Language) that provides a certain level of abstraction from pure C++ constructs and ensures a definite level of similarity in the implementation of classes. See *CDL User’s Guide* for more details.
This chapter introduces some basic concepts, which are used not only in Foundation Classes, but throughout the whole OCCT library.
This chapter introduces some basic concepts most of which are directly supported by CDL and used not only in Foundation Classes, but throughout the whole OCCT library.
@subsubsection occt_fcug_2_a_1 Modules and toolkits
@subsubsection occt_fcug_1_2_1 Modules and toolkits
The whole OCCT library is organized in a set of modules. The first module, providing most basic services and used by all other modules, is called Foundation Classes and described by this manual.
Every module consists primarily of one or several toolkits (though it can also contain executables, resource units etc.). Physically a toolkit is represented by a shared library (e.g. .so or .dll). The toolkit is built from one or several packages.
@subsubsection occt_fcug_1_2_2 Packages
@subsubsection occt_fcug_2_a_2 Packages
A **package** groups together a number of classes which have semantic links. For example, a geometry package would contain Point, Line, and Circle classes. A package can also contain enumerations, exceptions and package methods (functions). In practice, a class name is prefixed with the name of its package e.g.
*Geom_Circle*.
Data types described in a package may include one or more of the following data types:
@ -118,19 +119,18 @@ Inside a package, two data types cannot bear the same name.
* **Instance method** Operates on the instance which owns it.
* **Class method** Does not work on individual instances, only on the class itself.
@subsubsection occt_fcug_1_2_3 Classes
@subsubsection occt_fcug_2_a_3 Classes
The fundamental software component in object-oriented software development is the class. A class is the implementation of a **data type**. It defines its **behavior** (the services offered by its functions) and its **representation** (the data structure of the class – the fields, which store its data).
#### Categories of Classes
Classes fall into three categories:
* Ordinary classes.
* Deferred classes. A **deferred class** cannot be instantiated. The purpose of having such classes is to have a given behavior shared by a hierarchy of classes and dependent on the implementation of the descendants. This is a way of guaranteeing a certain base of inherited behavior common to all the classes based on a particular deferred class. The C++ equivalent of a deferred CDL class is an abstract class.
* Generic classes. A **generic class** offers a set of functional behaviors to manipulate other data types. Instantiation of a generic class requires that a data type is given for its argument(s). The generic classes in CDL perform the same mission as template classes in C++.
* Ordinary classes.
* Deferred classes. A **deferred class** cannot be instantiated. The purpose of having such classes is to have a given behavior shared by a hierarchy of classes and dependent on the implementation of the descendants. This is a way of guaranteeing a certain base of inherited behavior common to all the classes based on a particular deferred class. The C++ equivalent of a deferred CDL class is an abstract class.
* Generic classes. A **generic class** offers a set of functional behaviors to manipulate other data types. Instantiation of a generic class requires that a data type is given for its argument(s). The generic classes in CDL perform the same mission as template classes in C++.
@subsubsection occt_fcug_1_2_4 Genericity
@subsubsection occt_fcug_2_a_4 Generic Classes
Generic classes are implemented in two steps. First you declare the generic class to establish the model, then you instantiate this class by giving information about the generic types.
#### Declaring a Generic Class
#### Declaring a Generic Class
The generic classes in Open CASCADE Technology are similar by their intent to C++ templates with explicit instantiation.
A generic class is declared in CDL as operating on data items of non-fixed types which are declared as arguments of the generic class. It is possible to put a restriction on these data types to be of subtype of some definite class. Definition of the generic class does not create new class type in C++ terms; it only defines a pattern for generation (instantiation) of the real classes.
@ -157,15 +157,27 @@ class MapOfReal instantiates Map from TCollection (Real,MapRealHasher);
This declaration in *TColStd* defines not only class *TColStd_MapOfReal*, but also class *TColStd_MapIteratorOfMapOfReal*, which is instantiated from nested class *MapIterator* of the generic class *TCollection_Map*. Note that instantiation of the nested class is separate class, it is not nested class to the instantiation of the main class.
**Nested classes**, even though they are described as non-generic classes, are generic by construction being inside the class they are a member of.
@subsubsection occt_fcug_1_2_5 Inheritance
@subsubsection occt_fcug_2_a_5 Inheritance
The purpose of inheritance is to reduce the development workload. The inheritance mechanism allows a new class to be declared already containing the characteristics of an existing class. This new class can then be rapidly specialized for the task in hand. This avoids the necessity of developing each component “from scratch”.
For example, having already developed a class *BankAccount* you could quickly specialize new classes: *SavingsAccount, LongTermDepositAccount, MoneyMarketAccount, RevolvingCreditAccount*, etc....
The corollary of this is that when two or more classes inherit from a parent (or ancestor) class, all these classes guarantee as a minimum the behavior of their parent (or ancestor). For example, if the parent class BankAccount contains the method Print which tells it to print itself out, then all its descendent classes guarantee to offer the same service.
The corollary of this is that when two or more classes inherit from a parent (or ancestor) class, all these classes guarantee as a minimum the behavior of their parent (or ancestor). For example, if the parent class BankAccount contains the method Print which tells it to print itself out, then all its descendant classes guarantee to offer the same service.
One way of ensuring the use of inheritance is to declare classes at the top of a hierarchy as being **deferred**. In such classes, the methods are not implemented. This forces the user to create a new class which redefines the methods. This is a way of guaranteeing a certain minimum of behavior among descendent classes.
One way of ensuring the use of inheritance is to declare classes at the top of a hierarchy as being **deferred**. In such classes, the methods are not implemented. This forces the user to create a new class which redefines the methods. This is a way of guaranteeing a certain minimum of behavior among descendant classes.
@subsection occt_fcug_2_b Persistence and Data Schema
The data schema is the structure used by an application to store its data. Data schemas consist of persistent classes.
An object is called **persistent** if it can be permanently stored. Thus, the object can be reused at a later date by the application, which created it, or by another application.
In order for an object to be persistent for CDL, its type must be declared as inheriting from the class *Standard_Persistent* or have a parent class inheriting from the *Standard_Persistent* class. Note that classes inheriting from *Standard_Persistent* are handled by a reference.
Objects instantiated from classes which inherit from the Standard_Storable class cannot themselves be stored individually, but they can be stored as fields of an object which inherits from *Standard_Persistent*. Note that objects inheriting from *Standard_Storable* are handled by a value.
@subsection occt_fcug_2_1 Data Types
An object-oriented language structures a system around data types rather than around the actions carried out on this data. In this context, an **object** is an **instance** of a data type and its definition determines how it can be used. Each data type is implemented by one or more classes, which make up the basic elements of the system.
@subsubsection occt_fcug_1_2_6 Categories of Data Types
The data types in Open CASCADE Technology fall into two categories:
* Data types manipulated by handle (or reference)
* Data types manipulated by value
@ -186,24 +198,10 @@ Handle(myClass) m = new myClass;
In Open CASCADE Technology, the Handles are specific classes that are used to safely manipulate objects allocated in the dynamic memory by reference, providing reference counting mechanism and automatic destruction of the object when it is not referenced.
@subsubsection occt_fcug_1_2_7 Exceptions
The behavior of any object is implemented by the methods, which were defined in its class declaration. The definition of these methods includes not only their signature (their programming interface) but also their domain of validity.
This domain is expressed by **exceptions**. Exceptions are raised under various error conditions. This mechanism is a safeguard of software quality.
@subsubsection occt_fcug_1_2_8 Persistence and Data Schema
The data schema is the structure used by an application to store its data. Data schemas consist of persistent classes.
An object is called **persistent** if it can be permanently stored. Thus, the object can be reused at a later date by the application, which created it, or by another application.
In order for an object to be persistent for CDL, its type must be declared as inheriting from the class *Standard_Persistent* or have a parent class inheriting from the *Standard_Persistent* class. Note that classes inheriting from *Standard_Persistent* are handled by a reference.
Objects instantiated from classes which inherit from the Standard_Storable class cannot themselves be stored individually, but they can be stored as fields of an object which inherits from *Standard_Persistent*. Note that objects inheriting from *Standard_Storable* are handled by a value.
@section occt_fcug_2 Basics
This chapter deals with basic services such as memory management, programming with handles, primitive types, exception handling, genericity by downcasting and plug-in creation.
@subsection occt_fcug_2_1 Data Types
@subsubsection occt_fcug_2_1_1 Primitive Types
The primitive types are predefined in the language and they are **manipulated by value**.
Some of these primitives inherit from the **Storable** class. This means they can be used in the implementation of persistent objects, either contained in entities declared within the methods of the object, or they form part of the internal representation of the object.
@ -237,7 +235,6 @@ The table below presents the equivalence existing between C++ fundamental types
\* The types with asterisk are pointers.
**Reminder of the classes listed above:**
* **Standard_Integer** : fundamental type representing 32-bit integers yielding negative, positive or null values. *Integer* is implemented as a *typedef* of the C++ *int* fundamental type. As such, the algebraic operations +, -, *, / as well as the ordering and equivalence relations <, <=, ==, !=, >=, > are defined on it.
@ -270,7 +267,7 @@ There are two categories of types which are manipulated by handle:
@image html /user_guides/foundation_classes/images/foundation_classes_image006.png "Manipulation of a data type by reference"
@image latex /user_guides/foundation_classes/images/foundation_classes_image006.png "Manipulation of a data type by reference"
@subsubsection occt_fcug_2_1_4 Summary of properties
@subsubsection occt_fcug_2_1_4 When is it necessary to use a handle?
The following table summarizes how various data types are handled and stored.
@ -279,9 +276,26 @@ The following table summarizes how various data types are handled and stored.
| storable | Persistent | Primitive, Storable (if nested in a persistent class)|
|temporary | Transient | Other |
When you design an object, it can be difficult to choose how to manipulate that
object: by value or by handle. The following ideas can help you to make up your mind:
* 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.
* 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.
* 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.
@subsection occt_fcug_2_2 Programming with Handles
@subsubsection occt_fcug_2_2_1 Handle Definition
A handle may be compared with a C++ pointer. Several handles can reference the same object. Also, a single handle may reference several objects, but only one at a time. To have access to the object it refers to, the handle must be de-referenced just as with a C++ pointer.
Transient and Persistent classes may be manipulated either with handles or with values. Handles which reference non-persistent objects are called non-storable handles; therefore, a persistent object cannot contain a non-storable handle.
@ -315,10 +329,8 @@ To initialize a handle, either a new object should be created or the value of a
@subsubsection occt_fcug_2_2_2 Type Management
#### General
Open CASCADE Technology provides a means to describe the hierarchy of data types in a generic way, with a possibility to check the exact type of the given object at run-time (similarly to C++ RTTI). For every class type derived from *Standard_Transient*, CDL extractor creates a code instantiating single instance of the class *Standard_Type* (type descriptor) that holds information on that type: its name and list of ancestor types.
That instance (actually, a handle on it) is returned by the virtual method *DynamicType()* of the class derived from *Standard_Transient*. The other virtual method *IsKind()* provides a means to check whether a given object has specified type or inherits it.
In order to refer to the type descriptor object for a given class type, use macros *STANDARD_TYPE()* with argument being a name of the class.
@ -341,7 +353,6 @@ The compiler sees p1 as a handle to *Point* though the actual object referenced
#### Explicit Type Conversion
According to the rule of type conformity, it is always possible to go up the class hierarchy through successive assignments of handles. On the other hand, assignment does not authorize you to go down the hierarchy. Consequently, an explicit type conversion of handles is required.
A handle can be converted explicitly into one of its sub-types if the actual type of the referenced object is a descendant of the object used to cast the handle. If this is not the case, the handle is nullified (explicit type conversion is sometimes called a “safe cast”). Consider the example below.
@ -396,6 +407,7 @@ else {
~~~~~
@subsubsection occt_fcug_2_2_3 Using Handles to Create Objects
To create an object which is manipulated by handle, declare the handle and initialize it with the standard C++ **new** operator, immediately followed by a call to the constructor. The constructor can be any of those specified in the source of the class from which the object is instanced.
~~~~~
@ -444,7 +456,8 @@ n = Geom_BezierCurve::MaxDegree();
~~~~~
@subsubsection occt_fcug_2_2_5 Handle deallocation
Before you delete an object, you must ensure it is no longer referenced. To reduce the programming load related to this management of object life, the delete function in Open CASCADE Technology is secured by a **reference counter** of classes manipulated by handle. A handle automatically deletes an object when it is no longer referenced. Normally you never call the delete operator explicitly on instances of subclasses of *Standard_Transient*.
Before you delete an object, you must ensure it is no longer referenced. To reduce the programming load related to this management of object life, the delete function in Open CASCADE Technology is secured by a **reference counter** of classes manipulated by handle. A handle automatically deletes an object when it is no longer referenced. Normally you never call the delete operator explicitly on instances of subclasses of *Standard_Transient*.
When a new handle to the same object is created, the reference counter is incremented. When the handle is destroyed, nullified, or reassigned to another object, that counter is decremented. The object is automatically deleted by the handle when reference counter becomes 0.
@ -471,25 +484,38 @@ Handle (TColStd_HSequenceOfInteger) H1 = new TColStd_HSequenceOfInteger;
// Here, H1 has no reference and the referred TColStd_HSequenceOfInteger object is deleted.
~~~~~
#### Cycles
You can easily cast a reference to the handle object to <i> void* </i> by defining the following:
Cycles appear if two or more objects reference each other by handles (stored as fields). In this condition automatic destruction will not work.
~~~~
void *pointer;
Handle(Some_class) aHandle;
// Here only a pointer will be copied
Pointer = &aHandle;
// Here the Handle object will be copied
aHandle = * (Handle(Some_Class) *)pointer;
~~~~
@subsubsection occt_fcug_2_2_6 Cycles
Cycles appear if two or more objects reference each other by handles (stored as fields). In this condition automatic destruction will not work.
Consider for example a graph, whose objects (primitives) have to know the graph object to which they belong, i.e. a primitive must have a reference to complete graph object. If both primitives and the graph are manipulated by handle and they refer to each other by keeping a handle as a field, the cycle appears.
The graph object will not be deleted when the last handle to it is destructed in the application, since there are handles to it stored inside its own data structure (primitives).
There are two approaches how to avoid such situation:
* Use C++ pointer for one kind of references, e.g. from a primitive to the graph
* Nullify one set of handles (e.g. handles to a graph in primitives) when a graph object needs to be destroyed
@subsubsection occt_fcug_2_2_6 Creating Transient Classes without CDL
@subsubsection occt_fcug_2_2_7 Creating Transient Classes without CDL
Though generation of Handle class and related C++ code is normally performed by CDL extractor, it is also possible to define a class managed by handle without CDL. To facilitate that, several macros are provided in the file Standard_DefineHandle.hxx:
* **DEFINE_STANDARD_HANDLE(class_name,ancestor_name)** - declares Handle class for a class *class_name* that inherits class *ancestor_name* (for instance, *Standard_Transient*). This macro should be put in a header file; the declaration of the handle to a base class must be available (usually put before or after the declaration of the class *class_name*, or into a separate header file).
* **IMPLEMENT_STANDARD_HANDLE(class_name,ancestor_name)** - implements method *DownCast()* of the *Handle* class. Should be located in a C++ file (normally the file where methods of the class *class_name* are implemented).
* **DEFINE_STANDARD_RTTI(class_name)** - declares methods required for RTTI in the class *class_name* declaration; should be in public: section.
* **IMPLEMENT_STANDARD_RTTIEXT(class_name,ancestor_name)** - implements above methods. Usually put into the C++ file implementing class class_name.
* **IMPLEMENT_STANDARD_RTTIEXT(class_name,ancestor_name)** - implements above methods. Usually put into the C++ file implementing class *class_name*.
Note that it is important to ensure correctness of macro arguments, especially the ancestor name, otherwise the definition may be inconsistent (no compiler warnings will be issued in case of mistake).
In *Appli_ExtSurface.hxx* file:
@ -511,21 +537,118 @@ IMPLEMENT_STANDARD_HANDLE(Appli_ExtSurface,Geom_Surface)
IMPLEMENT_STANDARD_RTTIEXT(Appli_ExtSurface,Geom_Surface)
~~~~~
#### Example
@subsection occt_fcug_2_3 Memory Management in Open CASCADE Technology
In the course of a work session, geometric modeling applications create and delete a considerable number of C++ objects allocated in the dynamic memory (heap). In this context, performance of standard functions for allocating and deallocating memory may be not sufficient. For this reason, Open CASCADE Technology employs a specialized memory manager implemented in the Standard package.
The following example shows how to define a class <i> SamplePoint </i> manipulated by handle.
@subsubsection occt_fcug_2_3_1. Usage
To use the Open CASCADE Technology memory manager to allocate memory in a C code, just use method *Standard::Allocate()* instead of *malloc()* and method *Standard::Free()* instead of *free()*. In addition, method *Standard::Reallocate()* is provided to replace C function *realloc()*.
First you need to define *Sample_Point.hxx* :
~~~~
#ifndef _Sample_Point_HeaderFile
#define _Sample_Point_HeaderFile
#ifndef _Standard_Macro_HeaderFile
#include <Standard_Macro.hxx>
#endif
#include <MMgt_TShared.hxx>
#include <Standard_DefineHandle.hxx>
// Handle definition
//
DEFINE_STANDARD_HANDLE(Sample_Point,MMgt_TShared)
class Sample_Point: public MMgt_TShared {
public:
Sample_Point();
Sample_Point(const Standard_Real, const
Standard_Real);
void SetX(const Standard_Real x) {
myX = x;
}
void SetY(const Standard_Real y) {
myY = y;
}
Standard_Real X() const {
return myX;
}
Standard_Real Y() const {
return myY;
}
// some methods like DynamicType() or
IsKind()
//
DEFINE_STANDARD_RTTI(Sample_Point)
private:
Standard_Real myX;
Standard_Real myY;
};
#endif
~~~~
Then you need to define *Sample_Point.cxx* :
~~~~
#include <Sample_Point.hxx>
// Implementation of Handle and type mgt
IMPLEMENT_STANDARD_HANDLE(Sample_Point,MMgt_TShared)
IMPLEMENT_STANDARD_RTTI(Sample_Point,MMgt_TShared)
// For ancestors, we add a IMPLEMENT_STANDARD_SUPERTYPE and
// a IMPLEMENT_STANDARD_SUPERTYPE_ARRAY_ENTRY macro.
// We must respect the order: from the direct ancestor class to the base class.
IMPLEMENT_STANDARD_TYPE(Sample_Point)
IMPLEMENT_STANDARD_SUPERTYPE(MMgt_TShared)
IMPLEMENT_STANDARD_SUPERTYPE(Standard_Transient)
IMPLEMENT_STANDARD_SUPERTYPE_ARRAY()
IMPLEMENT_STANDARD_SUPERTYPE_ARRAY_ENTRY(MMgt_TShared)
IMPLEMENT_STANDARD_SUPERTYPE_ARRAY_ENTRY(Standard_Transient)
IMPLEMENT_STANDARD_SUPERTYPE_ARRAY_END()
IMPLEMENT_STANDARD_TYPE_END(Sample_Point)
// Constructors implementation
Sample_Point::Sample_Point(const
Standard_Real x, const Standard_Real y)
{
myX = x;
myY = y;
}
Sample_Point::Sample_Point()
{
myX = 0.0;
myY = 0.0;
}
~~~~
@subsection occt_fcug_2_3 Memory Management
In a work session, geometric modeling applications create and delete a considerable number of C++ objects allocated in the dynamic memory (heap). In this context, performance of standard functions for allocating and deallocating memory may be not sufficient. For this reason, Open CASCADE Technology employs a specialized memory manager implemented in the *Standard* package.
The Memory Manager is based on the following principles:
* small memory arrays are grouped into clusters and then recycled (clusters are never released to the system),
* 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).
As a general rule, it is advisable to allocate memory through significant blocks. In this way, the user can work with blocks of contiguous data and it facilitates memory page manager processing.
@subsubsection occt_fcug_2_3_1 Usage of Memory Manager
To allocate memory in a C code with Open CASCADE Technology memory manager, simply use method *Standard::Allocate()* instead of *malloc()* and method *Standard::Free()* instead of *free()*. In addition, method *Standard::Reallocate()* is provided to replace C function *realloc()*.
In C++, operators *new()* and *delete()* for a class may be defined so as to allocate memory using *Standard::Allocate()* and free it using *Standard::Free()*. In that case all objects of that class and all inherited classes will be allocated using the OCCT memory manager.
CDL extractor defines *new()* and *delete()* in this way for all classes declared with CDL. Thus all OCCT classes (apart from a few exceptions) are allocated using the OCCT memory manager.
Since operators *new()* and *delete()* are inherited, this is also true for any class derived from an OCCT class, for instance, for all classes derived from *Standard_Transient*.
**Note** that it is possible (though not recommended unless really unavoidable) to redefine *new()* and *delete()* functions for some class inheriting Standard_Transient. If that is done, the method *Delete()* should be also redefined to apply operator *delete* to *this* pointer. This will ensure that appropriate *delete()* function will be called, even if the object is manipulated by a handle to a base class.
**Note** that it is possible (though not recommended unless really unavoidable) to redefine *new()* and *delete()* functions for a class inheriting *Standard_Transient*. If that is done, the method *Delete()* should be also redefined to apply operator *delete* to this pointer. This will ensure that appropriate *delete()* function will be called, even if the object is manipulated by a handle to a base class.
@subsubsection occt_fcug_2_3_2 How to configure the Memory Manager
@subsubsection occt_fcug_2_3_2 Configuring the memory manager
The OCCT memory manager may be configured to apply different optimization techniques to different memory blocks (depending on their size), or even to avoid any optimization and use C functions *malloc()* and *free()* directly.
The configuration is defined by numeric values of the following environment variables:
* *MMGT_OPT*: if set to 0 (default) every memory block is allocated in C memory heap directly (via *malloc()* and *free()* functions). In this case, all other options except for *MMGT_CLEAR* are ignored; if set to 1 the memory manager performs optimizations as described below; if set to 2, Intel ® TBB optimized memory manager is used.
@ -535,7 +658,8 @@ The configuration is defined by numeric values of the following environment var
* *MMGT_THRESHOLD*: defines the maximal size of blocks that are recycled internally instead of being returned to the heap. Default is 40000.
* *MMGT_MMAP*: when set to 1 (default), large memory blocks are allocated using memory mapping functions of the operating system; if set to 0, they will be allocated in the C heap by *malloc()*.
@subsubsection occt_fcug_2_3_3 Implementation details
@subsubsection occt_fcug_2_3_3 Optimization Techniques
When *MMGT_OPT* is set to 1, the following optimization techniques are used:
* Small blocks with a size less than *MMGT_CELLSIZE*, are not allocated separately. Instead, a large pools of memory are allocated (the size of each pool is *MMGT_NBPAGES* pages). Every new memory block is arranged in a spare place of the current pool. When the current memory pool is completely occupied, the next one is allocated, and so on.
@ -547,15 +671,15 @@ However, unlike small blocks, the recycled medium blocks contained in the free
* Large blocks with a size greater than *MMGT_THRESHOLD*, including memory pools used for small blocks, are allocated depending on the value of *MMGT_MMAP*: if it is 0, these blocks are allocated in the C heap; otherwise they are allocated using operating-system specific functions managing memory mapped files. Large blocks are returned to the system immediately when *Standard::Free()* is called.
#### Benefits and drawbacks
@subsubsection occt_fcug_2_3_4 Benefits and drawbacks
The major benefit of the OCCT memory manager is explained by its recycling of small and medium blocks that makes an application work much faster when it constantly allocates and frees multiple memory blocks of similar sizes. In practical situations, the real gain on the application performance may be up to 50%.
The associated drawback is that recycled memory is not returned to the operating system during program execution. This may lead to considerable memory consumption and even be misinterpreted as a memory leak. To minimize this effect, the method Standard::Purge() shall be called after the completion of memory-intensive operations.
The associated drawback is that recycled memory is not returned to the operating system during program execution. This may lead to considerable memory consumption and even be misinterpreted as a memory leak. To minimize this effect it is necessary to call the method *Standard::Purge* after the completion of memory-intensive operations.
The overhead expenses induced by the OCCT memory manager are:
* size of every allocated memory block is rounded up to 8 bytes (when MMGT_OPT is 0 (default), the rounding is defined by the CRT; the typical value for 32-bit platforms is 4 bytes)
* additional 4 bytes (or 8 on 64-bit platforms) are allocated in the beginning of every memory block to hold its size (or address of the next free memory block when recycled in free list) only when MMGT_OPT is 1
* size of every allocated memory block is rounded up to 8 bytes (when *MMGT_OPT* is 0 (default), the rounding is defined by the CRT; the typical value for 32-bit platforms is 4 bytes)
* additional 4 bytes (or 8 on 64-bit platforms) are allocated in the beginning of every memory block to hold its size (or address of the next free memory block when recycled in free list) only when *MMGT_OPT* is 1.
Note that these overheads may be greater or less than overheads induced by the C heap memory manager, so overall memory consumption may be greater in either optimized or standard modes, depending on circumstances.
@ -564,12 +688,19 @@ As a general rule, it is advisable to allocate memory through significant block
OCCT memory manager uses mutex to lock access to free lists, therefore it may have less performance than non-optimized mode in situations when different threads often make simultaneous calls to the memory manager.
The reason is that modern implementations of *malloc()* and *free()* employ several allocation arenas and thus avoid delays waiting mutex release, which are possible in such situations.
@subsection occt_fcug_2_4 Exception Handling
@subsection occt_fcug_2_4 Exceptions
@subsubsection occt_fcug_2_4_1 Introduction
The behavior of any object is implemented by the methods, which were defined in its class declaration. The definition of these methods includes not only their signature (their programming interface) but also their domain of validity.
This domain is expressed by **exceptions**. Exceptions are raised under various error conditions to protect software quality.
Exception handling provides a means of transferring control from a given point in a program being executed to an **exception handler** associated with another point previously executed.
A method may raise an exception which interrupts its normal execution and transfers control to the handler catching this exception.
Open CASCADE Technology provides a hierarchy of exception classes with a root class being class Standard_Failure from the Standard package. The CDL extractor generates exception classes with standardized interface.
A hierarchy of commonly used exception classes is provided. The root class is *Standard_Failure* from the *Standard* package. So each exception inherits from *Standard_Failure* either directly or by inheriting from another exception. Exception classes list all exceptions, which can be raised by any OCCT function.
Open CASCADE Technology also provides support for converting system signals (such as access violation or division by zero) to exceptions, so that such situations can be safely handled with the same uniform approach.
@ -577,7 +708,7 @@ However, in order to support this functionality on various platforms, some spec
The following paragraphs describe recommended approaches for using exceptions when working with Open CASCADE Technology.
@subsubsection occt_fcug_2_4_1 Raising an Exception
@subsubsection occt_fcug_2_4_2 Raising an Exception
#### “C++ like” Syntax
@ -648,7 +779,7 @@ Item TCollection_Array1::Value (const Standard_Integer&index) const
}
~~~~~
@subsubsection occt_fcug_2_4_2 Handling an Exception
@subsubsection occt_fcug_2_4_3 Handling an Exception
When an exception is raised, control is transferred to the nearest handler of a given type in the call stack, that is:
* the handler whose try block was most recently entered and not yet exited,
@ -736,31 +867,31 @@ Normally this method is called in the beginning of the main() function. It inst
In order to actually convert signals to exceptions, macro *OCC_CATCH_SIGNALS* needs to be inserted in the source code. The typical place where this macro is put is beginning of the *try{}* block which catches such exceptions.
@subsubsection occt_fcug_2_4_3 Implementation details
@subsubsection occt_fcug_2_4_4 Implementation on various platforms.
The exception handling mechanism in Open CASCADE Technology is implemented in different ways depending on the preprocessor macros *NO_CXX_EXCEPTIONS* and *OCC_CONVERT_SIGNALS*, which shall be consistently defined by compilation procedures for both Open CASCADE Technology and user applications:
1. On Windows and DEC, these macros are not defined by default, and normal C++ exceptions are used in all cases, including throwing from signal handler. Thus the behavior is as expected in C++.
1. On Windows, these macros are not defined by default, and normal C++ exceptions are used in all cases, including throwing from signal handler. Thus the behavior is as expected in C++.
2. On SUN and Linux, macro *OCC_CONVERT_SIGNALS* is defined by default. The C++ exception mechanism is used for catching exceptions and for throwing them from normal code. Since it is not possible to throw C++ exception from system signal handler function, that function makes a long jump to the nearest (in the execution stack) invocation of macro *OCC_CATCH_SIGNALS*, and only there the C++ exception gets actually thrown. The macro *OCC_CATCH_SIGNALS* is defined in the file *Standard_ErrorHandler.hxx*. Therefore, including this file is necessary for successful compilation of a code containing this macro.
2. On Linux, macro *OCC_CONVERT_SIGNALS* is defined by default. The C++ exception mechanism is used for catching exceptions and for throwing them from normal code. Since it is not possible to throw C++ exception from system signal handler function, that function makes a long jump to the nearest (in the execution stack) invocation of macro *OCC_CATCH_SIGNALS*, and only there the C++ exception gets actually thrown. The macro *OCC_CATCH_SIGNALS* is defined in the file *Standard_ErrorHandler.hxx*. Therefore, including this file is necessary for successful compilation of a code containing this macro.
This mode differs from standard C++ exception handling only for signals:
* macro *OCC_CATCH_SIGNALS* is necessary (besides call to *OSD::SetSignal()* described above) for conversion of signals into exceptions;
* the destructors for automatic C++ objects created in the code after that macro and till the place where signal is raised will not be called in case of signal, since no C++ stack unwinding is performed by long jump.
3. On SUN and Linux Open CASCADE Technology can also be compiled in compatibility mode (which was default till Open CASCADE Technology 6.1.0). In that case macro *NO_CXX_EXCEPTIONS* is defined and the C++ exceptions are simulated with C long jumps. As a consequence, the behavior is slightly different from that expected in the C++ standard.
3. On Linux Open CASCADE Technology can also be compiled in compatibility mode. In that case macro *NO_CXX_EXCEPTIONS* is defined and the C++ exceptions are simulated with C long jumps. As a consequence, the behavior is slightly different from that expected in the C++ standard.
While exception handling with NO_CXX_EXCEPTIONS is very similar to C++ by syntax, it has a number of peculiarities that should be taken into account:
While exception handling with *NO_CXX_EXCEPTIONS* is very similar to C++ by syntax, it has a number of peculiarities that should be taken into account:
* try and catch are actually macros defined in the file *Standard_ErrorHandler.hxx*. Therefore, including this file is necessary for handling OCCT exceptions;
* due to being a macro, catch cannot contain a declaration of the exception object after its type; only type is allowed in the catch statement. Use method *Standard_Failure::Caught()* to access an exception object;
* catch macro may conflict with some STL classes that might use catch(...) statements in their header files. So STL headers should not be included after *Standard_ErrorHandler.hxx*;
* Open CASCADE Technology try/catch block will not handle normal C++ exceptions; however this can be achieved using special workarounds;
* the try macro defines a C++ object that holds an entry point in the exception handler. Therefore if exception is raised by code located immediately after the try/catch block but on the same nesting level as *try*, it may be handled by that *catch*. This may lead to unexpected behavior, including infinite loop. To avoid that, always surround the try/catch block in \{\} braces;
* the destructors of the C++ objects allocated on the stack after handler initialization are not called by exception raising.
* the try macro defines a C++ object that holds an entry point in the exception handler. Therefore if exception is raised by code located immediately after the try/catch block but on the same nesting level as *try*, it may be handled by that *catch*. This may lead to unexpected behavior, including infinite loop. To avoid that, always surround the try/catch block with curved brackets;
* the destructors of C++ objects allocated on the stack after handler initialization are not called by exception raising.
In general, for writing platform-independent code it is recommended to insert macros *OCC_CATCH_SIGNALS* in try \{\} blocks or other code where signals may happen. For compatibility with previous versions of Open CASCADE Technology the limitations described above for *NO_CXX_EXCEPTIONS* shall be assumed.
In general, for writing platform-independent code it is recommended to insert macros *OCC_CATCH_SIGNALS* in try {} blocks or other code where signals may happen. For compatibility with previous versions of Open CASCADE Technology the limitations described above for *NO_CXX_EXCEPTIONS* shall be assumed.
@subsection occt_fcug_2_5 Plug-In Management
@ -780,9 +911,9 @@ Once it has been loaded, the call to the services provided by the plug-in is di
#### C++ Plug-In Implementation
The C++ plug-in implements a service as an object with functions defined in an abstract class (this abstract class and its parent classes with the GUID are the only information about the plug-in implemented in the client application). The plug-in consists of a sharable library including a method named Factory which creates the C++ object (the client cannot instantiate this object because the plug-in implementation is not visible).
Foundation classes provide in the package **Plugin** a method named Load(), which enables the client to access the required service through a library.
Foundation classes provide in the package *Plugin* a method named *Load()*, which enables the client to access the required service through a library.
That method reads the information regarding available plug-ins and their locations from the resource file Plugin found by environment variable CSF_PluginDefaults:
That method reads the information regarding available plug-ins and their locations from the resource file *Plugin* found by environment variable *CSF_PluginDefaults*:
~~~~~
$CSF_PluginDefaults/.Plugin
@ -904,7 +1035,7 @@ Handle(Standard_Transient) FAFactory::Factory(const Standard_GUID& aGUID)
#### Without using the Software Factory
To create a factory without using the Software Factory, define a *dll* project under Windows or a library under UNIX by using a source file as specified above. The *FAFactory* class is implemented as follows:
To create a factory without using the Software Factory, define a *dll* project under Windows or a library under UNIX by using a source file as specified above. The *FAFactory* class is implemented as follows:
~~~~~
#include <Handle_Standard_Transient.hxx>
@ -920,7 +1051,7 @@ public:
~~~~~
@section occt_fcug_3 Collections, Strings and Unit Conversion
@section occt_fcug_3 Collections, Strings, Quantities and Unit Conversion
@subsection occt_fcug_3_1 Collections
@ -928,18 +1059,35 @@ public:
The **Collections** component contains the classes that handle dynamically sized aggregates of data. They include a wide range of collections such as arrays, lists and maps.
Collections classes are *generic*, that is, they can hold a variety of objects which do not necessarily inherit from a unique root class. When you need to use a collection of a given type of object you must *instantiate* it for this specific type of element. Once this declaration is compiled, all the functions available on the generic collection are available on your *instantiated class*.
Collections classes are *generic* (C++ template-like), that is, they define a structure and algorithms allowing to hold a variety of objects which do not necessarily inherit from a unique root class (similarly to C++ templates).
When you need to use a collection of a given type of object you must *instantiate* it for this specific type of element. Once this declaration is compiled, all the functions available on the generic collection are available on your *instantiated class*.
However, note that:
* Each collection directly used as an argument in OCCT public syntax is instantiated in an OCCT component.
* The *TColStd* package (**Collections of Standard Objects** component) provides numerous instantiations of these generic collections with objects from the **Standard** package or from the **Strings** component.
The **Collections** component provides a wide range of generic collections:
* **Arrays** are generally used for a quick access to the item, however an array is a fixed sized aggregate.
* **Sequences** are variable-sized structures, they avoid the use of large and quasi-empty arrays. A sequence item is longer to access than an array item: only an exploration in sequence is effective (but sequences are not adapted for numerous explorations). Arrays and sequences are commonly used as data structures for more complex objects.
* On the other hand, **maps** are dynamic structures where the size is constantly adapted to the number of inserted items and the access time for an item is effective. Maps structures are commonly used in cases of numerous explorations: they are typically internal data structures for complex algorithms. **Sets** generate the same results as maps but computation time is considerable.
* **Lists, queues** and **stacks** are minor structures similar to sequences but with other exploration algorithms.
* **Maps** are dynamic structures, where the size is constantly adapted to the number of inserted items and access to an item is the fastest. Maps structures are commonly used in cases of numerous explorations: they are typically internal data structures for complex algorithms.
* **Lists** are similar to sequences but have different algorithms to explore them.
* Specific iterators for sequences and maps.
Most collections follow value semantics: their instances are the actual collections, not **handles** to a collection. Only arrays and sequences may also be manipulated by handle, and therefore shared.
Each collection directly used as an argument in Open CASCADE Technology public syntax
is instantiated in an OCCT component using the corresponding generic class in package
<i> TCollection</i>, by means of compiling the CDL declaration of the instance.
Thus OCCT generic classes require compilation of definitions in the CDL language and therefore
can only be instantiated in WOK.
If you do not use CDL in your project (CDL compilation under WOK is necessary
to instantiate any generic Collection from package <i>TCollection</i>), then you should
use the Collections defined in <i> NCollection</i> package. It contains definitions of the
same generic collection classes described above, but in a form of C++ templates.
Therefore, to instantiate any collection type no additional support is required beyond
the ANSI C++ compiler.
@subsubsection occt_fcug_3_1_2 Generic general-purpose Aggregates
#### TCollection_Array1
@ -1059,7 +1207,6 @@ Maps are dynamically extended data structures where data is quickly accessed wi
#### General properties of maps
Map items may contain complex non-unitary data, thus it can be difficult to manage them with an array. The map allows a data structure to be indexed by complex data.
The size of a map is dynamically extended. So a map may be first dimensioned for a little number of items. Maps avoid the use of large and quasi-empty arrays.
@ -1583,9 +1730,15 @@ As one possible choice, the class *NCollection_IncAllocator* is included. Unlike
@subsection occt_fcug_3_4 Strings
The **Strings** component provides services to manipulate character strings.
**Strings** are classes that handle dynamically sized sequences of characters based on both ASCII (normal 8-bit character type) and Unicode (16-bit character type). They provide editing operations with built-in memory management which make the relative objects easier to use than ordinary character arrays.
*Strings* may also be manipulated by *handle*, and therefore shared.
Strings are classes that handle dynamically sized sequences of characters based on
ASCII/Unicode UTF-8 (normal 8-bit character type) and UTF-16/UCS-2 (16-bit character type). They provide editing operations with built-in memory management which make the relative objects easier to use than ordinary character arrays.
String classes provide the following services to manipulate character strings:
* Editing operations on string objects, using a built-in string manager
* Handling of dynamically-sized sequences of characters
* Conversion from/to ASCII and UTF-8 strings.
Strings may also be manipulated by handles and therefore shared.
@subsubsection occt_fcug_3_4_1 Examples
@ -1620,7 +1773,27 @@ A variable-length sequence of extended; (UNICODE) characters (16-bit character
*Resource_Unicode* provides functions to convert a non-ASCII *C string* given in ANSI, EUC, GB or SJIS format, to a Unicode string of extended characters, and vice versa.
@subsection occt_fcug_3_5 Unit Conversion
@subsection occt_fcug_3_5 Quantities
Quantities are various classes supporting date and time information and fundamental types representing most physical quantities such as length, area, volume, mass, density, weight, temperature, pressure etc.
Quantity classes provide the following services:
* Definition of primitive types representing most of mathematical and physical quantities;
* Unit conversion tools providing a uniform mechanism for dealing with quantities and associated physical units: check unit compatibility, perform conversions of values between different units, etc. (see package *UnitsAPI*)
* Resources to manage time information such as dates and time periods
* Resources to manage color definition
A mathematical quantity is characterized by the name and the value (real).
A physical quantity is characterized by the name, the value (real) and the unit. The unit may be either an international unit complying with the International Unit System (SI) or a user defined unit. The unit is managed by the physical quantity user.
The fact that both physical and mathematical quantities are manipulated as real values means that :
* They are defined as aliases of real values, so all functions provided by the <i>Standard_Real</i> class are available on each quantity.
* It is possible to mix several physical quantities in a mathematical or physical formula involving real values.
<i>Quantity</i> package includes all commonly used basic physical quantities.
@subsection occt_fcug_3_6 Unit Conversion
The *UnitsAPI* global functions are used to convert a value from any unit into another unit. Conversion is executed among three unit systems:
* the **SI System**,
@ -1636,15 +1809,32 @@ A physical quantity is defined by a string (example: LENGTH).
@section occt_occt_fcug_4 Math Primitives and Algorithms
@subsection occt_occt_fcug_4_1 Overview
Math primitives and algorithms available in Open CASCADE Technology include:
* Vectors and matrices
* Geometric primitives
* Math algorithms
@subsection occt_occt_fcug_4_2 Vectors and Matrices
The Vectors and Matrices component provides a C++ implementation of the fundamental types Matrix and Vector, currently used to define more complex data structures. The Vector and Matrix classes support vectors and matrices of real values with standard operations such as addition, multiplication, transposition, inversion etc.
Vectors and matrices have arbitrary ranges which must be defined at declaration time and cannot be changed after declaration.
The Vectors and Matrices component provides a C++ implementation of the fundamental types *Vector* and *Matrix*, which are regularly used to define more complex data structures.
The <i> Vector</i> and <i> Matrix </i> classes provide commonly used mathematical algorithms which
include:
* Basic calculations involving vectors and matrices;
* Computation of eigenvalues and eigenvectors of a square matrix;
* Solvers for a set of linear algebraic equations;
* Algorithms to find the roots of a set of non-linear equations;
* Algorithms to find the minimum function of one or more independent variables.
These classes also provide a data structure to represent any expression,
relation, or function used in mathematics, including the assignment of variables.
Vectors and matrices have arbitrary ranges which must be defined at declaration time
and cannot be changed after declaration.
~~~~~
math_Vector v(1, 3);
@ -1694,26 +1884,38 @@ v1(0) = 2.0;
~~~~~~
@subsection occt_occt_fcug_4_3 Primitive Geometric Types
Before creating a geometric object, you must decide whether you are in a 2d or in a 3d context and how you want to handle the object.
The *gp* package offers classes for both 2d and 3d objects which are handled by value rather than by reference. When this sort of object is copied, it is copied entirely. Changes in one instance will not be reflected in another.
Open CASCADE Technology primitive geometric types are a STEP-compliant implementation of basic geometric and algebraic entities.
They provide:
* Descriptions of primitive geometric shapes, such as:
* Points;
* Vectors;
* Lines;
* Circles and conics;
* Planes and elementary surfaces;
* Positioning of these shapes in space or in a plane by means of an axis or a coordinate system;
* Definition and application of geometric transformations to these shapes:
* Translations;
* Rotations;
* Symmetries;
* Scaling transformations;
* Composed transformations;
* Tools (coordinates and matrices) for algebraic computation.
All these functions are provided by geometric processor package <i> gp</i>. Its classes for 2d and 3d objects are handled by value rather than by reference. When this sort of object is copied, it is copied entirely. Changes in one instance will not be reflected in another.
The *gp* package defines the basic non-persistent geometric entities used for algebraic calculation and basic analytical geometry in 2d & 3d space. It also provides basic transformations such as identity, rotation, translation, mirroring, scale transformations, combinations of transformations, etc. Entities are handled by value.
The available geometric entities are:
* 2d & 3d Cartesian coordinates (x, y, z)
* Matrices
* Cartesian points
* Vector
* Direction
* Axis
* Line
* Circle
* Ellipse
* Hyperbola
* Parabola
* Plane
* Infinite cylindrical surface
* Spherical surface
* Toroidal surface
* Conical surface.
Please, note that <i> gp</i> curves and surfaces are analytic: there is no parameterization and no orientation on <i>gp</i> entities, i.e. these entities do not provide functions which work with these properties.
If you need, you may use more evolved data structures provided by <i> Geom</i> (in 3D space) and <i> Geom2d</i> (in the plane). However, the definition of <i> gp</i> entities is identical to the one of equivalent <i> Geom</i> and <i> Geom2d</i> entities, and they are located in the plane or in space with the same kind of positioning systems. They implicitly contain the orientation, which they express on the <i> Geom </i> and <i> Geom2d </i> entities, and they induce the definition of their parameterization.
Therefore, it is easy to give an implicit parameterization to <i> gp</i> curves and surfaces, which is the parametrization of the equivalent <i> Geom</i> or <i> Geom2d</i> entity. This property is particularly useful when computing projections or intersections, or for operations involving complex algorithms where it is particularly important to manipulate the simplest data structures, i.e. those of <i> gp</i>. Thus, <i> ElCLib</i> and <i> ElSLib</i> packages provide functions to compute:
* the point of parameter u on a 2D or 3D gp curve,
* the point of parameter (u,v) on a gp elementary surface, and
* any derivative vector at this point.
Note: the <i> gp</i> entities cannot be shared when they are inside more complex data structures.
@subsection occt_occt_fcug_4_4 Collections of Primitive Geometric Types

15
dox/user_guides/iges/iges.md
View File

@ -5,10 +5,19 @@ IGES Support {#occt_user_guides__iges}
@section occt_iges_1 Introduction
The IGES interface reads IGES files and translates them to Open CASCADE Technology models. The interface is able to translate one entity, a group of entities or a whole file. Before beginning a translation, you can set a range of parameters to manage the translation process. If you like, you can also check file consistency before translation. The IGES interface also translates OCCT models to IGES files.
This manual explains how to convert an IGES file to an Open CASCADE Technology (**OCCT**) shape and vice versa. It provides basic documentation on conversion. For advanced information on conversion, see our offerings on our web site at <a href="http://www.opencascade.org/support/training/">www.opencascade.org/support/training/</a>
Other kinds of data such as colors and names can be read or written with the help of XDE tools <i> IGESCAFControl_Reader</i> and <i> IGESCAFControl_Writer</i>.
IGES files up to and including IGES version 5.3 can be read. IGES files that are produced by this interface conform to IGES version 5.3 (Initial Graphics Exchange Specification, IGES 5.3. ANS US PRO/IPO-100-1996).
Please, note:
* an IGES model is an IGES file that has been loaded into memory.
* an IGES entity is an entity in the IGES normal sense.
* 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.
This manual mainly explains how to convert an IGES file to an Open CASCADE Technology (**OCCT**) shape and vice versa. It provides basic documentation on conversion. For advanced information on conversion, see our offerings on our web site at <a href="http://www.opencascade.org/support/training/">www.opencascade.org/support/training/</a>
IGES files produced in accordance with IGES standard versions up to and including version 5.3 can be read. IGES files that are produced by this interface conform to IGES version 5.3 (Initial Graphics Exchange Specification, IGES 5.3. ANS US PRO/IPO-100-1996).
This manual principally deals with two OCCT classes:
* The Reader class, which loads IGES files and translates their contents to OCCT shapes,
@ -18,6 +27,8 @@ File translation is performed in the programming mode, via C++ calls, and the r
All definitions in IGES version 5.3 are recognized but only 3D geometric entities are translated. When the processor encounters data, which is not translated, it ignores it and writes a message identifying the types of data, which was not handled. This message can be written either to a log file or to screen output.
@ref occt_user_guides__shape_healing "Shape Healing" toolkit provides tools to heal various problems, which may be encountered in translated shapes, and to make them valid in Open CASCADE. The Shape Healing is smoothly connected to IGES translator using the same API, only the names of API packages change.
@section occt_iges_2 Reading IGES
@subsection occt_iges_2_1 Procedure
You can translate an IGES file to an OCCT shape by following the steps below:

BIN
dox/user_guides/modeling_algos/images/modeling_algos_image019.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 14 KiB

BIN
dox/user_guides/modeling_algos/images/modeling_algos_image058.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 1.9 KiB

BIN
dox/user_guides/modeling_algos/images/modeling_algos_image059.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 14 KiB

BIN
dox/user_guides/modeling_algos/images/modeling_algos_image060.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 47 KiB

BIN
dox/user_guides/modeling_algos/images/modeling_algos_image061.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 30 KiB

1032
dox/user_guides/modeling_algos/modeling_algos.md
View File

File diff suppressed because it is too large Load Diff

384
dox/user_guides/modeling_data/modeling_data.md
View File

@ -5,24 +5,37 @@ Modeling Data {#occt_user_guides__modeling_data}
@section occt_modat_0 Introduction
Modeling Data supplies data structures to represent 2D and 3D geometric models. This manual explains how to use Modeling Data. For advanced information on modeling data, see our offerings on our web site at <a href="http://www.opencascade.org/support/training/">www.opencascade.org/support/training/</a>
Modeling Data supplies data structures to represent 2D and 3D geometric models.
This manual explains how to use Modeling Data. For advanced information on modeling data, see our offerings on our web site at <a href="http://www.opencascade.org/support/training/">www.opencascade.org/support/training/</a>.
@section occt_modat_1 Geometry Utilities
Geometry Utilities provide the following services:
* Creation of shapes by interpolation and approximation
* Direct construction of shapes
* Conversion of curves and surfaces to Bspline curves and surfaces
* Conversion of curves and surfaces to BSpline curves and surfaces
* Computation of the coordinates of points on 2D and 3D curves
* Calculation of extrema between shapes.
@subsection occt_modat_1_1 Interpolations and Approximations
In modeling, it is often required to approximate or interpolate points into curves and surfaces. In interpolation, the process is complete when the curve or surface passes through all the points; in approximation, when it is as close to these points as possible. This component provides both high and low level services to approximate or interpolate points into curves and surfaces. The lower level services allow performing parallel approximation of groups of points into groups of Bezier or B-spline curves.
In modeling, it is often required to approximate or interpolate points into curves and surfaces. In interpolation, the process is complete when the curve or surface passes through all the points; in approximation, when it is as close to these points as possible.
Approximation of Curves and Surfaces groups together a variety of functions used in 2D and 3D geometry for:
* the interpolation of a set of 2D points using a 2D BSpline or Bezier curve;
* the approximation of a set of 2D points using a 2D BSpline or Bezier curve;
* the interpolation of a set of 3D points using a 3D BSpline or Bezier curve, or a BSpline surface;
* the approximation of a set of 3D points using a 3D BSpline or Bezier curve, or a BSpline surface.
You can program approximations in two ways:
* Using high-level functions, designed to provide a simple method for obtaining approximations with minimal programming,
* Using low-level functions, designed for users requiring more control over the approximations.
@subsubsection occt_modat_1_1_1 Analysis of a set of points
The class *PEquation* from *GProp* package allows analyzng a collection or cloud of points and verifying if they are coincident, collinear or coplanar within a given precision. If they are, the algorithm computes the mean point, the mean line or the mean plane of the points. If they are not, the algorithm computes the minimal box, which includes all the points.
The class *PEquation* from *GProp* package allows analyzing a collection or cloud of points and verifying if they are coincident, collinear or coplanar within a given precision. If they are, the algorithm computes the mean point, the mean line or the mean plane of the points. If they are not, the algorithm computes the minimal box, which includes all the points.
@subsubsection occt_modat_1_1_2 Basic Interpolation and Approximation
@ -78,6 +91,15 @@ The class **PointsToBSplineSurface** from GeomAPI package allows building a BSpl
Packages *AppDef* and *AppParCurves* provide low-level functions, allowing more control over the approximations.
The low-level functions provide a second API with functions to:
* Define compulsory tangents for an approximation. These tangents have origins and extremities.
* Approximate a set of curves in parallel to respect identical parameterization.
* Smooth approximations. This is to produce a faired curve.
You can also find functions to compute:
* The minimal box which includes a set of points
* The mean plane, line or point of a set of coplanar, collinear or coincident points.
#### Approximation by multiple point constraints
*AppDef* package provides low-level tools to allow parallel approximation of groups of points into Bezier or B-Spline curves using multiple point constraints.
@ -86,7 +108,7 @@ The following low level services are provided:
* Definition of an array of point constraints:
The class *MultiLine* allows defining a given number of multipoint constraints in order to build the multi-line, multiple lines passing through ordered multiple point constraints.
The class *MultiLine* allows defining a given number of multi-point constraints in order to build the multi-line, multiple lines passing through ordered multiple point constraints.
@image html /user_guides/modeling_data/images/modeling_data_image004.png "Definition of a MultiLine using Multiple Point Constraints"
@image latex /user_guides/modeling_data/images/modeling_data_image004.png "Definition of a MultiLine using Multiple Point Constraints"
@ -98,7 +120,7 @@ The following low level services are provided:
* Definition of a set of point constraints:
The class **MultiPointConstraint** allows defining a multiple point constraint and computing the approximation of sets of points to several curves.
The class *MultiPointConstraint* allows defining a multiple point constraint and computing the approximation of sets of points to several curves.
* Computation of an approximation of a Bezier curve from a set of points:
@ -106,7 +128,7 @@ The following low level services are provided:
* Computation of an approximation of a BSpline curve from a set of points:
The class **BSplineCompute** allows making an approximation of a set of points to a BSpline curve.
The class *BSplineCompute* allows making an approximation of a set of points to a BSpline curve.
* Definition of Variational Criteria:
@ -138,13 +160,48 @@ The class *MultiBSpCurve* allows defining the approximation of a multi-line made
* Definition of points making up a set of point constraints
The class *MultiPoint* allows defining groups of 2D or 3D points making up a multi-line.
#### Example: How to approximate a curve with respect to tangency
To approximate a curve with respect to tangency, follow these steps:
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.
2. Create an object of type <i> AppDef_MultiLine </i>from the <i> AppDef_MultiPointConstraint</i>.
3. Use <i> AppDef_BSplineCompute</i>, which instantiates <i>Approx_BSplineComputeLine</i> to perform the approximation.
@subsection occt_modat_1_2 Direct Construction
Direct Construction methods from *gce*, *GC* and *GCE2d* packages provide simplified algorithms to build elementary geometric entities such as lines, circles and curves. They complement the reference definitions provided by the *gp*, *Geom* and *Geom2d* packages.
The algorithms implemented by <i> gce</i>, <i> GCE2d</i> and <i> GC</i> packages are simple: there is no creation of objects defined by advanced positional constraints (for more information on this subject, see *Geom2dGcc* and *GccAna*, which describe geometry by constraints).
For example, to construct a circle from a point and a radius using the *gp* package, it is necessary to construct axis *Ax2d* before creating the circle. If *gce* package is used, and *Ox* is taken for the axis, it is possible to create a circle directly from a point and a radius.
Another example is the class <i>gce_MakeCirc</i> providing a framework for defining eight problems encountered in the geometric construction of circles and implementing the eight related construction algorithms.
The object created (or implemented) is an algorithm which can be consulted to find out, in particular:
* its result, which is a <i>gp_Circ</i>, and
* its status. Here, the status indicates whether or not the construction was successful.
If it was unsuccessful, the status gives the reason for the failure.
~~~~
gp_Pnt P1 (0.,0.,0.);
gp_Pnt P2 (0.,10.,0.);
gp_Pnt P3 (10.,0.,0.);
gce_MakeCirc MC (P1,P2,P3);
if (MC.IsDone()) {
const gp_Circ& C = MC.Value();
}
~~~~
In addition, <i> gce</i>, <i> GCE2d</i> and <i> GC</i> each have a <i>Root</i> class. This class is the root of all classes in the package, which return a status. The returned status (successful
construction or construction error) is described by the enumeration <i>gce_ErrorType</i>.
Note, that classes, which construct geometric transformations do not return a status, and therefore do not inherit from *Root*.
@subsubsection occt_modat_1_2_1 Non-persistent entities
The following algorithms used to build entities from non-persistent *gp* entities are provided by *gce* package.
@ -245,16 +302,52 @@ The following classes return objects of type *TrimmedCurve* from *Geom*:
@subsection occt_modat_1_3 Conversion to and from BSplines
The following algorithms to convert geometric curves or surfaces into their BSpline or Bezier equivalents are provided by *GeomConvert*, *Geom2dConvert* and *Convert* packages:
- Conversion of a conic into a rational BSpline.
- Conversion of an elementary surface into a rational Bspline.
- Conversion of a BSpline or Bezier curve into two or more Bezier curves or surfaces.
- Conversion of a BSpline curve or surface into two or more BSplinecurves or surfaces with constraints on continuity.
- Conversion of a set of joining Bezier curves into a BSplinecurve.
- Conversion of a polynomial representation into a BSpline curve.
The Conversion to and from BSplines component has two distinct purposes:
* Firstly, it provides a homogeneous formulation which can be used to describe any curve or surface.
This is useful for writing algorithms for a single data structure model.
The BSpline formulation can be used to represent most basic geometric objects provided
by the components which describe geometric data structures ("Fundamental Geometry Types", "2D Geometry Types" and "3D Geometry Types" components).
* Secondly, it can be used to divide a BSpline curve or surface into a series of curves or surfaces,
thereby providing a higher degree of continuity. This is useful for writing algorithms
which require a specific degree of continuity in the objects to which they are applied.
Discontinuities are situated on the boundaries of objects only.
The "Conversion to and from BSplines" component is composed of three packages.
The <i> Convert </i> package provides algorithms to convert the following into a BSpline curve or surface:
* a bounded curve based on an elementary 2D curve (line, circle or conic) from the <i> gp </i> package,
* a bounded surface based on an elementary surface (cylinder, cone, sphere or torus) from the <i> gp</i> package,
* a series of adjacent 2D or 3D Bezier curves defined by their poles.
These algorithms compute the data needed to define the resulting BSpline curve or surface.
This elementary data (degrees, periodic characteristics, poles and weights, knots and multiplicities)
may then be used directly in an algorithm, or can be used to construct the curve or the surface
by calling the appropriate constructor provided by the classes <i>Geom2d_BSplineCurve, Geom_BSplineCurve </i> or <i>Geom_BSplineSurface</i>.
The <i>Geom2dConvert</i> package provides the following:
* a global function which is used to construct a BSpline curve from a bounded curve based on a 2D curve from the Geom2d package,
* 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,
* global functions used to construct the BSpline curves created by this splitting algorithm, or by other types of segmentation of the BSpline curve,
* an algorithm which converts a 2D BSpline curve into a series of adjacent Bezier curves.
The <i> GeomConvert</i> package also provides the following:
* a global function used to construct a BSpline curve from a bounded curve based on a curve from the Geom package,
* 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,
* global functions to construct BSpline curves created by this splitting algorithm, or by other types of BSpline curve segmentation,
* an algorithm, which converts a BSpline curve into a series of adjacent Bezier curves,
* a global function to construct a BSpline surface from a bounded surface based on a surface from the Geom package,
* 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,
* global functions to construct BSpline surfaces created by this splitting algorithm, or by other types of BSpline surface segmentation,
* an algorithm, which converts a BSpline surface into a series of adjacent Bezier surfaces,
* an algorithm, which converts a grid of adjacent Bezier surfaces into a BSpline surface.
@subsection occt_modat_1_4 Points on Curves
The Points on Curves component comprises high level functions providing an API for complex algorithms that compute points on a 2D or 3D curve.
The following characteristic points exist on parameterized curves in 3d space:
- points equally spaced on a curve,
- points distributed along a curve with equal chords,
@ -267,7 +360,6 @@ The following characteristic points exist on parameterized curves in 3d space:
### Example: Visualizing a curve.
Let us take an adapted curve **C**, i.e. an object which is an interface between the services provided by either a 2D curve from the package Geom2d (in case of an Adaptor_Curve2d curve) or a 3D curve from the package Geom (in case of an Adaptor_Curve curve), and the services required on the curve by the computation algorithm. The adapted curve is created in the following way:
**2D case :**
@ -312,23 +404,30 @@ These packages calculate the extrema of distance between:
- a curve and a surface,
- two surfaces.
@subsubsection occt_modat_1_5_1 Extrema between Curves
### Extrema between Curves
The *Geom2dAPI_ExtremaCurveCurve* class allows calculation of all extrema between two 2D geometric curves. Extrema are the lengths of the segments orthogonal to two curves.
The *GeomAPI_ExtremaCurveCurve* class allows calculation of all extrema between two 3D geometric curves. Extrema are the lengths of the segments orthogonal to two curves.
@subsubsection occt_modat_1_5_2 Extrema between Curve and Surface
### Extrema between Curve and Surface
The *GeomAPI_ExtremaCurveSurface* class allows calculation of all extrema between a 3D curve and a surface. Extrema are the lengths of the segments orthogonal to the curve and the surface.
@subsubsection occt_modat_1_5_3 Extrema between Surfaces
### Extrema between Surfaces
The *GeomAPI_ExtremaSurfaceSurface* class allows calculation of all extrema between two surfaces. Extrema are the lengths of the segments orthogonal to two surfaces.
@section occt_modat_2 2D Geometry
*Geom2d* package defines geometric objects in 2dspace. All geometric entities are STEP processed. The objects are non-persistent and are handled by reference. The following objects are available:
*Geom2d* package defines geometric objects in 2dspace. All geometric entities are STEP processed. The objects are non-persistent and are handled by reference.
In particular, <i>Geom2d</i> package provides classes for:
* description of points, vectors and curves,
* their positioning in the plane using coordinate systems,
* their geometric transformation, by applying translations, rotations, symmetries, scaling transformations and combinations thereof.
The following objects are available:
- point,
- Cartesian point,
- vector,
@ -337,9 +436,9 @@ The *GeomAPI_ExtremaSurfaceSurface* class allows calculation of all extrema betw
- axis,
- curve,
- line,
- conic: circle, ellipse, hyperbola, pparabola,
- rounded curve: trimmed curve, NURBS curve, Bezier curve.
- offset curve
- conic: circle, ellipse, hyperbola, parabola,
- rounded curve: trimmed curve, NURBS curve, Bezier curve,
- offset curve.
Before creating a geometric object, it is necessary to decide how the object is handled.
The objects provided by *Geom2d* package are handled by reference rather than by value. Copying an instance copies the handle, not the object, so that a change to one instance is reflected in each occurrence of it.
@ -347,9 +446,45 @@ If a set of object instances is needed rather than a single object instance, *
- handled by reference and
- handled by value.
The key characteristic of <i> Geom2d </i> curves is that they are parameterized.
Each class provides functions to work with the parametric equation of the curve,
and, in particular, to compute the point of parameter u on a curve and the derivative vectors of order 1, 2.., N at this point.
As a consequence of the parameterization, a <i> Geom2d </i> curve is naturally oriented.
Parameterization and orientation differentiate elementary <i>Geom2d </i>curves from their
equivalent as provided by <i> gp</i> package. <i> Geom2d</i> package provides conversion
functions to transform a <i> Geom2d</i> object into a <i> gp</i> object, and vice-versa, when this is possible.
Moreover, <i> Geom2d</i> package provides more complex curves, including Bezier curves,
BSpline curves, trimmed curves and offset curves.
<i> Geom2d </i> objects are organized according to an inheritance structure over several levels.
Thus, an ellipse (specific class <i> Geom2d_Ellipse</i>) is also a conical curve and inherits from the abstract class <i> Geom2d_Conic</i>, while a Bezier curve (concrete class <i> Geom2d_BezierCurve</i>) is also a bounded curve and inherits from the abstract class <i> Geom2d_BoundedCurve</i>; both these examples are also curves (abstract class <i>Geom2d_Curve</i>). Curves, points and vectors inherit from the abstract class <i> Geom2d_Geometry,</i> which describes the properties common to any geometric object from the <i>Geom2d</i> package.
This inheritance structure is open and it is possible to describe new objects, which inherit from those provided in the <i>Geom2d</i> package, provided that they respect the behavior of the classes from which they are to inherit.
Finally, <i> Geom2d</i> objects can be shared within more complex data structures. This is why they are used within topological data structures, for example.
<i>Geom2d</i>package uses the services of the <i> gp</i> package to:
* implement elementary algebraic calculus and basic analytic geometry,
* describe geometric transformations which can be applied to <i> Geom2d</i> objects,
* describe the elementary data structures of <i>Geom2d</i> objects.
However, the <i> Geom2d</i> package essentially provides data structures and not algorithms.
You can refer to the <i> GCE2d </i> package to find more evolved construction algorithms for <i> Geom2d </i> objects.
@section occt_modat_3 3D Geometry
The *Geom* package defines geometric objects in 3d space and contains all basic geometric transformations, such as identity, rotation, translation, mirroring, scale transformations, combinations of transformations, etc. as well as special functions depending on the reference definition of the geometric object (e.g. addition of a control point on a B-Spline curve,modification of a curve, etc.). All geometrical entities are STEP processed. The following non-persistent and reference-handled objects are available:
The *Geom* package defines geometric objects in 3d space and contains all basic geometric transformations, such as identity, rotation, translation, mirroring, scale transformations, combinations of transformations, etc. as well as special functions depending on the reference definition of the geometric object (e.g. addition of a control point on a B-Spline curve,modification of a curve, etc.). All geometrical entities are STEP processed.
In particular, it provides classes for:
* description of points, vectors, curves and surfaces,
* their positioning in 3D space using axis or coordinate systems, and
* their geometric transformation, by applying translations, rotations, symmetries, scaling transformations and combinations thereof.
The following non-persistent and reference-handled objects are available:
- Point
- Cartesian point
- Vector
@ -366,13 +501,125 @@ The *Geom* package defines geometric objects in 3d space and contains all basic
- Swept surface: surface of linear extrusion, surface of revolution
- Offset surface.
The key characteristic of *Geom* curves and surfaces is that they are parameterized.
Each class provides functions to work with the parametric equation of the curve or
surface, and, in particular, to compute:
* the point of parameter u on a curve, or
* the point of parameters (u, v) on a surface.
together with the derivative vectors of order 1, 2, ... N at this point.
As a consequence of this parameterization, a Geom curve or surface is naturally oriented.
Parameterization and orientation differentiate elementary Geom curves and surfaces from the classes of the same (or similar) names found in <i> gp</i> package.
<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.
Moreover, <i> Geom </i>package provides more complex curves and surfaces, including:
* Bezier and BSpline curves and surfaces,
* swept surfaces, for example surfaces of revolution and surfaces of linear extrusion,
* trimmed curves and surfaces, and
* offset curves and surfaces.
Geom objects are organized according to an inheritance structure over several levels.
Thus, a sphere (concrete class <i> Geom_SphericalSurface</i>) is also an elementary surface and inherits from the abstract class <i> Geom_ElementarySurface</i>, while a Bezier surface (concrete class <i> Geom_BezierSurface</i>) is also a bounded surface and inherits from the abstract class <i> Geom_BoundedSurface</i>; both these examples are also surfaces (abstract class <i> Geom_Surface</i>). Curves, points and vectors inherit from the abstract class <i> Geom_Geometry,</i> which describes the properties common to any geometric object from the <i>Geom</i> package.
This inheritance structure is open and it is possible to describe new objects, which inherit from those provided in the Geom package, on the condition that they respect the behavior of the classes from which they are to inherit.
Finally, Geom objects can be shared within more complex data structures. This is why they are used within topological data structures, for example.
If a set of object instances is needed rather than a single object instance, *TColGeom* package can be used. This package provides instantiations of one- and two-dimensional arrays and sequences for curves from *Geom* package. All objects are available in two versions:
- handled by reference and
- handled by value.
@subsection occt_modat_4 Local Properties of Curves and Surfaces
The <i> Geom</i> package uses the services of the <i> gp</i> package to:
* implement elementary algebraic calculus and basic analytic geometry,
* describe geometric transformations which can be applied to Geom objects,
* describe the elementary data structures of Geom objects.
Packages **GeomLProp**, **Geom2dLProp** provide algorithms calculating the local properties of curves and surfaces
However, the Geom package essentially provides data structures, not algorithms.
You can refer to the <i> GC</i> package to find more evolved construction algorithms for
Geom objects.
@section occt_modat_4 Properties of Shapes
@subsection occt_modat_4_1 Local Properties of Shapes
<i>BRepLProp</i> package provides the Local Properties of Shapes component,
which contains algorithms computing various local properties on edges and faces in a BRep model.
The local properties which may be queried are:
* for a point of parameter u on a curve which supports an edge :
* the point,
* the derivative vectors, up to the third degree,
* the tangent vector,
* the normal,
* the curvature, and the center of curvature;
* for a point of parameter (u, v) on a surface which supports a face :
* the point,
* the derivative vectors, up to the second degree,
* the tangent vectors to the u and v isoparametric curves,
* the normal vector,
* the minimum or maximum curvature, and the corresponding directions of curvature;
* the degree of continuity of a curve which supports an edge, built by the concatenation of two other edges, at their junction point.
Analyzed edges and faces are described as <i> BRepAdaptor</i> curves and surfaces,
which provide shapes with an interface for the description of their geometric support.
The base point for local properties is defined by its u parameter value on a curve, or its (u, v) parameter values on a surface.
@subsection occt_modat_4_2 Local Properties of Curves and Surfaces
The "Local Properties of Curves and Surfaces" component provides algorithms for computing various local properties on a Geom curve (in 2D or 3D space) or a surface. It is composed of:
* <i> Geom2dLProp</i> package, which allows computing Derivative and Tangent vectors (normal and curvature) of a parametric point on a 2D curve;
* <i> GeomLProp </i> package, which provides local properties on 3D curves and surfaces
* <i> LProp </i> package, which provides an enumeration used to characterize a particular point on a 2D curve.
Curves are either <i> Geom_Curve </i> curves (in 3D space) or <i> Geom2d_Curve </i> curves (in the plane).
Surfaces are <i> Geom_Surface </i> surfaces. The point on which local properties are calculated
is defined by its u parameter value on a curve, and its (u,v) parameter values on a surface.
It is possible to query the same local properties for points as mentioned above, and additionally for 2D curves:
* the points corresponding to a minimum or a maximum of curvature;
* the inflection points.
#### Example: How to check the surface concavity
To check the concavity of a surface, proceed as follows:
1. Sample the surface and compute at each point the Gaussian curvature.
2. If the value of the curvature changes of sign, the surface is concave or convex depending on the point of view.
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>.
@subsection occt_modat_4_3 Global Properties of Shapes
The Global Properties of Shapes component provides algorithms for computing the global
properties of a composite geometric system in 3D space, and frameworks to query the computed results.
The global properties computed for a system are :
* mass,
* mass center,
* matrix of inertia,
* moment about an axis,
* radius of gyration about an axis,
* principal properties of inertia such as principal axis, principal moments, and principal radius of gyration.
Geometric systems are generally defined as shapes. Depending on the way they are analyzed, these shapes will give properties of:
* lines induced from the edges of the shape,
* surfaces induced from the faces of the shape, or
* volumes induced from the solid bounded by the shape.
The global properties of several systems may be brought together to give the global properties of the system composed of the sum of all individual systems.
The Global Properties of Shapes component is composed of:
* 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),
* a framework for computing global properties for a set of points (<i>GProp_PGProps</i>),
* 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.
Packages *GeomLProp* and *Geom2dLProp* provide algorithms calculating the local properties of curves and surfaces
A curve (for one parameter) has the following local properties:
- Point
@ -401,24 +648,77 @@ The following methods are available:
Note that the B-spline curve and surface are accepted but they are not cut into pieces of the desired continuity. It is the global continuity, which is seen.
@subsection occt_modat_5 Adaptors for Curves and Surfaces
Some Open CASCADE Technology general algorithms may work theoretically on numerous types of curves or surfaces.
To do this, they simply get the services required of the analyzed curve or surface through an interface so as to a single API, whatever the type of curve or surface. These interfaces are called adaptors.
For example, <i> Adaptor3d_Curve </i> is the abstract class which provides the required services by an algorithm which uses any 3d curve.
<i> GeomAdaptor </i> package provides interfaces:
* On a Geom curve;
* On a curve lying on a Geom surface;
* On a Geom surface;
<i> Geom2dAdaptor</i> package provides interfaces :
* On a <i>Geom2d</i> curve.
<i> BRepAdaptor </i> package provides interfaces:
* On a Face
* On an Edge
When you write an algorithm which operates on geometric objects, use <i> Adaptor3d</i> (or <i> Adaptor2d</i>) objects.
As a result, you can use the algorithm with any kind of object, if you provide for this object an interface derived from *Adaptor3d* or *Adaptor2d*.
These interfaces are easy to use: simply create an adapted curve or surface from a *Geom2d* curve, and then use this adapted curve as an argument for the algorithm? which requires it.
@section occt_modat_5 Topology
Open CASCADE Technology Topology allows accessing and manipulating objects data without dealing with their 2D or 3D representations. Whereas OCCT Geometry provides a description of objects in terms of coordinates or parametric values, Topology describes data structures of objects in parametric space. These descriptions use location in and restriction of parts of this space.
OCCT Topology allows accessing and manipulating data of objects without dealing with their 2D or 3D representations. Whereas OCCT Geometry provides a description of objects in terms of coordinates or parametric values, Topology describes data structures of objects in parametric space. These descriptions use location in and restriction of parts of this space.
To provide its descriptions, OCCT abstract topology offers the following services:
- Keeping track of Location of shapes
- Naming shapes, sub-shapes, their orientations and states
- Manipulating shapes and sub-shapes
- Exploring topological data structures
- Using lists and maps of shapes
Topological library allows you to build pure topological data structures. Topology defines relationships between simple geometric entities. In this way, you can model complex shapes as assemblies of simpler entities. Due to a built-in non-manifold (or mixed-dimensional) feature, you can build models mixing:
* 0D entities such as points;
* 1D entities such as curves;
* 2D entities such as surfaces;
* 3D entities such as volumes.
You can, for example, represent a single object made of several distinct bodies containing embedded curves and surfaces connected or non-connected to an outer boundary.
Abstract topological data structure describes a basic entity - a shape, which can be divided into the following component topologies:
* Vertex - a zero-dimensional shape corresponding to a point in geometry;
* Edge - a shape corresponding to a curve, and bound by a vertex at each extremity;
* Wire - a sequence of edges connected by their vertices;
* Face - part of a plane (in 2D geometry) or a surface (in 3D geometry) bounded by a closed wire;
* Shell - a collection of faces connected by some edges of their wire boundaries;
* Solid - a part of 3D space bound by a shell;
* Compound solid - a collection of solids.
The wire and the solid can be either infinite or closed.
A face with 3D underlying geometry may also refer to a collection of connected triangles that approximate the underlying surface. The surfaces can be undefined leaving the faces represented by triangles only. If so, the model is purely polyhedral.
Topology defines the relationship between simple geometric entities, which can thus be linked together to represent complex shapes.
Abstract Topology is provided by six packages.
The first three packages describe the topological data structure used in Open CASCADE Technology:
* <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.
* <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.
* <i> TopoDS</i> package describes classes to model and build data structures that are purely topological.
Three additional packages provide tools to access and manipulate this abstract topology:
* <i> TopTools</i> package provides basic tools to use on topological data structures.
* <i> TopExp</i> package provides classes to explore and manipulate the topological data structures described in the TopoDS package.
* <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.
@subsection occt_modat_5_1 Shape Location
A local coordinate system can be viewed as either of the following:
- A right-handed trihedron with an origin and three orthonormal vectors. The **gp_Ax2** package corresponds to this definition.
- A transformation of a +1 determinant, allowing the transformation of coordinates between local and global references frames. This corresponds to the **gp_Trsf**.
- A right-handed trihedron with an origin and three orthonormal vectors. The *gp_Ax2* package corresponds to this definition.
- A transformation of a +1 determinant, allowing the transformation of coordinates between local and global references frames. This corresponds to the *gp_Trsf*.
*TopLoc* package distinguishes two notions:
- *TopLoc_Datum3D* class provides the elementary reference coordinate, represented by a right-handed orthonormal system of axes or by a right-handed unitary transformation.
@ -439,21 +739,19 @@ C4 = R1 * C2
**NOTE** C3 and C4 are equal because they are both R1 * R2 * R3.
The TopLoc package is chiefly targeted at the topological data structure, but it can be used for other purposes.
The *TopLoc* package is chiefly targeted at the topological data structure, but it can be used for other purposes.
Change of coordinates
---------------------
*TopLoc_Datum3D* class represents a change of elementary coordinates. Such changes must be shared so this class inherits from *MMgt_TShared*. The coordinate is represented by a transformation *gp_Trsfpackage*. This transformation has no scaling factor.
@subsection occt_modat_5_2 Naming shapes, sub-shapes, their orientation and state
The **TopAbs** package provides general enumerations describing the basic concepts of topology and methods to handle these enumerations. It contains no classes. This package has been separated from the rest of the topology because the notions it contains are sufficiently general to be used by all topological tools. This avoids redefinition of enumerations by remaining independent of modeling resources. The TopAbs package defines three notions:
- Topological type (TopAbs_ShapeEnum)
- Orietation (TopAbs_Orientation)
- StateTopAbs_State)
- **Type** *TopAbs_ShapeEnum*;
- **Orientation** *TopAbs_Orientation* ;
- **State** *StateTopAbs_State*
@subsubsection occt_modat_5_2_1 Topological types
@ -920,7 +1218,7 @@ Below is the auxiliary function, which copies the element of rank *i* from the m
@subsubsection occt_modat_5_5_1 Wire Explorer
BRepTools_WireExplorer class can access edges of a wire in their order of connection.
*BRepTools_WireExplorer* class can access edges of a wire in their order of connection.
For example, in the wire in the image we want to recuperate the edges in the order {e1, e2, e3,e4, e5} :
@ -937,4 +1235,6 @@ For example, in the wire in the image we want to recuperate the edges in the ord
ProcessTheVertexConnectingTheCurrentEdgeToThePrevious
One(Ex.CurrentVertex());
}
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

280
dox/user_guides/ocaf/ocaf.md
View File

@ -145,7 +145,6 @@ Documents offer access to the data framework and manage the following items:
@subsubsection occt_ocaf_2_3_2 Shape attribute
The shape attribute implements the functionality of the OCCT topology manipulation:
* reference to the shapes
* tracking of shape evolution
@ -164,6 +163,7 @@ Where the document manages the notification of changes, a function manages propa
@image html /user_guides/ocaf/images/ocaf_image008.png "Document structure"
@image latex /user_guides/ocaf/images/ocaf_image008.png "Document structure"
@section occt_ocaf_3 Data Framework Services
@subsection occt_ocaf_3_1 Overview
@ -416,11 +416,11 @@ If you use a standard file format and you want your new attributes to be stored
If you use the XML format, do the following:
1. Create a new package with the name Xml[package name] (for example *XmlMyAttributePackage*) containing class *XmlMyAttributePackage_MyAttributeDriver*. The new class inherits *XmlMDF_ADriver* class and contains the translation functionality: from transient to persistent and vice versa (see the realization of the standard attributes in the packages *XmlMDataStd*, for example). Add package method AddDrivers which adds your class to a driver table (see below).
2. Create a new package (or do it in the current one) with two package methods:
* Factory, which loads the document storage and retrieval drivers; and
* AttributeDrivers, which calls the methods AddDrivers for all packages responsible for persistence of the document.
* *Factory*, which loads the document storage and retrieval drivers; and
* *AttributeDrivers*, which calls the methods AddDrivers for all packages responsible for persistence of the document.
3. Create a plug-in implemented as an executable (see example *XmlPlugin*). It calls a macro PLUGIN with the package name where you implemented the method Factory.
If you use the binary format, do the following:
1. Create a new package with name Bin[package name] (for example *BinMyAttributePackage*) containing a class *BinMyAttributePackage_MyAttributeDriver*. The new class inherits *BinMDF_ADriver* class and contains the translation functionality: from transient to persistent and vice versa (see the realization of the standard attributes in the packages *BinMDataStd*, for example). Add package method *AddDrivers*, which adds your class to a driver table (see below).
1. Create a new package with name <i> Bin[package name] </i> (for example *BinMyAttributePackage*) containing a class *BinMyAttributePackage_MyAttributeDriver*. The new class inherits *BinMDF_ADriver* class and contains the translation functionality: from transient to persistent and vice versa (see the realization of the standard attributes in the packages *BinMDataStd*, for example). Add package method *AddDrivers*, which adds your class to a driver table.
2. Create a new package (or do it in the current one) with two package methods:
* Factory, which loads the document storage and retrieval drivers; and
* AttributeDrivers, which calls the methods AddDrivers for all packages responsible for persistence of the document.
@ -439,23 +439,23 @@ Let’s study the implementation of the same data type in both ways by the examp
1. The first way: creation of a new attribute. The implementation of the transformation by creation of a new attribute is represented in the <a href="#occt_ocaf_11">Samples</a>.
2. The second way: creation of a new data type by means of combination of standard attributes. Depending on the type of transformation it may be kept in data framework by different standard attributes. For example, a translation is defined by two points. Therefore the data tree for translation looks like this:
* Type of transformation (gp_Translation) as TDataStd_Integer;
* First point as TDataStd_RealArray (three values: X1, Y1 and Z1);
* Second point as TDataStd_RealArray (three values: X2, Y2 and Z2).
* Type of transformation <i>(gp_Translation)</i> as *TDataStd_Integer*;
* First point as *TDataStd_RealArray* (three values: X1, Y1 and Z1);
* Second point as *TDataStd_RealArray* (three values: X2, Y2 and Z2).
@image html /user_guides/ocaf/images/ocaf_image010.png "Data tree for translation"
@image latex /user_guides/ocaf/images/ocaf_image010.png "Data tree for translation"
If the type of transformation is changed to rotation, the data tree looks like this:
* Type of transformation (gp_Rotation) as TDataStd_Integer;
* Point of axis of rotation as TDataStd_RealArray (three values: X, Y and Z);
* Axis of rotation as TDataStd_RealArray (three values: DX, DY and DZ);
* Angle of rotation as TDataStd_Real.
* Type of transformation <i>(gp_Rotation)</i> as *TDataStd_Integer*;
* Point of axis of rotation as *TDataStd_RealArray* (three values: X, Y and Z);
* Axis of rotation as *TDataStd_RealArray* (three values: DX, DY and DZ);
* Angle of rotation as *TDataStd_Real*.
@image html /user_guides/ocaf/images/ocaf_image011.png "Data tree for rotation"
@image latex /user_guides/ocaf/images/ocaf_image011.png "Data tree for rotation"
The attribute TDataStd_UAttribute with the chosen unique GUID identifies the data type. The interface class initialized by the label of this attribute allows access to the data container (type of transformation and the data of transformation according to the type).
The attribute *TDataStd_UAttribute* with the chosen unique GUID identifies the data type. The interface class initialized by the label of this attribute allows access to the data container (type of transformation and the data of transformation according to the type).
@section occt_ocaf_4_ Standard Document Services
@ -464,7 +464,7 @@ The attribute TDataStd_UAttribute with the chosen unique GUID identifies the dat
Standard documents offer ready-to-use documents containing a TDF-based data framework. Each document can contain only one framework.
The documents themselves are contained in the instantiation of a class inheriting from TDocStd_Application. This application manages the creation, storage and retrieval of documents.
The documents themselves are contained in the instantiation of a class inheriting from *TDocStd_Application*. This application manages the creation, storage and retrieval of documents.
You can implement undo and redo in your document, and refer from the data framework of one document to that of another one. This is done by means of external link attributes, which store the path and the entry of external links.
@ -577,21 +577,58 @@ setenv CSF_NewFormatDefaults MyApplicationPath/MyResources
Once these steps are taken you may run your application, create documents and Save/Open them. These resource files already exist in the OCAF (format "Standard").
If you use your specific attributes from packages, for example, P-, M- and TMyAttributePackage, see "Specific attribute creation" on page 20; you must take some additional steps for the new plugin implementation:
If you use your specific attributes from packages, for example, <i>P-, M-</i> and *TMyAttributePackage* (see @ref occt_ocaf_3_4_6 "Specific attribute creation") you must take some additional steps for the new plugin implementation:
1. Add our "P" package to the standard schema. You can get an already existing (in Open CASCADE Technology sources) schema from StdSchema unit and add your package string to the cdl-file: "package PMyAttributePackage".
2. Next step consists of implementation of an executable, which will connect our documents to our application and open/save them. Copy the package PAppStdPlugin and change its name to MyTheBestApplicationPlugin. In the PLUGIN macros type the name of your factory which will be defined in the next step.
3. Factory is a method, which returns drivers (standard drivers and our defined drivers from the "M" package) by a GUID. Copy the package where the standard factory is defined (it is PAppStd in the OCAF sources). Change its name to MyTheBestSchemaLocation. The Factory() method of the PappStd package checks the GUID set as its argument and returns the corresponding table of drivers. Set two new GUIDs for your determined storage and retrieval drivers. Append two "if" declarations inside the Factory() method which should check whether the set GUID coincides with GUIDs defined by the Factory() method as far as our storage and retrieval drivers are concerned. If the GUID coincides with one of them, the method should return a table of storage or retrieval drivers respectively.
4. Recompile all. Add the strings with GUIDs – in accordance with your plugin library GUID - to the "Plugin" file.
1. Add our *P* package to the standard schema. You can get an already existing (in Open CASCADE Technology sources) schema from *StdSchema* unit and add your package string to the cdl-file: package *PMyAttributePackage*.
2. The next step consists in the implementation of an executable, which will connect our documents to our application and open/save them. Copy the package *PAppStdPlugin* and change its name to *MyTheBestApplicationPlugin*. In the *PLUGIN* macros type the name of your factory, which will be defined at the next step.
3. *Factory* is a method, which returns drivers (standard drivers and our defined drivers from the *M* package) by a GUID. Copy the package to the location, where the standard factory is defined (it is PAppStd in the OCAF sources). Change its name to *MyTheBestSchemaLocation*. The *Factory()* method of the *PappStd* package checks the GUID set as its argument and returns the corresponding table of drivers. Set two new GUIDs for your determined storage and retrieval drivers. Append two *if* declarations inside the *Factory()* method, which should check whether the set GUID coincides with GUIDs defined by the *Factory()* method as far as our storage and retrieval drivers are concerned. If the GUID coincides with one of them, the method should return a table of storage or retrieval drivers respectively.
4. Recompile all and add the strings with GUIDs to the *Plugin* file in accordance with your plugin library GUID.
@subsubsection occt_ocaf_4_3_4 Opening the document from a file
To open the document from a file where it has been previously saved, you use TDocStd_Application::Open as in the example below. The arguments are the path of the file and the document saved in this file.
To open the document from a file where it has been previously saved, you can use *TDocStd_Application::Open* as in the example below. The arguments are the path of the file and the document saved in this file.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.cpp}
app->Open("/tmp/example.caf", doc);
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@subsubsection occt_ocaf_4_3_5 Cutting, copying and pasting inside a document
To cut, copy and paste inside a document, use the class *TDF_CopyLabel*.
In fact, you must define a *Label*, which contains the temporary value of a cut or
copy operation (say, in <i> Lab_Clipboard</i>). You must also define two other labels:
* The data container (e.g. <i> Lab_source</i>)
* The destination of the copy (e.g. <i> Lab_ Target</i> )
~~~~
Copy = copy (Lab_Source => Lab_Clipboard)
Cut = copy + Lab_Source.ForgetAll() // command clear the contents of LabelSource.
Paste = copy (Lab_Clipboard => Lab_target)
~~~~
So we need a tool to copy all (or a part) of the content of a label and its sub-label,
to another place defined by a label.
~~~~
TDF_CopyLabel aCopy;
TDF_IDFilter aFilter (Standard_False);
//Don't copy TDataStd_TreeNode attribute
aFilter.Ignore(TDataStd_TreeNode::GetDefaultTreeID());
aCopy.Load(aSource, aTarget); aCopy.UseFilter(aFilter); aCopy.Perform();
// copy the data structure to clipboard
return aCopy.IsDone(); }
~~~~
The filter is used to forbid copying a specified type of attribute.
You can also have a look at the class *TDF_Closure*, which can be useful to determine the dependencies of the part you want to cut from the document.
@subsection occt_ocaf_4_4 External Links
External links refer from one document to another. They allow you to update the copy of data framework later on.
@ -605,7 +642,7 @@ Note that documents can be copied with or without a possibility of updating an e
#### With the possibility of updating it later
To copy a document with a possibility of updating it later, you use TDocStd_XLinkTool::CopyWithLink.
To copy a document with a possibility of updating it later, you use *TDocStd_XLinkTool::CopyWithLink*.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.cpp}
Handle(TDocStd_Document) doc1;
@ -620,7 +657,7 @@ XLinkTool.CopyWithLink(target,source);
Now the target document has a copy of the source document. The copy also has a link in order to update the content of the copy if the original changes.
In the example below, something has changed in the source document. As a result, you need to update the copy in the target document. This copy is passed to TDocStd_XLinkTool::UpdateLink as the argument *target*.
In the example below, something has changed in the source document. As a result, you need to update the copy in the target document. This copy is passed to *TDocStd_XLinkTool::UpdateLink* as the argument *target*.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.cpp}
XLinkTool.UpdateLink(target);
@ -628,7 +665,7 @@ XLinkTool.UpdateLink(target);
#### Without any link between the copy and the original
You can also create a copy of the document with no link between the original and the copy. The syntax to use this option is TDocStd_XLinkTool::Copy; the copied document is again represented by the argument *target*, and the original – by *source.*
You can also create a copy of the document with no link between the original and the copy. The syntax to use this option is *TDocStd_XLinkTool::Copy*. The copied document is again represented by the argument *target*, and the original – by *source.*
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.cpp}
XLinkTool.Copy(target, source);
@ -639,24 +676,27 @@ XLinkTool.Copy(target, source);
@section occt_ocaf_5_ OCAF Shape Attributes
@subsection occt_ocaf_5_1 Overview
OCAF shape attributes are used for topology objects and their evolution access. All topological objects are stored in one TNaming_UsedShapes attribute at the root label of the data framework. This attribute contains a map with all topological shapes used in a given document.
A topological attribute can be seen as a hook into the topological structure. It is possible to attach data to define references to it.
The user can add the TNaming_NamedShape attribute to other labels. This attribute contains references (hooks) to shapes from the TNaming_UsedShapes attribute and an evolution of these shapes. The TNaming_NamedShape attribute contains a set of pairs of hooks: to the *Old* shape and to a *New* shape (see the following figure). It allows not only to get the topological shapes by the labels, but also to trace the evolution of the shapes and to correctly update dependent shapes by the changed one.
OCAF shape attributes are used for topology objects and their evolution access. All topological objects are stored in one *TNaming_UsedShapes* attribute at the root label of the data framework. This attribute contains a map with all topological shapes used in a given document.
The user can add the *TNaming_NamedShape* attribute to other labels. This attribute contains references (hooks) to shapes from the *TNaming_UsedShapes* attribute and an evolution of these shapes. The *TNaming_NamedShape* attribute contains a set of pairs of hooks: to the *Old* shape and to a *New* shape (see the following figure). It allows not only to get the topological shapes by the labels, but also to trace the evolution of the shapes and to correctly update dependent shapes by the changed one.
If a shape is newly created, then the old shape of a corresponding named shape is an empty shape. If a shape is deleted, then the new shape in this named shape is empty.
@image html /user_guides/ocaf/images/ocaf_image013.png
@image latex /user_guides/ocaf/images/ocaf_image013.png
### Shape attributes in data framework.
Different algorithms may dispose sub-shapes of the result shape at the individual labels depending on whether it is necessary to do so:
* 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 a separate label (usually to a sub-label of the result shape label) with all attributes of this sub-shape.
* If the topological naming algorithm is needed, a necessary and sufficient set of sub-shapes is placed to child labels of the result shape label. As usual, for a basic solid and closed shells, all faces of the shape are disposed.
*TNaming_NamedShape* may contain a few pairs of hooks with the same evolution. In this case the topology shape, which belongs to the named shape is a compound of new shapes.
TNaming_NamedShape may contain a few pairs of hooks with the same evolution. In this case the topology shape, which belongs to the named shape is a compound of new shapes.
Consider the following example. Two boxes (solids) are fused into one solid (the result one). Initially each box was placed to the result label as a named shape, which has evolution PRIMITIVE and refers to the corresponding shape of the TNaming_UsedShapes map. The box result label has a material attribute and six child labels containing named shapes of Box faces.
Consider the following example. Two boxes (solids) are fused into one solid (the result one). Initially each box was placed to the result label as a named shape, which has evolution PRIMITIVE and refers to the corresponding shape of the *TNaming_UsedShapes* map. The box result label has a material attribute and six child labels containing named shapes of Box faces.
@image html /user_guides/ocaf/images/ocaf_image014.png "Resulting box"
@image latex /user_guides/ocaf/images/ocaf_image014.png "Resulting box"
@ -670,8 +710,8 @@ Named shapes, which contain information about modified faces, belong to the fuse
This is necessary and sufficient information for the functionality of the right naming mechanism: any sub-shape of the result can be identified unambiguously by name type and set of labels, which contain named shapes:
* face F1’ as a modification of F11 face
* face F1’’ as generation of F12 face
* face F1’ as a modification of face F11
* face F1’’ as generation of face F12
* edges as an intersection of two contiguous faces
* vertices as an intersection of three contiguous faces
@ -684,19 +724,18 @@ After any modification of source boxes the application must automatically rebuil
When using TNaming_NamedShape to create attributes, the following fields of an attribute are filled:
* A list of shapes called the "old" and the "new" shapes A new shape is recomputed as the value of the named shape. The meaning of this pair depends on the type of evolution.
* The type of evolution: a term of the TNaming_Evolution enumeration:
* PRIMITIVE – newly created topology, with no previous history
* GENERATED – as usual, this evolution of a named shape means, that the new shape is created from a low-level old shape ( a prism face from an edge, for example )
* MODIFY – the new shape is a modified old shape
* DELETE – the new shape is empty; the named shape with this evolution just indicates that the old shape topology is deleted from the model
* SELECTED – a named shape with this evolution has no effect on the history of the topology; it is
used for the selected shapes that are placed to the separate label
* The type of evolution, which is a term of the *TNaming_Evolution* enumeration used for the selected shapes that are placed to the separate label:
* PRIMITIVE – newly created topology, with no previous history;
* GENERATED – as usual, this evolution of a named shape means, that the new shape is created from a low-level old shape ( a prism face from an edge, for example );
* MODIFY – the new shape is a modified old shape;
* DELETE – the new shape is empty; the named shape with this evolution just indicates that the old shape topology is deleted from the model;
* SELECTED – a named shape with this evolution has no effect on the history of the topology.
Only pairs of shapes with equal evolution can be stored in one named shape.
@subsubsection occt_ocaf_5_2_2 Using naming resources
The class TNaming_Builder allows you to create a named shape attribute. It has a label of a future attribute as an argument of the constructor. Respective methods are used for the evolution and setting of shape pairs. If for the same TNaming_Builder object a lot of pairs of shapes with the same evolution are given, then these pairs would be placed in the resulting named shape. After the creation of a new object of the TNaming_Builder class, an empty named shape is created at the given label.
The class *TNaming_Builder* allows you to create a named shape attribute. It has a label of a future attribute as an argument of the constructor. Respective methods are used for the evolution and setting of shape pairs. If for the same TNaming_Builder object a lot of pairs of shapes with the same evolution are given, then these pairs would be placed in the resulting named shape. After the creation of a new object of the TNaming_Builder class, an empty named shape is created at the given label.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.cpp}
// a new empty named shape is created at "label"
@ -710,15 +749,14 @@ Handle(TNaming_NamedShape) ns = builder.NamedShape();
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@subsubsection occt_ocaf_5_2_3 Reading the contents of a named shape attribute
You can use TNaming_NamedShape class to get evolution of this named shape (method TNaming_NamedShape::Evolution()) and "value" of the named shape – compound of new shapes of all pairs of this named shape (method TNaming_NamedShape::Get()).
You can use the method <i>TNaming_NamedShape::Evolution()</i> to get the evolution of this named shape and the method <i>TNaming_NamedShape::Get()</i> to get a compound of new shapes of all pairs of this named shape.
More detailed information about the contents of the named shape or about the modification history of a topology can be obtained with the following:
* TNaming_Tool provides a common high-level functionality for access to the named shapes contents:
* GetShape(Handle(TNaming_NamedShape)) method returns a compound of new shapes of the given named shape
* CurrentShape(Handle(TNaming_NamedShape)) method returns a compound of the shapes – last modifications ( latest versions ) of the shapes from the given named shape
* NamedShape(TopoDS_Shape,TDF_Label) method returns a named shape, which contains a given shape as a new shape. Given label is any label from the data framework – it just gives access to it
* TNaming_Iterator given access to the named shape hooks pairs.
* *TNaming_Tool* provides a common high-level functionality for access to the named shapes contents:
* The method <i>GetShape(Handle(TNaming_NamedShape)) </i> returns a compound of new shapes of the given named shape;
* The method <i>CurrentShape(Handle(TNaming_NamedShape))</i> returns a compound of the shapes, which are latest versions of the shapes from the given named shape;
* The method <i>NamedShape(TopoDS_Shape,TDF_Label) </i> returns a named shape, which contains a given shape as a new shape. A given label is any label from the data framework – it just gives access to it.
* *TNaming_Iterator* gives access to the named shape and hooks pairs.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.cpp}
// create an iterator for a named shape
@ -739,7 +777,7 @@ iter.Next();
@subsubsection occt_ocaf_5_2_4 Selection Mechanism
One of user interfaces for topological naming resources is the TNaming_Selector class. You can use this class to:
One of user interfaces for topological naming resources is the *TNaming_Selector* class. You can use this class to:
* Store a selected shape on a label
* Access the named shape
@ -747,13 +785,13 @@ One of user interfaces for topological naming resources is the TNaming_Selector
Selector places a new named shape with evolution SELECTED to the given label. By the given context shape (main shape, which contains a selected sub-shape), its evolution and naming structure the selector creates a "name" of the selected shape – unique description how to find a selected topology.
After any modification of a context shape and updating of the corresponding naming structure, you must call the TNaming_Selector::Solve method. If the naming structure is right, then the selector automatically updates the selected shape in the corresponding named shape, else it fails.
After any modification of a context shape and updating of the corresponding naming structure, you must call the method *TNaming_Selector::Solve*. If the naming structure is correct, the selector automatically updates the selected shape in the corresponding named shape, else it fails.
@subsubsection occt_ocaf_5_2_5 Exploring shape evolution
The class TNaming_Tool provides a toolkit to read current data contained in the attribute.
The class *TNaming_Tool* provides a toolkit to read current data contained in the attribute.
If you need to create a topological attribute for existing data, use the method NamedShape.
If you need to create a topological attribute for existing data, use the method *NamedShape*.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.cpp}
class MyPkg_MyClass
@ -773,65 +811,62 @@ Standard_Boolean CafTest_MyClass::SameEdge (const Handle(CafTest_Line)& L1, cons
@subsection occt_ocaf_6_1 Overview
There are several ready-to-use attributes, which allow creating and modifying attributes for many basic data types. They are available in the packages TDataStd, TDataXtd and TDF. Each attribute belongs to one of four types:
Standard attributes are ready-to-use attributes, which allow creating and modifying attributes for many basic data types. They are available in the packages *TDataStd, TDataXtd* and *TDF*. Each attribute belongs to one of four types:
* Geometric attributes
* General attributes
* Relationship attributes
* Auxiliary attributes
* Geometric attributes;
* General attributes;
* Relationship attributes;
* Auxiliary attributes.
### Geometric attributes
* Axis – simply identifies, that the concerned TNaming_NamedShape attribute with an axis shape inside belongs to the same label
* Constraint – contains information about a constraint between geometries: used geometry attributes, type, value (if exists), plane (if exists), "is reversed", "is inverted" and "is verified" flags
* Geometry – simply identifies, that the concerned TNaming_NamedShape attribute with a specified-type geometry belongs to the same label
* Plane – simply identifies, that the concerned TNaming_NamedShape attribute with a plane shape inside belongs to the same label
* Point – simply identifies, that the concerned TNaming_NamedShape attribute with a point shape inside belongs to the same label
* Shape – simply identifies, that the concerned TNaming_NamedShape attribute belongs to the same label
* PatternStd – identifies one of five available pattern models (linear, circular, rectangular, circular rectangular and mirror)
* Position – identifies the position in 3d global space
* **Axis** – simply identifies, that the concerned *TNaming_NamedShape* attribute with an axis shape inside belongs to the same label;
* **Constraint** – contains information about a constraint between geometries: used geometry attributes, type, value (if exists), plane (if exists), "is reversed", "is inverted" and "is verified" flags;
* **Geometry** – simply identifies, that the concerned *TNaming_NamedShape* attribute with a specified-type geometry belongs to the same label;
* **Plane** – simply identifies, that the concerned *TNaming_NamedShape* attribute with a plane shape inside belongs to the same label;
* **Point** – simply identifies, that the concerned *TNaming_NamedShape* attribute with a point shape inside belongs to the same label;
* **Shape** – simply identifies, that the concerned *TNaming_NamedShape* attribute belongs to the same label;
* **PatternStd** – identifies one of five available pattern models (linear, circular, rectangular, circular rectangular and mirror);
* **Position** – identifies the position in 3d global space.
### General attributes
* AsciiString – contains AsciiString value
* BooleanArray – contains an array of Boolean
* BooleanList – contains a list of Boolean
* ByteArray – contains an array of Byte (unsigned char) values
* Comment – contains a string – some comment for a given label (or attribute)
* Expression – contains an expression string and a list of used variables attributes
* ExtStringArray – contains an array of ExtendedString values
* ExtStringList – contains a list of ExtendedString values
* Integer – contains an integer value
* IntegerArray – contains an array of integer values
* IntegerList – contains a list of integer values
* IntPackedMap – contains a packed map of integers
* Name – contains a string – some name of a given label (or attribute)
* NamedData – may contain up to 6 of the following named data sets (vocabularies): DataMapOfStringInteger, DataMapOfStringReal, DataMapOfStringString, DataMapOfStringByte, DataMapOfStringHArray1OfInteger, DataMapOfStringHArray1OfReal
* NoteBook – contains a NoteBook object attribute
* Real – contains a real value
* RealArray – contains an array of real values
* RealList – contains a list of real values
* Relation – contains a relation string and a list of used variables attributes
* Tick – defines a boolean attribute
* Variable – simply identifies, that a variable belongs to this label; contains the "is constraint" flag and a string of used units ("mm", "m"...)
* UAttribute – attribute with a user-defined GUID. As a rule, this attribute is used as a marker, which is independent of attributes at the same label (note, that attributes with the same GUIDs can not belong to the same label)
* **AsciiString** – contains AsciiString value;
* **BooleanArray** – contains an array of Boolean;
* **BooleanList** – contains a list of Boolean;
* **ByteArray** – contains an array of Byte (unsigned char) values;
* **Comment** – contains a string – some comment for a given label (or attribute);
* **Expression** – contains an expression string and a list of used variables attributes;
* **ExtStringArray** – contains an array of *ExtendedString* values;
* **ExtStringList** – contains a list of *ExtendedString* values;
* **Integer** – contains an integer value;
* **IntegerArray** – contains an array of integer values;
* **IntegerList** – contains a list of integer values;
* **IntPackedMap** – contains a packed map of integers;
* **Name** – contains a string – some name of a given label (or attribute);
* **NamedData** – may contain up to 6 of the following named data sets (vocabularies): *DataMapOfStringInteger, DataMapOfStringReal, DataMapOfStringString, DataMapOfStringByte, DataMapOfStringHArray1OfInteger* or *DataMapOfStringHArray1OfReal*;
* **NoteBook** – contains a *NoteBook* object attribute;
* **Real** – contains a real value;
* **RealArray** – contains an array of real values;
* **RealList** – contains a list of real values;
* **Relation** – contains a relation string and a list of used variables attributes;
* **Tick** – defines a boolean attribute;
* **Variable** – simply identifies, that a variable belongs to this label; contains the flag *is constraint* and a string of used units ("mm", "m"...);
* **UAttribute** – attribute with a user-defined GUID. As a rule, this attribute is used as a marker, which is independent of attributes at the same label (note, that attributes with the same GUIDs can not belong to the same label).
### Relationship attributes
* Reference – contains reference to the label of its own data framework
* ReferenceArray – contains an array of references
* ReferenceList – contains a list of references
* TreeNode – this attribute allows to create an internal tree in the data framework; this tree consists of nodes with the specified tree ID; each node contains references to the father, previous brother, next brother, first child nodes and tree ID.
* **Reference** – contains reference to the label of its own data framework;
* **ReferenceArray** – contains an array of references;
* **ReferenceList** – contains a list of references;
* **TreeNode** – this attribute allows to create an internal tree in the data framework; this tree consists of nodes with the specified tree ID; each node contains references to the father, previous brother, next brother, first child nodes and tree ID.
### Auxiliary attributes
* Directory – hi-level tool attribute for sub-labels management
* TagSource – this attribute is used for creation of new children: it stores the tag of the last-created child of the label and gives access to the new child label creation functionality.
* **Directory** – high-level tool attribute for sub-labels management;
* **TagSource** – this attribute is used for creation of new children: it stores the tag of the last-created child of the label and gives access to the new child label creation functionality.
All of these attributes inherit class TDF_Attribute, so, each attribute has its own GUID and standard methods for attribute creation, manipulation, getting access to the data framework.
All attributes inherit class *TDF_Attribute*, so, each attribute has its own GUID and standard methods for attribute creation, manipulation, getting access to the data framework.
@subsection occt_ocaf_6_2 Services common to all attributes
@ -839,9 +874,15 @@ All of these attributes inherit class TDF_Attribute, so, each attribute has its
@subsubsection occt_ocaf_6_2_1 Accessing GUIDs
To access the GUID of an attribute, you can use two methods:
* Method *GetID* is the static method of a class. It returns the GUID of any attribute, which is an object of a specified class (for example, TDataStd_Integer returns the GUID of an integer attribute). Only two classes from the list of standard attributes do not support these methods: TDataStd_TreeNode and TDataStd_Uattribute, because the GUIDs of these attributes are variable.
* Method *GetID* is the static method of a class. It returns the GUID of any attribute, which is an object of a specified class (for example, *TDataStd_Integer* returns the GUID of an integer attribute). Only two classes from the list of standard attributes do not support these methods: *TDataStd_TreeNode* and *TDataStd_Uattribute*, because the GUIDs of these attributes are variable.
* Method *ID* is the method of an object of an attribute class. It returns the GUID of this attribute. Absolutely all attributes have this method: only by this identifier you can discern the type of an attribute.
To find an attribute attached to a specific label, you use the GUID of the attribute type you are looking for. This information can be found using the method <i> GetID</i> and the method <i> Find</i> for the label as follows:
~~~~
Standard_GUID anID = MyAttributeClass::GetID();
Standard_Boolean HasAttribute = aLabel.Find(anID,anAttribute);
~~~~
@subsubsection occt_ocaf_6_2_2 Conventional Interface of Standard Attributes
@ -855,15 +896,15 @@ It is usual to create standard named methods for the attributes:
@subsection occt_ocaf_7_1 Overview
Standard visualization attributes implement the Application Interactive Services (see Open CASCADE Technology Visualization User’s Guide) in the context of Open CASCADE Technology Application Framework. Standard visualization attributes are AISViewer and Presentation and belong to the TPrsStd package.
Standard visualization attributes implement the Application Interactive Services (see @ref occt_user_guides__visualization "Visualization User's Guide"). in the context of Open CASCADE Technology Application Framework. Standard visualization attributes are AISViewer and Presentation and belong to the TPrsStd package.
@subsection occt_ocaf_7_2 Services provided
@subsubsection occt_ocaf_7_2_1 Defining an interactive viewer attribute
The class TPrsStd_AISViewer allows you to define an interactive viewer attribute. There may be only one such attribute per one data framework and it is always placed to the root label. So, it could be set or found by any label ("access label") of the data framework. Nevertheless the default architecture can be easily extended and the user can manage several Viewers per one framework by himself.
The class *TPrsStd_AISViewer* allows you to define an interactive viewer attribute. There may be only one such attribute per one data framework and it is always placed to the root label. So, it could be set or found by any label ("access label") of the data framework. Nevertheless the default architecture can be easily extended and the user can manage several Viewers per one framework by himself.
To initialize the AIS viewer as in the example below, use method Find.
To initialize the AIS viewer as in the example below, use method *Find*.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.cpp}
// "access" is any label of the data framework
@ -872,13 +913,13 @@ Handle(TPrsStd_AISViewer) viewer = TPrsStd_AISViewer::Find(access)
@subsection occt_ocaf_7_2_2 Defining a presentation attribute
The class TPrsStd_AISPresentation allows you to define the visual presentation of document labels contents. In addition to various visual fields (color, material, transparency, "isDisplayed", etc.), this attribute contains its driver GUID. This GUID defines the functionality, which will update the presentation every time when needed.
The class *TPrsStd_AISPresentation* allows you to define the visual presentation of document labels contents. In addition to various visual fields (color, material, transparency, *isDisplayed*, etc.), this attribute contains its driver GUID. This GUID defines the functionality, which will update the presentation every time when needed.
@subsubsection occt_ocaf_7_2_3 Creating your own driver
The abstract class TPrsStd_Driver allows you to define your own driver classes. Simply redefine the Update method in your new class, which will rebuild the presentation.
If your driver is placed to the driver table with the unique driver GUID, then every time the viewer updates presentations with a GUID identical to your driver’s GUID, the Update method of your driver for these presentations must be called:
If your driver is placed to the driver table with the unique driver GUID, then every time the viewer updates presentations with a GUID identical to your driver’s GUID, the *Update* method of your driver for these presentations must be called:
@image html /user_guides/ocaf/images/ocaf_image016.png
@image latex /user_guides/ocaf/images/ocaf_image016.png
@ -886,9 +927,9 @@ As usual, the GUID of a driver and the GUID of a displayed attribute are the sam
@subsubsection occt_ocaf_7_2_4 Using a container for drivers
You frequently need a container for different presentation drivers. The class TPrsStd_DriverTable provides this service. You can add a driver to the table, see if one is successfully added, and fill it with standard drivers.
You frequently need a container for different presentation drivers. The class *TPrsStd_DriverTable* provides this service. You can add a driver to the table, see if one is successfully added, and fill it with standard drivers.
To fill a driver table with standard drivers, first initialize the AIS viewer as in the example above, and then pass the return value of the method InitStandardDrivers to the driver table returned by the method Get. Then attach a TNaming_NamedShape to a label and set the named shape in the presentation attribute using the method Set. Then attach the presentation attribute to the named shape attribute, and the AIS_InteractiveObject, which the presentation attribute contains, will initialize its drivers for the named shape. This can be seen in the example below.
To fill a driver table with standard drivers, first initialize the AIS viewer as in the example above, and then pass the return value of the method *InitStandardDrivers* to the driver table returned by the method *Get*. Then attach a *TNaming_NamedShape* to a label and set the named shape in the presentation attribute using the method *Set*. Then attach the presentation attribute to the named shape attribute, and the *AIS_InteractiveObject*, which the presentation attribute contains, will initialize its drivers for the named shape. This can be seen in the example below.
**Example**
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.cpp}
@ -906,21 +947,23 @@ When you edit any application model, you have to regenerate the model by propaga
Take, for example, the case of a modeling sequence made up of a box with the application of a fillet on one of its edges. If you change the height of the box, the fillet will need to be regenerated as well.
See the white paper @ref occt_user_guides__ocaf_functionmechanism_wp "Application Framework Function Mechanism" for more information.
@subsection occt_ocaf_8_1 Finding functions, their owners and roots
The class TFunction_Function is an attribute, which stores a link to a function driver in the data framework. In the static table TFunction_DriverTable correspondence links between function attributes and drivers are stored.
The class *TFunction_Function* is an attribute, which stores a link to a function driver in the data framework. In the static table *TFunction_DriverTable* correspondence links between function attributes and drivers are stored.
You can write your function attribute, a driver for such attribute (which updates the function result in accordance to a given map of changed labels), and set your driver with the GUID to the driver table.
You can write your function attribute, a driver for such attribute, which updates the function result in accordance to a given map of changed labels, and set your driver with the GUID to the driver table.
Then the solver algorithm of a data model can find the Function attribute on a corresponding label and call the Execute driver method to update the result of the function.
Then the solver algorithm of a data model can find the *Function* attribute on a corresponding label and call the *Execute* driver method to update the result of the function.
@subsection occt_ocaf_8_2 Storing and accessing information about function status
For updating algorithm optimization, each function driver has access to the TFunction_Logbook object that is a container for a set of touched, impacted and valid labels. Using this object a driver gets to know which arguments of the function were modified.
For updating algorithm optimization, each function driver has access to the *TFunction_Logbook* object that is a container for a set of touched, impacted and valid labels. Using this object a driver gets to know which arguments of the function were modified.
@subsection occt_ocaf_8_3 Propagating modifications
An application must implement its functions, function drivers and the common solver for parametric model creation. For example, check the following model (see the following illustration):
An application must implement its functions, function drivers and the common solver for parametric model creation. For example, check the following model:
@image html /user_guides/ocaf/images/ocaf_image017.png
@image latex /user_guides/ocaf/images/ocaf_image017.png
@ -948,29 +991,29 @@ Writing and reading XML files in OCCT is provided by LDOM package, which constit
of XML OCAF persistence, which is the optional component provided on top of Open CASCADE Technology.
The Light DOM (LDOM) package contains classes maintaining a data structure whose main principles conform to W3C DOM Level 1 Recommendations. The purpose of these classes as required by XML OCAF persistence schema is to:
* Maintain a tree structure of objects in memory representing the XML document. The root of the structure is an object of the LDOM_Document type. This object contains all the data corresponding to a given XML document and contains one object of the LDOM_Element type named "document element". The document element contains other LDOM_Element objects forming a tree. Other types of nodes (LDOM_Attr, LDOM_Text, LDOM_Comment, LDOM_CDATASection) represent the corresponding XML types and serve as branches of the tree of elements.
* Provide class LDOM_Parser to read XML files and convert them to LDOM_Document objects.
* Provide class LDOM_XmlWriter to convert LDOM_Document to a character stream in XML format and store it in file.
* Maintain a tree structure of objects in memory representing the XML document. The root of the structure is an object of the *LDOM_Document* type. This object contains all the data corresponding to a given XML document and contains one object of the *LDOM_Element* type named "document element". The document element contains other *LDOM_Element* objects forming a tree. Other types of nodes: *LDOM_Attr, LDOM_Text, LDOM_Comment* and *LDOM_CDATASection* - represent the corresponding XML types and serve as branches of the tree of elements.
* Provide class *LDOM_Parser* to read XML files and convert them to *LDOM_Document* objects.
* Provide class *LDOM_XmlWriter* to convert *LDOM_Document* to a character stream in XML format and store it in file.
This package covers the functionality provided by numerous products known as "DOM parsers". Unlike most of them, LDOM was specifically developed to meet the following requirements:
* To minimize the virtual memory allocated by DOM data structures. In average, the amount of memory of LDOM is the same as the XML file size (UTF-8).
* To minimize the time required for parsing and formatting XML, as well as for access to DOM data structures.
Both these requirements are important when XML files are processed by applications if these files are relatively large (occupying megabytes and even hundreds of megabytes). To meet the requirements, some limitations were imposed on the DOM Level 1 specification; these limitations are insignificant in applications like OCAF. Some of these limitations can be overridden in the course of future developments. The main limitations are:
* No Unicode support as well as various other encodings; only ASCII strings are used in DOM/XML. Note: There is a data type TCollection_ExtendedString for wide character data. This type is supported by LDOM_String as a sequence of numbers.
* Some superfluous methods are deleted: getPreviousSibling, getParentNode, etc.
* No Unicode support as well as various other encodings; only ASCII strings are used in DOM/XML. Note: There is a data type *TCollection_ExtendedString* for wide character data. This type is supported by *LDOM_String* as a sequence of numbers.
* Some superfluous methods are deleted: *getPreviousSibling, getParentNode,* etc.
* No resolution of XML Entities of any kind
* No support for DTD: the parser just checks for observance of general XML rules and never validates documents.
* Only 5 available types of DOM nodes: LDOM_Element, LDOM_Attr, LDOM_Text, LDOM_Comment, LDOM_CDATASection.
* Only 5 available types of DOM nodes: *LDOM_Element, LDOM_Attr, LDOM_Text, LDOM_Comment* and *LDOM_CDATASection*.
* No support of Namespaces; prefixed names are used instead of qualified names.
* No support of the interface DOMException (no exception when attempting to remove a non-existing node).
* No support of the interface *DOMException* (no exception when attempting to remove a non-existing node).
LDOM is dependent on Kernel OCCT classes only. Therefore, it can be used outside OCAF persistence in various algorithms where DOM/XML support may be required.
@subsection occt_ocaf_9_1 Document Drivers
The drivers for document storage and retrieval manage conversion between a transient OCAF
Document in memory and its persistent reflection in a container (disk, memory, network ...). For XML Persistence, they are defined in the package XmlDrivers.
Document in memory and its persistent reflection in a container (disk, memory, network). For XML Persistence, they are defined in the package XmlDrivers.
The main methods (entry points) of these drivers are:
* *Write()* - for a storage driver;
@ -1089,15 +1132,14 @@ Both the XML format and the XML OCAF persistence code are extensible in the sens
* **Child** - a label created from another label, which by definition, is the father label.
* **Compound document** - a set of interdependent documents, linked to each other by means of external references. These references provide the associativity of data.
* **Data framework** - a tree-like data structure which in OCAF, is a tree of labels with data attached to them in the form of attributes. This tree of labels is accessible through the services of the *TDocStd_Document* class.
* *Document* - a container for a data framework which grants access to the data, and is, in its turn, contained by an application. A document also allows you to:
* **Document** - a container for a data framework which grants access to the data, and is, in its turn, contained by an application. A document also allows you to:
* Manage modifications, providing Undo and Redo functions
* Manage command transactions
* Update external links
* Manage save and restore options
* Store the names of software extensions.
* **Driver** - an abstract class, which defines the communications protocol with a system.
* **Entry** - an ASCII character string containing the tag list of a label.
* **Entry** - an ASCII character string containing the tag list of a label. For example:
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.cpp}
0:3:24:7:2:7
@ -1113,7 +1155,7 @@ To store these references properly, a label must also contain an external link a
In C++, the application behavior is implemented in virtual functions redefined in these derived classes. This is known as overriding.
* **GUID** - Global Universal ID. A string of 37 characters intended to uniquely identify an object.
* **GUID** - Global Universal ID. A string of 37 characters intended to uniquely identify an object. For example:
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.cpp}
2a96b602-ec8b-11d0-bee7-080009dc3333

353
dox/user_guides/ocaf_wp/ocaf_wp.md
View File

@ -25,6 +25,15 @@ OCAF White-Paper {#occt_user_guides__ocaf_wp}
By providing architectural guidance and ready-to-use solutions to these issues,
OCAF helps you to develop your application significantly faster: you concentrate on the application's functionality.
As you use the architecture provided by OCAF, the design of your application is made easy: as the application developer you can concentrate on the functionality instead of the underlying mechanisms required to support it.
Also, thanks to the coupling with the other Open CASCADE Technology modules,
your application can rapidly be prototyped. In addition, the final application
can be developed by industrializing the prototype — you don't need to restart the development from scratch.
Last but not least, you base your application on an Open Source component:
this guarantees the long-term usefulness of your development.
@subsection ocaf_wp_1_2 Overview of the Architecture
@ -73,7 +82,7 @@ OCAF uses other modules of Open CASCADE Technology — the Shape attribute is im
If you need application specific data not provided with OCAF, for example,
to incorporate a finite element model in the data structure,
you define a new attribute class containing the mesh,
and you include its persistent homolog in a new file format.
and you include its persistent homologue in a new file format.
Once you have implemented the commands which create and modify the data structure
according to your specification, OCAF provides you, without any additional programming:
@ -91,19 +100,99 @@ OCAF uses other modules of Open CASCADE Technology — the Shape attribute is im
You can also implement the user interface in the Java language using
the Swing-based Java Application Desktop component (JAD) provided with OCAF.
@subsection ocaf_wp_1_4 Benefits of OCAF
@subsection ocaf_wp_1_4 An example of OCAF usage
As you use the architecture provided by OCAF, the design of your application is made easy:
the application developer concentrates on the functionality
instead of the underlying mechanisms required to support this functionality.
To create a useful OCAF-based application, it is necessary to redefine two deferred methods: <i> Formats</i> and <i> ResourcesName</i>
In the <i> Formats </i> method, add the format of the documents, which need to be read by the application and may have been built in other applications.
For example:
~~~~
void myApplication::Formats(TColStd_SequenceOfExtendedString& Formats)
{
Formats.Append(TCollection_ExtendedString ("OCAF-myApplication"));
}
~~~~
In the <i> ResourcesName</i> method, you only define the name of the resource file. This
file contains several definitions for the saving and opening mechanisms associated
with each format and calling of the plug-in file.
~~~~
Standard_CString myApplication::ResourcesName()
{
return Standard_CString ("Resources");
}
~~~~
To obtain the saving and opening mechanisms, it is necessary to set two environment variables: <i> CSF_PluginDefaults</i>, which defines the path of the plug-in file, and <i> CSF_ResourcesDefault</i>, which defines the resource file:
~~~~
SetEnvironmentVariable ( "CSF_ResourcesDefaults",myDirectory);
SetEnvironmentVariable ( "CSF_PluginDefaults",myDirectory);
~~~~
The plugin and the resource files of the application will be located in <i> myDirector</i>.
The name of the plugin file must be <i>Plugin</i>.
### Resource File
The resource file describes the documents (type and extension) and
the type of data that the application can manipulate
by identifying the storage and retrieval drivers appropriate for this data.
Each driver is unique and identified by a GUID generated, for example, with the <i> uuidgen </i> tool in Windows.
Five drivers are required to use all standard attributes provided within OCAF:
* the schema driver (ad696002-5b34-11d1-b5ba-00a0c9064368)
* the document storage driver (ad696000-5b34-11d1-b5ba-00a0c9064368)
* the document retrieval driver (ad696001-5b34-11d1-b5ba-00a0c9064368)
* the attribute storage driver (47b0b826-d931-11d1-b5da-00a0c9064368)
* the attribute retrieval driver (47b0b827-d931-11d1-b5da-00a0c9064368)
These drivers are provided as plug-ins and are located in the <i> PappStdPlugin</i> library.
For example, this is a resource file, which declares a new model document OCAF-MyApplication:
~~~~
formatlist:OCAF-MyApplication
OCAF-MyApplication.Description: MyApplication Document Version 1.0
OCAF-MyApplication.FileExtension: sta
OCAF-MyApplication.StoragePlugin: ad696000-5b34-11d1-b5ba-00a0c9064368
OCAF-MyApplication.RetrievalPlugin: ad696001-5b34-11d1-b5ba-00a0c9064368
OCAF-MyApplicationSchema: ad696002-5b34-11d1-b5ba-00a0c9064368
OCAF-MyApplication.AttributeStoragePlugin: 47b0b826-d931-11d1-b5da-00a0c9064368
OCAF-MyApplication.AttributeRetrievalPlugin: 47b0b827-d931-11d1-b5da-00a0c9064368
~~~~
Also, thanks to the coupling with the other Open CASCADE Technology modules,
your application can rapidly be prototyped. In addition, the final application
can be developed by industrializing the prototype — you don't need to restart the development from scratch.
Last but not least, you base your application on an Open Source component:
this guarantees the long-term usefulness of your development.
### Plugin File
The plugin file describes the list of required plug-ins to run the application and the
libraries in which plug-ins are located.
You need at least the <i> FWOSPlugin</i> and the plug-in drivers to run an OCAF application.
The syntax of each item is <i> Identification.Location Library_Name, </i> where:
* Identification is GUID.
* Location defines the location of the Identification (where its definition is found).
* Library_Name is the name (and path to) the library, where the plug-in is located.
For example, this is a Plugin file:
~~~~
a148e300-5740-11d1-a904-080036aaa103.Location: FWOSPlugin
! base document drivers plugin
ad696000-5b34-11d1-b5ba-00a0c9064368.Location: PAppStdPlugin
ad696001-5b34-11d1-b5ba-00a0c9064368.Location: PAppStdPlugin
ad696002-5b34-11d1-b5ba-00a0c9064368.Location: PAppStdPlugin
47b0b826-d931-11d1-b5da-00a0c9064368.Location: PAppStdPlugin
47b0b827-d931-11d1-b5da-00a0c9064368.Location: PAppStdPlugin
~~~~
@section ocaf_wp_2 A Look Inside OCAF
@ -290,27 +379,17 @@ OCAF uses other modules of Open CASCADE Technology — the Shape attribute is im
@subsection ocaf_wp_2_3 Persistent Data Storage
In OCAF, persistence, that is, the mechanism used to save a document in a file,
is based on an explicit formal description of the data saved.
@subsubsection ocaf_wp_2_3_1 Introduction
In OCAF, persistence, that is, the mechanism used to save a document in a file, is based on an explicit formal description of the data saved.
When you open a document, the application reads the corresponding file
and first creates a memory representation of it.
This representation is then converted to the application data model —
the OCAF-based data structure the application operates on.
The file's memory representation consists of objects defined by classes known as persistent.
The persistent classes needed by an application to save its documents make the application's data schema.
This schema defines the way the data are organized in the file — the format of the data.
In other words, the file is simply an ASCII dump of the persistent data defined by the schema,
the persistent data being created from the application data model during the save process.
Only canonical information is saved. As a matter of fact,
the application data model usually contains additional data to optimize processing.
For example, the persistent Bézier curve is defined by its poles, whereas
its data model equivalent also contains coefficients used to compute a point at a given parameter.
The additional data is calculated when the document is opened.
The major advantages of this approach are the following:
When you open a document, the application reads the corresponding file and first creates a memory representation of it. This representation is then converted to the application data model — the OCAF-based data structure the application operates on. The file's memory representation consists of objects defined by classes known as persistent.
The persistent classes needed by an application to save its documents make the application's data schema. This schema defines the way the data are organized in the file — the format of the data. In other words, the file is simply an ASCII dump of the persistent data defined by the schema, the persistent data being created from the application data model during the save process.
Only canonical information is saved. As a matter of fact, the application data model usually contains additional data to optimize processing. For example, the persistent Bézier curve is defined by its poles, whereas its data model equivalent also contains coefficients used to compute a point at a given parameter. The additional data is calculated when the document is opened.
The major advantages of this approach are the following:
* Providing that the data format is published, files created by OCAF-based applications
can be read without needing a runtime of the application (openness)
* Although the persistence approach makes the data format more stable,
@ -329,4 +408,214 @@ Applications using compound documents extensively (saving data in many files lin
In order to ease the delegation of document management to a data management application, OCAF encapsulates the file management functions in a driver (the meta-data driver). You have to implement this driver for your application to communicate with the data management system of your choice.
@subsubsection ocaf_wp_2_3_2 Schemes of Persistence
There are three schemes of persistence, which you can use to store and retrieve OCAF data (documents):
* <i> Standard</i> persistence schema, compatible with previous OCAF applications
* <i> XmlOcaf</i> persistence, allowing the storage of all OCAF data in XML form
* <i> BinOcaf</i> persistence, allowing the storage of all OCAF data in binary format form
All schemes are independent of each other, but they guarantee that the standard OCAF
attributes stored and retrieved by one schema will be storable and retrievable by
the other. Therefore in any OCAF application you can use any persistence schema or
even all three of them. The choice is made depending on the *Format* string of stored OCAF documents
or automatically by the file header data - on retrieval.
Persistent data storage in OCAF using the <i> Standard</i> package is presented in:
* Basic Data Storage
* Persistent Collections
Persistent storage of shapes is presented in the following chapters:
* Persistent Geometry
* Persistent Topology
Finally, information about opening and saving persistent data is presented in Standard
Documents.
@subsubsection ocaf_wp_2_3_3 Basic Data Storage
Normally, all data structures provided by Open CASCADE Technology are run-time structures,
in other words, transient data. As transient data, they exist only while an application
is running and are not stored permanently. However, the Data Storage module provides
resources, which enable an application to store data on disk as persistent data.
Data storage services also provide libraries of persistent classes and translation
functions needed to translate data from transient to persistent state and vice-versa.
#### Libraries of persistent classes
Libraries of persistent classes are extensible libraries of elementary classes you
use to define the database schema of your application. They include:
* Unicode (8-bit or 16-bit character type) strings
* Collections of any kind of persistent data such as arrays.
All persistent classes are derived from the \b Persistent base class, which defines
a unique way of creating and handling persistent objects. You create new persistent
classes by inheriting from this base class.
#### Translation Functions
Translation functions allow you to convert persistent objects to transient ones and
vice-versa. These translation functions are used to build Storage and Retrieval drivers
of an application.
For each class of 2D and 3D geometric types, and for the general shape class in the
topological data structure library, there are corresponding persistent class libraries,
which allow you to translate your data with ease.
#### Creation of Persistent Classes
If you use Unix platforms as well as WOK and CDL, you can create your own persistent
classes. In this case, data storage is achieved by implementing *Storage* and *Retrieval*
drivers.
The <i> Storage </i> package is used to write and read persistent objects.
These objects are read and written by a retrieval or storage algorithm
(<i> Storage_Schema </i>object) in a container (disk, memory, network ...).
Drivers (<i> FSD_File</i> objects) assign a physical container for data to be stored or retrieved.
The standard procedure for an application in reading a container is as follows:
* open the driver in reading mode,
* 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,
* close the driver.
The standard procedure for an application in writing a container is as follows:
* open the driver in writing mode,
* create an instance of the <i> Storage_Data </i> class, then add the persistent data to write with the function <i> AddRoot</i>,
* call the function <i> Write </i> from the schema, setting the driver and the <i> Storage_Data </i> instance as parameters,
* close the driver.
@subsubsection ocaf_wp_2_3_4 Persistent Collections
Persistent collections are classes which handle dynamically sized collections of data that can be stored in the database. These collections provide three categories of service:
* persistent strings,
* generic arrays of data,
* commonly used instantiations of arrays.
Persistent strings are concrete classes that handle sequences of characters based
on both ASCII (normal 8-bit) and Unicode (16-bit) character sets.
Arrays are generic classes, that is, they can hold a variety of objects not necessarily inheriting from a unique root class. These arrays can be instantiated with any kind of storable or persistent object, and then inserted into the persistent data model of a user application.
The purpose of these data collections is simply to convert transient data into its persistent equivalent so that it can be stored in the database. To this end, the collections are used to create the persistent data model and assure the link with the database. They do not provide editing or query capabilities because it is more efficient, within the operative data model of the application, to work with transient data structures (from the <i> TCollection</i> package).
For this reason:
* the persistent strings only provide constructors and functions to convert between transient and persistent strings, and
* the persistent data collections are limited to arrays. In other words, <i> PCollection</i> does not include sequences, lists, and so on (unlike <i> TCollection</i>).
Persistent string and array classes are found in the <i> PCollection</i> package. In addition, <i> PColStd</i> package provides standard, and frequently used, instantiations of persistent arrays, for very simple objects.
@subsubsection ocaf_wp_2_3_5 Persistent Geometry
The Persistent Geometry component describes geometric data structures which can be stored in the database. These packages provide a way to convert data from the transient "world" to the persistent "world".
Persistent Geometry consists of a set of atomic data models parallel to the geometric data structures described in the geometry packages. Geometric data models, independent of each other, can appear within the data model of any application. The system provides the means to convert each atomic transient data model into a persistent one, but it does not provide a way for these data models to share data.
Consequently, you can create a data model using these components, store data in, and retrieve it from a file or a database, using the geometric components provided in the transient and persistent "worlds". In other words, you customize the system by declaring your own objects, and the conversion of the geometric components from persistent to transient and vice versa is automatically managed for you by the system.
However, these simple objects cannot be shared within a more complex data model. To allow data to be shared, you must provide additional tools.
Persistent Geometry is provided by several packages.
The <i> PGeom</i> package describes geometric persistent objects in 3D space, such as points,
vectors, positioning systems, curves and surfaces.
These objects are persistent versions of those provided by the <i> Geom</i> package: for
each type of transient object provided by Geom there is a corresponding type of persistent
object in the <i>PGeom</i> package. In particular the inheritance structure is parallel.
However the <i> PGeom </i>package does not provide any functions to construct, edit or access
the persistent objects. Instead the objects are manipulated as follows:
* Persistent objects are constructed by converting the equivalent transient <i> Geom </i> objects. To do this you use the <i>MgtGeom::Translate</i> function.
* Persistent objects created in this way are used to build persistent data structures that are then stored in a file or database.
* 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.
In other words, you always edit or query transient data structures within the transient
data model supplied by the session.
Consequently, the documentation for the <i> PGeom </i> package consists simply of a list of available objects.
The <i> PGeom2d </i> package describes persistent geometric objects in 2D space, such as points,
vectors, positioning systems and curves. This package provides the same type of services
as the <i> PGeom</i> package, but for the 2D geometric objects provided by the <i> Geom2d</i> package.
Conversions are provided by the <i>MgtGeom::Translate</i> function.
~~~~
//Create a coordinate system
Handle(Geom_Axis2Placement) aSys;
//Create a persistent coordinate PTopoDS_HShape.cdlsystem
Handle(PGeom_Axis2placement)
aPSys = MgtGeom::Translate(aSys);
//Restore a transient coordinate system
Handle(PGeom_Axis2Placement) aPSys;
Handle(Geom_Axis2Placement)
aSys = MgtGeom::Translate(aPSys);
~~~~
@subsubsection ocaf_wp_2_3_6 Persistent Topology
The Persistent Topology component describes topological data structures which can be stored in the database. These packages provide a way to convert data from the transient "world" to the persistent "world".
Persistent Topology is based on the BRep concrete data model provided by the topology packages. Unlike the components of the Persistent Geometry package, topological components can be fully shared within a single model, as well as between several models.
Each topological component is considered to be a shape: a <i> TopoDS_Shape</i> object. The system's capacity to convert a transient shape into a persistent shape and vice-versa applies to all objects, irrespective of their complexity: vertex, edge, wire, face, shell, solid, and so on.
When a user creates a data model using BRep shapes, he uses the conversion functions that the system provides to store the data in, and retrieve it from the database. The data can also be shared.
Persistent Topology is provided by several packages.
The <i> PTopoDS</i> package describes the persistent data model associated with any BRep shape; it is the persistent version of any shape of type <i> TopoDS_Shape</i>. As is the case for persistent geometric models, this data structure is never edited or queried, it is simply stored in or retrieved from the database. It is created or converted by the <i>MgtBRep::Translate</i> function.
The <i> MgtBRepAbs</i> and <i> PTColStd </i> packages provide tools used by the conversion functions of topological objects.
~~~~
//Create a shape
TopoDS_Shape aShape;
//Create a persistent shape
PtColStd_DoubleTransientPersistentMap aMap;
Handle(PTopoDS_HShape) aPShape =
aMap.Bind2(MgtBRep::Translate
aShape,aMap,MgtBRepAbs_WithTriangle));
aPShape.Nullify();
//Restore a transient shape
Handle(PTopoDS_HShape) aPShape;
Handle(TopoDS_HShape) aShape =
aMap.Bind1(MgtBRep::Translate
(aPShape,aMap,MgtBRepAbs_WithTriangle));
aShape.Nullify();
~~~~
@subsubsection ocaf_wp_2_3_7 Standard Documents
Standard documents offer you a ready-to-use document containing a TDF-based data
structure. The documents themselves are contained in a class inheriting from <i> TDocStd_Application</i>
which manages creation, storage and retrieval of documents.
You can implement undo and redo in your document, and refer from the data framework
of one document to that of another one. This is done by means of external link attributes,
which store the path and the entry of external links. To sum up, standard documents
alone provide access to the data framework. They also allow you to:
* Update external links;
* Manage the saving and opening of data;
* Manage undo/redo functionality.

28
dox/user_guides/shape_healing/shape_healing.md
View File

@ -5,9 +5,35 @@ Shape Healing {#occt_user_guides__shape_healing}
@section occt_shg_1 Overview
@subsection occt_shg_1_1 Introduction
This manual explains how to use Shape Healing. It provides basic documentation on its operation. For advanced information on Shape Healing and its applications, see our offerings on our web site at <a href="http://www.opencascade.org/support/training/">www.opencascade.org/support/training/</a>
The **Shape Healing** toolkit provides a set of tools to work on the geometry and topology of Open CASCADE Technology (**OCCT**) shapes. Shape Healing adapts shapes so as to make them as appropriate for use by Open CASCADE Technology as possible.
@subsection occt_shg_1_2 Examples of use
Here are a few examples of typical problems with illustrations of how Shape Healing deals with them:
#### Face with missing seam edge
The problem: Face on a periodical surface is limited by wires which make a full trip around the surface. These wires are closed in 3d but not closed in parametric space of the surface. This is not valid in Open CASCADE.
The solution: Shape Healing fixes this face by inserting seam edge which combines two open wires and thus closes the parametric space. Note that internal wires are processed correctly.
#### Wrong orientation of wires
The problem: Wires on face have incorrect orientation, so that interior and outer parts of the face are mixed.
The solution: Shape Healing recovers correct orientation of wires.
#### Self-intersecting wire
The problem: Face is invalid because its boundary wire has self-intersection (on two adjacent edges)
The solution: Shape Healing cuts intersecting edges at intersection points thus making boundary valid.
#### Lacking edge
The problem: There is a gap between two edges in the wire, so that wire is not closed
The solution: Shape Healing closes a gap by inserting lacking edge.
@subsection occt_shg_1_3 Toolkit Structure
**Shape Healing** currently includes several packages that are designed to help you to:
* analyze shape characteristics and, in particular, identify shapes that do not comply with Open CASCADE Technology validity rules
* fix some of the problems shapes may have
@ -28,7 +54,7 @@ Message management is used for creating messages, filling them with various para
Tools responsible for analysis, fixing and upgrading of shapes can give the information about how these operations were performed. This information can be obtained by the user with the help of mechanism of status querying.
@subsection occt_shg_1_1 Querying the statuses
@subsection occt_shg_1_4 Querying the statuses
Each fixing and upgrading tool has its own status, which is reset when their methods are called. The status can contain several flags, which give the information about how the method was performed. For exploring the statuses, a set of methods named *Status...()* is provided. These methods accept enumeration *ShapeExtend_Status* and return True if the status has the corresponding flag set. The meaning of flags for each method is described below.

BIN
dox/user_guides/step/images/step_image002.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 4.7 KiB

58
dox/user_guides/step/step.md
View File

@ -3,16 +3,70 @@ STEP processor {#occt_user_guides__step}
@tableofcontents
@section occt_step_1 Overview
@section occt_step_1 Introduction
This manual is intended to provide technical documentation on the Open CASCADE Technology (**OCCT**) STEP processor and to help Open CASCADE Technology users with the use of the STEP processor (to read and write STEP files). STEP files conforming to AP 214, AP 203 and partially AP 209 can be read. STEP files that are produced by this interface conform to STEP AP 214 or AP 203, according to the user option.
STEP is more and more widely used to exchange data between various software, involved in CAD, PDM, Analysis, etc... STEP is far more than an "exchange standard" : it provides a technology and a set of methodologies to describe the data to exchange in a modular and upgradeable way. Regarding OCCT, this mostly applies to CAD data but it is not a limitation, other kinds of data for specific applications can be addressed too.
@figure{/user_guides/step/images/step_image002.png, "Image imported from STEP"}
Open Cascade allows its users to employ STEP in the following domains:
* Exchange of data for technical applications, following the state-of-the-art definitions and rules;
* Extension of case coverage, according to specific needs or to the evolution of general business uses;
* Expertise in data architecture of an application, to get experience from STEP definitions and make easier the mapping to them, for a better interoperability with outer world.
This manual is intended to provide technical documentation on the Open CASCADE Technology (**OCCT**) STEP processor and to help Open CASCADE Technology users with the use of the STEP processor (to read and write STEP files).
Only geometrical, topological STEP entities (shapes) and assembly structures are translated by the basic translator described in sections 2 to 6. Data that cannot be translated on this level are also loaded from a STEP file and can be translated later. XDE STEP translator (see section 7 <a href="#occt_step_7">Reading from and writing to XDE</a>) translates names, colors, layers, validation properties and other data associated with shapes and assemblies into XDE document.
File translation is performed in the programming mode, via C++ calls.
@ref occt_user_guides__shape_healing "Shape Healing" toolkit provides tools to heal various problems, which may be encountered in translated shapes, and to make them valid in Open CASCADE. The Shape Healing is smoothly connected to STEP translator using the same API, only the names of API packages change.
For testing the STEP component in DRAW Test Harness, a set of commands for reading and writing STEP files and analysis of relevant data are provided by the *TKXSDRAW* plugin.
See also: our web site at <a href="http://www.opencascade.org/support/training/">E-learning and Training</a>.
@subsection occt_step_1_1 STEP Exchanges in Open Cascade technology
Beyond the upper level API, which is fitted for an easy end-use, the STEP exchange functions enter in the general frame of Exchanges in Open Cascade, adapted for STEP:
* Specific packages for Data definition and checking;
* Physical Access supported by Drivers (Part 21 file access is embedded);
* Conversion to/from Open Cascade or applicative data supported by drivers (OCC-BREP and XDE ard basically provided);
* Tools for analysis, filtering, etc... including DRAW commands.
These modules share common architecture and capabilities with other exchange modules of Open Cascade, like Shape Healing. Also, built-in Viewer and Converter (as Plugin for Netscape, Internet Explorer ..), are based on the same technology.
In addition, Open Cascade provides tools to process models described using STEP: to reflect EXPRESS descriptions, to read, write and check data, to analyze the whole models ... Their key features are:
* Modularity by sets of data types, which can be hierarchized to reflect the original modularity describing the resources and application protocols;
* Implementation as CDL/C++ classes, providing comprehensive access to their members;
* Early binding is basically used, providing good performance, easy installation and use as well as the capability to support non-compiled descriptions.
This provides a natural way to deal with non-supported protocols when they share common definitions, as for geometry, which can then be exploited. The common frame, as the already supported data types, give a good foundation to go towards new uses of STEP, either on data definition (protocols from ISO or from industrial consortia) or on mapping with applicative data.
@subsection occt_step_1_2 STEP Interface
The STEP interface reads STEP files produced in accordance with STEP Application Protocol 214 (Conformance Class 2 both CD and DIS versions of schema) and translates them to Open CASCADE Technology models. STEP Application Protocol 203 is also supported.
The STEP interface also translates OCCT models to STEP files. STEP files that are produced by this interface conform to STEP AP 203 or AP 214 (Conformance Class 2, either CD or DIS version of the schema) depending on the user's option.
Basic interface reads and writes geometrical, topological STEP data and assembly structures.
The interface is able to translate one entity, a group of entities or a whole file.
Other kinds of data such as colors, validation properties, layers, names and the structure of assemblies can be read or written with the help of XDE tools - <i> STEPCAFControl_Reader</i> and <i> STEPCAFControl_Writer</i>.
To choose a translation mode when exporting to a STEP format, use <i> STEPControl_STEPModelType</i>.
There is a set of parameters that concern the translation and can be set before the beginning of the translation.
Please, note:
* a STEP model is a STEP file that has been loaded into memory;
* all references to shapes indicate OCCT shapes unless otherwise explicitly stated;
* a root entity is the highest level entity of any given type, i.e. an entity that is not referenced by any other one.
@section occt_step_2 Reading STEP
@subsection occt_step_2_1 Procedure
You can translate a STEP file into an OCCT shape in the following steps:

BIN
dox/user_guides/xde/images/239_xde_12_400.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 11 KiB

BIN
dox/user_guides/xde/images/614_xde_04_400.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 13 KiB

BIN
dox/user_guides/xde/images/646_xde_11_400.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 7.4 KiB

108
dox/user_guides/xde/xde.md
View File

@ -3,37 +3,29 @@
@tableofcontents
@section occt_xde_1_ Introduction
@subsection occt_xde_1_1 Overview of the Extended Data Exchange (XDE)
@section occt_xde_1 Introduction
This manual explains how to use the Extended Data Exchange (XDE). It provides basic documentation on setting up and using XDE. For advanced information on XDE and its applications, see our offerings at <a href="http://www.opencascade.com/services/support/">on our web site</a>.
Based on document architecture, XDE allows processing of various types of data to and from external files.
The Extended Data Exchange (XDE) module allows extending the scope of exchange by translating additional data attached to geometric BREP data, thereby improving the interoperability with external software.
XDE is available for users of Open CASCADE Technology on all supported platforms (Linux, Windows).
@subsubsection occt_xde_1_1_1 Prerequisite
The Extended Data Exchange (XDE) component requires Advanced Shape Healing for operation.
Data types such as colors, layers, assembly descriptions and validation properties (i.e. center of gravity, etc.) are supported. These data are stored together with shapes in an XCAF document. It is also possible to add a new types of data taking the existing tools as prototypes.
Finally, the XDE provides reader and writer tools for reading and writing the data supported by XCAF to and from IGES and STEP files.
@figure{/user_guides/xde/images/646_xde_11_400.png,"Shape imported using XDE"}
The XDE component requires @ref occt_user_guides__shape_healing "Shape Healing" toolkit for operation.
@subsection occt_xde_1_1 Basic terms
@subsubsection occt_xde_1_1_2 Environment variables
To use XDE you have to set the environment variables properly. Make sure that two important environment variables are set as follows:
* *CSF_PluginDefaults* points to sources of <i>\%CASROOT%/src/XCAFResources ($CASROOT/src/XCAFResources)</i>.
* *CSF_XCAFDefaults* points to sources of <i>\%CASROOT%/src/XCAFResources ($CASROOT/src/XCAFResources)</i>.
@subsubsection occt_xde_1_1_3 Basic terms
For better understanding of XDE, certain key terms are defined:
* **Shape** - a standalone shape, which does not belong to the assembly structure.
* **Instance** - a replication of another shape with a location that can be the same location or a different one.
* **Assembly** - a construction that is either a root or a sub-assembly.
@subsubsection occt_xde_1_1_4 XDE Data Types
The following types of data are currently supported:
* assemblies
* validation properties
* names
* colors
* layers
It is also possible to add new types of data by using tools as prototypes. This makes XDE a basically extensible framework.
In addition, XDE provides reading and writing tools to read and write the data supported by STEP and IGES files.
@subsubsection occt_xde_1_1_5 XDE Organization
@subsection occt_xde_1_2 XDE Organization
The basis of XDE, called XCAF, is a framework based on OCAF (Open CASCADE Technology Application Framework) and is intended to be used with assemblies and with various kinds of attached data (attributes). Attributes can be Individual attributes for a shape, specifying some characteristics of a shape, or they can be Grouping attributes, specifying that a shape belongs to a given group whose definition is specified apart from the shapes.
XDE works in an OCAF document with a specific organization defined in a dedicated XCAF module. This organization is used by various functions of XDE to exchange standardized data other than shapes and geometry.
@ -43,7 +35,7 @@ The Assembly Structure and attributes assigned to shapes are stored in the OCAF
Basic elements used by XDE are introduced in the XCAF sub-module by the package XCAFDoc. These elements consist in descriptions of commonly used data structures (apart from the shapes themselves) in normalized data exchanges. They are not attached to specific applications and do not bring specific semantics, but are structured according to the use and needs of data exchanges.
The Document used by XDE usually starts as a *TDocStd_Document*.
@subsubsection occt_xde_1_1_6 Assemblies
@subsection occt_xde_1_3 Assemblies
XDE supports assemblies by separating shape definitions and their locations. Shapes are simple OCAF objects without a location definition. An assembly consists of several components. Each of these components references one and the same specified shape with different locations. All this provides an increased flexibility in working on multi-level assemblies.
For example, a mechanical assembly can be defined as follows:
@ -57,9 +49,9 @@ For example, a mechanical assembly can be defined as follows:
XDE defines the specific organization of the assembly content. Shapes are stored on sub-labels of label 0:1:1. There can be one or more roots (called free shapes) whether they are true trees or simple shapes. A shape can be considered to be an Assembly (such as AS1 under 0:1:1:1 in Figure1) if it is defined with Components (sub-shapes, located or not).
*XCAFDoc_ShapeTool* is a tool that allows you to manage the Shape section of the XCAF document. This tool is implemented as an attribute and located at the root label of the shape section.
*XCAFDoc_ShapeTool* is a tool that allows managing the Shape section of the XCAF document. This tool is implemented as an attribute and located at the root label of the shape section.
@subsubsection occt_xde_1_1_7 Validation Properties
@subsection occt_xde_1_4 Validation Properties
Validation properties are geometric characteristics of Shapes (volume, centroid, surface area) written to STEP files by the sending system. These characteristics are read by the receiving system to validate the quality of the translation. This is done by comparing the values computed by the original system with the same values computed by the receiving system on the resulting model.
Advanced Data Exchange supports both reading and writing of validation properties, and provides a tool to check them.
@ -67,8 +59,6 @@ Advanced Data Exchange supports both reading and writing of validation propertie
@image html /user_guides/xde/images/xde_image005.png "Validation Property Descriptions"
@image latex /user_guides/xde/images/xde_image005.png "Validation Property Descriptions"
Check logs contain deviations of computed values from the values stored in a STEP file. A typical example appears as follows:
| Label | Area defect | Volume defect | dX | dY | DZ | Name |
@ -90,31 +80,41 @@ Check logs contain deviations of computed values from the values stored in a STE
In our example, it can be seen that no errors were detected for either area, volume or positioning data.
@subsubsection occt_xde_1_1_8 Names
@subsection occt_xde_1_5 Names
XDE supports reading and writing the names of shapes to and from IGES and STEP file formats. This functionality can be switched off if you do not need this type of data, thereby reducing the size of the document.
@subsubsection occt_xde_1_1_9 Colors and Layers
@figure{/user_guides/xde/images/614_xde_04_400.png, "Instance Names"}
@subsection occt_xde_1_6 Colors and Layers
XDE can read and write colors and layers assigned to shapes or their subparts (down to the level of faces and edges) to and from both IGES and STEP formats. Three types of colors are defined in the enumeration *XCAFDoc_ColorType*:
* generic color <i>(XCAFDoc_ColorGen)</i>
* surface color <i>(XCAFDoc_ColorSurf)</i>
* curve color <i>(XCAFDoc_ColorCurv)</i>
@image html /user_guides/xde/images/xde_image006.png "Colors and Layers"
@image latex /user_guides/xde/images/xde_image006.png "Colors and Layers"
@figure{/user_guides/xde/images/xde_image006.png, "Colors and Layers"}
@section occt_xde_2 Working with XDE
@subsection occt_xde_2_1 Getting started
@section occt_xde_2_ Basic Concepts
@subsection occt_xde_2_1 Overview
As explained in the last chapter, XDE uses *TDocStd_Documents* as a starting point. The general purpose of XDE is:
* Checking if an existing document is fit for XDE
* Getting an application and initialized document
* Initializing a document to fit it for XDE
* Adding, setting and finding data
* Querying and managing shapes
* Attaching properties to shapes
The Document used by XDE usually starts as a TDocStd_Document.
* Checking if an existing document is fit for XDE;
* Getting an application and initialized document;
* Initializing a document to fit it for XDE;
* Adding, setting and finding data;
* Querying and managing shapes;
* Attaching properties to shapes.
The Document used by XDE usually starts as a *TDocStd_Document*.
@subsubsection occt_xde_2_1_1 General Check
@subsubsection occt_xde_2_1_1 Environment variables
To use XDE you have to set the environment variables properly. Make sure that two important environment variables are set as follows:
* *CSF_PluginDefaults* points to sources of <i>\%CASROOT%/src/XCAFResources ($CASROOT/src/XCAFResources)</i>.
* *CSF_XCAFDefaults* points to sources of <i>\%CASROOT%/src/XCAFResources ($CASROOT/src/XCAFResources)</i>.
@subsubsection occt_xde_2_1_2 General Check
Before working with shapes, properties, and other types of information, the global organization of an XDE Document can be queried or completed to determine if an existing Document is actually structured for use with XDE.
To find out if an existing *TDocStd_Document* is suitable for XDE, use:
@ -124,13 +124,14 @@ if ( XCAFDoc_DocumentTool::IsXCAFDocument (doc) ) { .. yes .. }
~~~~~
If the Document is suitable for XDE, you can perform operations and queries explained in this guide. However, if a Document is not fully structured for XDE, it must be initialized.
@subsubsection occt_xde_2_1_2 Get an Application or an Initialized Document
@subsubsection occt_xde_2_1_3 Get an Application or an Initialized Document
If you want to retrieve an existing application or an existing document (known to be correctly structured for XDE), use:
~~~~~
Handle(TDocStd_Document) aDoc;
Handle(XCAFApp_Application) anApp = XCAFApp_Application::GetApplication();
anApp->NewDocument(;MDTV-XCAF;,aDoc);
~~~~~
@subsection occt_xde_2_2 Shapes and Assemblies
@subsubsection occt_xde_2_2_1 Initialize an XDE Document (Shapes)
@ -478,10 +479,21 @@ Standard_Real volume ...;
// value previously computed for the volume
XCAFDoc_Volume::Set ( aLabel, volume );
~~~~~
@subsection occt_xde_2_6 Colors
@subsection occt_xde_2_6 Colors and Layers
XDE can read and write colors and layers assigned to shapes or their subparts (down to level of faces and edges) to and from both IGES and STEP formats.
@figure{/user_guides/xde/images/239_xde_12_400.png,"Motor Head"}
In an XDE document, colors are managed by the class *XCAFDoc_ColorTool*. This is done with the same principles as for ShapeTool with Shapes, and with the same capability of having a tool on the Main Label, or on any sub-label. The Property itself is defined as an *XCAFDoc_Color*, sub-class of *TDF_Attribute*.
Colors are stored in a child of the starting document label: it is the second level (0.1.2), while Shapes are at the first level. Each color then corresponds to a dedicated label, the property itself is a Quantity_Color, which has a name and value for Red, Green, Blue. A Color may be attached to Surfaces (flat colors) or to Curves (wireframe colors), or to both. A Color may be attached to a sub-shape. In such a case, the sub-shape (and its own sub-shapes) takes its own Color as a priority.
Colors are stored in a child of the starting document label: it is the second level (0.1.2), while Shapes are at the first level. Each color then corresponds to a dedicated label, the property itself is a Quantity_Color, which has a name and value for Red, Green, Blue. A Color may be attached to Surfaces (flat colors) or to Curves (wireframe colors), or to both. A Color may be attached to a sub-shape. In such a case, the sub-shape (and its own sub-shapes) takes its own Color as a priority.
Layers are handled using the same principles as Colors. In all operations described below you can simply replace **Color** with **Layer** when dealing with Layers. Layers are supported by the class *XCAFDoc_LayerTool*.
The class of the property is *XCAFDoc_Layer*, sub-class of *TDF_Attribute* while its definition is a *TCollection_ExtendedString*. Integers are generally used when dealing with Layers. The general cases are:
* IGES has *LevelList* as a list of Layer Numbers (not often used)
* STEP identifies a Layer (not by a Number, but by a String), to be more general.
Colors and Shapes are related to by Tree Nodes.
@ -595,11 +607,7 @@ To remove a Color and all the references to it (so that the related shapes will
~~~~~
myColors->RemoveColor(ColLabel);
~~~~~
@subsection occt_xde_2_7 Layers
Layers are handled using the same principles as for Colors. Simply replace **Color** with **Layer** when dealing with Layers. Layers are supported by the class *XCAFDoc_LayerTool*.
The class of the property is *XCAFDoc_Layer*, sub-class of *TDF_Attribute* while its definition is a *TCollection_ExtendedString*. Integers are generally used when dealing with Layers. The general cases are:
* IGES has *LevelList* as a list of Layer Numbers (not often used)
* STEP identifies a Layer (not by a Number, but by a String), to be more general.
@subsection occt_xde_2_8 Reading and Writing STEP or IGES
Note that saving and restoring the document itself are standard OCAF operations. As the various previously described definitions enter into this frame, they will not be explained any further.

4
src/ShapeUpgrade/ShapeUpgrade_ShellSewing.cdl
View File

@ -17,7 +17,7 @@
class ShellSewing from ShapeUpgrade
---Purpose: This class provides a tool for applying sewing algorithm from
-- BRepAlgo: it takes a shape, calls sewing for each shell,
-- BRepBuilderAPI: it takes a shape, calls sewing for each shell,
-- and then replaces sewed shells with use of ShapeBuild_ReShape
uses
@ -33,7 +33,7 @@ is
ApplySewing (me: in out; shape: Shape from TopoDS; tol: Real = 0.0)
returns Shape from TopoDS;
---Purpose: Builds a new shape from a former one, by calling Sewing from
-- BRepOffsetAPI. Rebuilt solids are oriented to be "not infinite"
-- BRepBuilderAPI. Rebuilt solids are oriented to be "not infinite"
--
-- If <tol> is not given (i.e. value 0. by default), it is
-- computed as the mean tolerance recorded in <shape>