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.
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
@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).
### 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
### 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.
-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.
+@subsection occt_fcug_2_a Library organization
-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.
+This chapter introduces some basic concepts, which are 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:
* **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.
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 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
-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.
+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
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.
\* 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.
@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.
| 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.
@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.
#### 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.
~~~~~
@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.
~~~~~
~~~~~
@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.
// 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:
+
+~~~~
+ 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;
+~~~~
-Cycles appear if two or more objects reference each other by handles (stored as fields). In this condition automatic destruction will not work.
+
+@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:
IMPLEMENT_STANDARD_RTTIEXT(Appli_ExtSurface,Geom_Surface)
~~~~~
+#### Example
+
+The following example shows how to define a class <i> SamplePoint </i> manipulated by handle.
+
+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>
-@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.
+ // Implementation of Handle and type mgt
-@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()*.
+ 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.
* *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.
* 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.
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.
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
}
~~~~~
-@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,
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
#### 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
#### 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>
~~~~~
-@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
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
#### 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.
@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
*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**,
@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);
~~~~~~
@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
@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,
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:
@section occt_modalg_1 Introduction
-@subsection occt_modalg_1_1 The Modeling Algorithms Module
-
-
This manual explains how to use the Modeling Algorithms. It provides basic documentation on modeling algorithms. For advanced information on Modeling Algorithms, see our offerings on our web site at <a href="http://www.opencascade.org/support/training/">www.opencascade.org/support/training/</a>
The Modeling Algorithms module brings together a wide range of topological algorithms used in modeling. Along with these tools, you will find the geometric algorithms, which they call.
-The algorithms available are divided into:
- * Geometric tools
- * Topological tools
- * The Topology API
-
-@subsection occt_modalg_1_2 The Topology API
-
-The Topology API of Open CASCADE Technology (**OCCT**) includes the following six packages:
-
- * BRepAlgoAPI
- * BRepBuilderAPI
- * BRepFilletAPI
- * BRepFeat
- * BRepOffsetAPI
- * BRepPrimAPI
-
-The classes in these six packages provide the user with a simple and powerful interface.
- * A simple interface: a function call works ideally,
- * A powerful interface: including error handling and access to extra information provided by the algorithms.
-
-As an example, the class BRepBuilderAPI_MakeEdge can be used to create a linear edge from two points.
-
-~~~~~
-gp_Pnt P1(10,0,0), P2(20,0,0);
-TopoDS_Edge E = BRepBuilderAPI_MakeEdge(P1,P2);
-~~~~~
-
-This is the simplest way to create edge E from two points P1, P2, but the developer can test for errors when he is not as confident of the data as in the previous example.
-
-~~~~~
-#include <gp_Pnt.hxx>
-#include <TopoDS_Edge.hxx>
-#include <BRepBuilderAPI_MakeEdge.hxx>
-void EdgeTest()
-{
-gp_Pnt P1;
-gp_Pnt P2;
-BRepBuilderAPI_MakeEdge ME(P1,P2);
-if (!ME.IsDone())
-{
-// doing ME.Edge() or E = ME here
-// would raise StdFail_NotDone
-Standard_DomainError::Raise
-(“ProcessPoints::Failed to createan edge”);
-}
-TopoDS_Edge E = ME;
-}
-~~~~~
-
-In this example an intermediary object ME has been introduced. This can be tested for the completion of the function before accessing the result. More information on **error handling** in the topology programming interface can be found in the next section.
-
-BRepBuilderAPI_MakeEdge provides valuable information. For example, when creating an edge from two points, two vertices have to be created from the points. Sometimes you may be interested in getting these vertices quickly without exploring the new edge. Such information can be provided when using a class. The following example shows a function creating an edge and two vertices from two points.
-
-~~~~~
-void MakeEdgeAndVertices(const gp_Pnt& P1,
-const gp_Pnt& P2,
-TopoDS_Edge& E,
-TopoDS_Vertex& V1,
-TopoDS_Vertex& V2)
-{
-BRepBuilderAPI_MakeEdge ME(P1,P2);
-if (!ME.IsDone()) {
-Standard_DomainError::Raise
-(“MakeEdgeAndVerices::Failed to create an edge”);
-}
-E = ME;
-V1 = ME.Vextex1();
-V2 = ME.Vertex2();
-~~~~~
-
-The BRepBuilderAPI_MakeEdge class provides the two methods Vertex1 and Vertex2, which return the two vertices used to create the edge.
-
-How can BRepBuilderAPI_MakeEdge be both a function and a class? It can do this because it uses the casting capabilities of C++. The BRepBuilderAPI_MakeEdge class has a method called Edge; in the previous example the line E = ME could have been written.
-
-~~~~~
-E = ME.Edge();
-~~~~~
-
-This instruction tells the C++ compiler that there is an **implicit casting** of a *BRepBuilderAPI_MakeEdge* into a *TopoDS_Edge* using the *Edge* method. It means this method is automatically called when a *BRepBuilderAPI_MakeEdge* is found where a *TopoDS_Edge* is required.
-
-This feature allows you to provide classes, which have the simplicity of function calls when required and the power of classes when advanced processing is necessary. All the benefits of this approach are explained when describing the topology programming interface classes.
-
-
-@subsubsection occt_modalg_1_2_1 Error Handling in the Topology API
-
-A method can report an error in the two following situations:
- * The data or arguments of the method are incorrect, i.e. they do not respect the restrictions specified by the methods in its specifications. Typical example: creating a linear edge from two identical points is likely to lead to a zero divide when computing the direction of the line.
- * Something unexpected happened. This situation covers every error not included in the first category. Including: interruption, programming errors in the method or in another method called by the first method, bad specifications of the arguments (i.e. a set of arguments that was not expected to fail).
-
-The second situation is supposed to become increasingly exceptional as a system is debugged and it is handled by the **exception mechanism**. Using exceptions avoids handling error statuses in the call to a method: a very cumbersome style of programming.
-
-In the first situation, an exception is also supposed to be raised because the calling method should have verified the arguments and if it did not do so, there is a bug. For example if before calling *MakeEdge* you are not sure that the two points are non-identical, this situation must be tested.
-
-Making those validity checks on the arguments can be tedious to program and frustrating as you have probably correctly surmised that the method will perform the test twice. It does not trust you.
-As the test involves a great deal of computation, performing it twice is also time-consuming.
-
-Consequently, you might be tempted to adopt the highly inadvisable style of programming illustrated in the following example:
-
-~~~~~
-#include <Standard_ErrorHandler.hxx>
-try {
-TopoDS_Edge E = BRepBuilderAPI_MakeEdge(P1,P2);
-// go on with the edge
-}
-catch {
-// process the error.
-}
-~~~~~
-
-To help the user, the Topology API classes only raise the exception *StdFail_NotDone*. Any other exception means that something happened which was unforeseen in the design of this API.
-
-The *NotDone* exception is only raised when the user tries to access the result of the computation and the original data is corrupted. At the construction of the class instance, if the algorithm cannot be completed, the internal flag *NotDone* is set. This flag can be tested and in some situations a more complete description of the error can be queried. If the user ignores the *NotDone* status and tries to access the result, an exception is raised.
-
-~~~~~
-BRepBuilderAPI_MakeEdge ME(P1,P2);
-if (!ME.IsDone()) {
-// doing ME.Edge() or E = ME here
-// would raise StdFail_NotDone
-Standard_DomainError::Raise
-(“ProcessPoints::Failed to create an edge”);
-}
-TopoDS_Edge E = ME;
-~~~~~
-
@section occt_modalg_2 Geometric Tools
-@subsection occt_modalg_2_1 Overview
-
-Open CASCADE Technology geometric tools include:
-
- * Computation of intersections
- * Interpolation laws
- * Computation of curves and surfaces from constraints
- * Computation of lines and circles from constraints
- * Projections
-
+Open CASCADE Technology geometric tools provide algorithms to:
+ * Calculate the intersection of two 2D curves, surfaces, or a 3D curve and a surface;
+ * Project points onto 2D and 3D curves, points onto surfaces, and 3D curves onto surfaces;
+ * Construct lines and circles from constraints;
+ * Construct curves and surfaces from constraints;
+ * Construct curves and surfaces by interpolation.
+
@subsection occt_modalg_2_2 Intersections
+The Intersections component is used to compute intersections between 2D or 3D geometrical objects:
+ * the intersections between two 2D curves;
+ * the self-intersections of a 2D curve;
+ * the intersection between a 3D curve and a surface;
+ * the intersection between two surfaces.
+
The *Geom2dAPI_InterCurveCurve* class allows the evaluation of the intersection points (*gp_Pnt2d*) between two geometric curves (*Geom2d_Curve*) and the evaluation of the points of self-intersection of a curve.
@image html /user_guides/modeling_algos/images/modeling_algos_image003.png "Intersection and self-intersection of curves"
The algorithm returns a point in the case of an intersection and a segment in the case of tangent intersection.
-@subsubsection occt_modalg_2_2_1 Geom2dAPI_InterCurveCurve
+@subsubsection occt_modalg_2_2_1 Intersection of two curves
-This class may be instantiated either for intersection of curves C1 and C2.
+*Geom2dAPI_InterCurveCurve* class may be instantiated for intersection of curves *C1* and *C2*.
~~~~~
Geom2dAPI_InterCurveCurve Intersector(C1,C2,tolerance);
~~~~~
-or for self-intersection of curve C3.
+or for self-intersection of curve *C3*.
~~~~~
Geom2dAPI_InterCurveCurve Intersector(C3,tolerance);
~~~~~
// if self-intersection of a curve
~~~~~
-If you need access to a wider range of functionalities the following method will return the algorithmic object for the calculation of intersections:
+If you need access to a wider range of functionalities the following method will return the algorithmic object for the calculation of intersections:
~~~~~
Geom2dInt_GInter& TheIntersector = Intersector.Intersector();
~~~~~
@subsubsection occt_modalg_2_2_2 Intersection of Curves and Surfaces
+
The *GeomAPI_IntCS* class is used to compute the intersection points between a curve and a surface.
This class is instantiated as follows:
~~~~~
Where *Index* is an integer between 1 and *nb*, calls the intersection curves.
+
@subsection occt_modalg_2_3 Interpolations
-*Interpolation* provides functionalities for interpolating BSpline curves, whether in 2D, using *Geom2dAPI_Interpolate*, or 3D using *GeomAPI_Interpolate*.
+The Interpolation Laws component provides definitions of functions: <i> y=f(x) </i>.
+
+In particular, it provides definitions of:
+ * a linear function,
+ * an <i> S </i> function, and
+ * an interpolation function for a range of values.
+
+Such functions can be used to define, for example, the evolution law of a fillet along the edge of a shape.
+
+The validity of the function built is never checked: the Law package does not know for what application or to what end the function will be used. In particular, if the function is used as the evolution law of a fillet, it is important that the function is always positive. The user must check this.
@subsubsection occt_modalg_2_3_1 Geom2dAPI_Interpolate
This class is used to interpolate a BSplineCurve passing through an array of points. If tangency is not requested at the point of interpolation, continuity will be *C2*. If tangency is requested at the point, continuity will be *C1*. If Periodicity is requested, the curve will be closed and the junction will be the first point given. The curve will then have a continuity of *C1* only.
@subsection occt_modalg_2_4 Lines and Circles from Constraints
-There are two packages to create lines and circles from constraints: *Geom2dGcc* and *GccAna*. *Geom2dGcc* deals with reference-handled geometric objects from the *Geom2d* package, while *GccAna* deals with value-handled geometric objects from the *gp* package.
+@subsibsection occt_modalg_2_4_1 Types of constraints
-The *Geom2dGcc* package solves geometric constructions of lines and circles expressed by constraints such as tangency or parallelism, that is, a constraint expressed in geometric terms. As a simple example the following figure shows a line which is constrained to pass through a point and be tangent to a circle.
+The algorithms for construction of 2D circles or lines can be described with numeric or geometric constraints in relation to other curves.
-@image html /user_guides/modeling_algos/images/modeling_algos_image005.png "A constrained line"
-@image latex /user_guides/modeling_algos/images/modeling_algos_image005.png "A constrained line"
+These constraints can impose the following :
+ * the radius of a circle,
+ * the angle that a straight line makes with another straight line,
+ * the tangency of a straight line or circle in relation to a curve,
+ * the passage of a straight line or circle through a point,
+ * the circle with center in a point or curve.
-The *Geom2dGcc* package focuses on algorithms; it is useful for finding results, but it does not offer any management or modification functions, which could be applied to the constraints or their arguments. This package is designed to offer optimum performance, both in rapidity and precision. Trivial cases (for example, a circle centered on one point and passing through another) are not treated.
+For example, these algorithms enable to easily construct a circle of a given radius, centered on a straight line and tangential to another circle.
-The *Geom2dGcc* package deals only with 2d objects from the *Geom2d* package. These objects are the points, lines and circles available.
+The implemented algorithms are more complex than those provided by the Direct Constructions component for building 2D circles or lines.
-All other lines such as Bezier curves and conic sections except for circles are considered general curves and must be differentiable twice.
+The expression of a tangency problem generally leads to several results, according to the relative positions of the solution and the circles or straight lines in relation to which the tangency constraints are expressed. For example, consider the following
+case of a circle of a given radius (a small one) which is tangential to two secant circles C1 and C2:
-The *GccAna* package deals with points, lines, and circles from the *gp* package. Apart from constructors for lines and circles, it also allows the creation of conics from the bisection of other geometric objects.
+@figure{/user_guides/modeling_algos/images/modeling_algos_image058.png,"Example of a Tangency Constraint"}
-@subsection occt_modalg_2_5 Provided algorithms
+This diagram clearly shows that there are 8 possible solutions.
-The following analytic algorithms using value-handled entities for creation of 2D lines or circles with geometric constraints are available:
+In order to limit the number of solutions, we can try to express the relative position
+of the required solution in relation to the circles to which it is tangential. For
+example, if we specify that the solution is inside the circle C1 and outside the
+circle C2, only two solutions referenced 3 and 4 on the diagram respond to the problem
+posed.
+
+These definitions are very easy to interpret on a circle, where it is easy to identify
+the interior and exterior sides. In fact, for any kind of curve the interior is defined
+as the left-hand side of the curve in relation to its orientation.
+
+This technique of qualification of a solution, in relation to the curves to which
+it is tangential, can be used in all algorithms for constructing a circle or a straight
+line by geometric constraints. Four qualifiers are used:
+ * **Enclosing** - the solution(s) must enclose the argument;
+ * **Enclosed** - the solution(s) must be enclosed by the argument;
+ * **Outside** - the solution(s) and the argument must be external to one another;
+ * **Unqualified** - the relative position is not qualified, i.e. all solutions apply.
+
+It is possible to create expressions using the qualifiers, for example:
+~~~~~
+GccAna_Circ2d2TanRad
+ Solver(GccEnt::Outside(C1),
+ GccEnt::Enclosing(C2), Rad, Tolerance);
+~~~~~
+This expression finds all circles of radius *Rad*, which are tangent to both circle *C1* and *C2*, while *C1* is outside and *C2* is inside.
+
+@subsection occt_modalg_2_4_2 Available types of lines and circles
+
+The following analytic algorithms using value-handled entities for creation of 2D lines or circles with geometric constraints are available:
* circle tangent to three elements (lines, circles, curves, points),
* circle tangent to two elements and having a radius,
* circle tangent to two elements and centered on a third element,
* line tangent to one element and perpendicular to a line,
* line tangent to one element and forming angle with a line.
-@subsection occt_modalg_2_6 Types of algorithms
-There are three categories of available algorithms, which complement each other:
- * analytic,
- * geometric,
- * iterative.
-
-An analytic algorithm will solve a system of equations, whereas a geometric algorithm works with notions of parallelism, tangency, intersection and so on.
-
-Both methods can provide solutions. An iterative algorithm, however, seeks to refine an approximate solution.
-
-@subsection occt_modalg_2_7 Performance factors
-
-The appropriate algorithm is the one, which reaches a solution of the required accuracy in the least time. Only the solutions actually requested by the user should be calculated. A simple means to reduce the number of solutions is the notion of a "qualifier". There are four qualifiers, which are:
-
- * Unqualified: the position of the solution is undefined with respect to this argument.
- * Enclosing: the solution encompasses this argument.
- * Enclosed: the solution is encompassed by this argument.
- * Outside: the solution and argument are outside each other.
-
-
-@subsection occt_modalg_2_8 Conventions
-
-@subsubsection occt_modalg_2_8_1 Exterior/Interior
+#### Exterior/Interior
It is not hard to define the interior and exterior of a circle. As is shown in the following diagram, the exterior is indicated by the sense of the binormal, that is to say the right side according to the sense of traversing the circle. The left side is therefore the interior (or "material").
@image html /user_guides/modeling_algos/images/modeling_algos_image006.png "Exterior/Interior of a Circle"
@image html /user_guides/modeling_algos/images/modeling_algos_image007.png "Exterior/Interior of a Line and a Curve"
@image latex /user_guides/modeling_algos/images/modeling_algos_image007.png "Exterior/Interior of a Line and a Curve"
-@subsubsection occt_modalg_2_8_2 Orientation of a Line
+#### Orientation of a Line
It is sometimes necessary to define in advance the sense of travel along a line to be created. This sense will be from first to second argument.
The following figure shows a line, which is first tangent to circle C1 which is interior to the line, and then passes through point P1.
@image html /user_guides/modeling_algos/images/modeling_algos_image008.png "An Oriented Line"
@image latex /user_guides/modeling_algos/images/modeling_algos_image008.png "An Oriented Line"
-@subsection occt_modalg_2_9 Examples
-@subsubsection occt_modalg_2_9_1 Line tangent to two circles
+#### Line tangent to two circles
The following four diagrams illustrate four cases of using qualifiers in the creation of a line. The fifth shows the solution if no qualifiers are given.
-
-Note that the qualifier "Outside" is used to mean "Mutually exterior".
+
**Example 1 Case 1**
Constraints:
Tangent and Including C1.
-Tangent and Exterior to C2.
+Tangent and Exterior to C2.
Syntax:
~~~~~
Tolerance);
~~~~~
-@subsubsection occt_modalg_2_9_2 Circle of given radius tangent to two circles
+#### Circle of given radius tangent to two circles
The following four diagrams show the four cases in using qualifiers in the creation of a circle.
**Example 2 Case 1**
GccEnt::Unqualified(C2),
Rad,Tolerance);
~~~~~
-
-@subsection occt_modalg_2_10 Algorithms
-
-The objects created by this toolkit are non-persistent.
-@subsubsection occt_modalg_2_10_1 Qualifiers
-The *GccEnt* package contains the following package methods:
- * Unqualified,
- * Enclosing,
- * Enclosed,
- * Outside.
-
-This enables creation of expressions, for example:
-~~~~~
-GccAna_Circ2d2TanRad
- Solver(GccEnt::Outside(C1),
- GccEnt::Enclosing(C2), Rad, Tolerance);
-~~~~~
-The objective in this case is to find all circles of radius *Rad*, which are tangent to both circle *C1* and *C2*, C1 being outside and C2 being inside.
+@subsection occt_modalg_2_4_2 Types of algorithms
-@subsubsection occt_modalg_2_10_2 General Remarks about Algorithms
+OCCT implements several categories of algorithms:
-We consider the following to be the case:
- * If a circle passes through a point then the circle is tangential to it.
- * A distinction is made between the trivial case of the center at a point and the complex case of the center on a line.
-
-@subsubsection occt_modalg_2_10_3 Analytic Algorithms
-*GccAna* package implements analytic algorithms. It deals only with points, lines, and circles from *gp* package. Here is a list of the services offered:
-
-#### Creation of a Line
-
-
-~~~~~
-Tangent ( point | circle ) & Parallel ( line )
-Tangent ( point | circle ) & Perpendicular ( line | circle )
-Tangent ( point | circle ) & Oblique ( line )
-Tangent ( 2 { point | circle } )
-Bisector( line | line )
-~~~~~
-
-#### Creation of Conics
-
-
-~~~~~
-Bisector ( point | point )
-Bisector ( line | point )
-Bisector ( circle | point )
-Bisector ( line | line )
-Bisector ( circle | line )
-Bisector ( circle | circle )
-~~~~~
-
-#### Creation of a Circle
-
-~~~~~
-Tangent ( point | line | circle ) & Center ( point )
-Tangent ( 3 { point | line | circle } )
-Tangent ( 2 { point | line | circle } ) & Radius ( real )
-Tangent ( 2 { point | line | circle } ) & Center ( line | circle )
-Tangent ( point | line | circle ) & Center ( line | circle ) & Radius ( real )
-~~~~~
-
-For each algorithm, the tolerance (and angular tolerance if appropriate) is given as an argument. Calculation is done with the highest precision available from the hardware.
+* **Analytic** algorithms, where solutions are obtained by the resolution of an equation, such algorithms are used when the geometries which are worked on (tangency arguments, position of the center, etc.) are points, lines or circles;
+* **Geometric** algorithms, where the solution is generally obtained by calculating the intersection of parallel or bisecting curves built from geometric arguments;
+* **Iterative** algorithms, where the solution is obtained by a process of iteration.
+
+For each kind of geometric construction of a constrained line or circle, OCCT provides two types of access:
-@subsubsection occt_modalg_2_10_4 Geometric Algorithms
+ * algorithms from the package <i> Geom2dGcc </i> automatically select the algorithm best suited to the problem, both in the general case and in all types of specific cases; the used arguments are *Geom2d* objects, while the computed solutions are <i> gp </i> objects;
+ * algorithms from the package <i> GccAna</i> resolve the problem analytically, and can only be used when the geometries to be worked on are lines or circles; both the used arguments and the computed solutions are <i> gp </i> objects.
-*Geom2dGcc* package offers algorithms, which produce 2d lines or circles with geometric constraints. For arguments, it takes curves for which an approximate solution is not requested. A tolerance value on the result is given as a starting parameter. The following services are provided:
+The provided algorithms compute all solutions, which correspond to the stated geometric problem, unless the solution is found by an iterative algorithm.
-#### Creation of a Circle
+Iterative algorithms compute only one solution, closest to an initial position. They can be used in the following cases:
+ * to build a circle, when an argument is more complex than a line or a circle, and where the radius is not known or difficult to determine: this is the case for a circle tangential to three geometric elements, or tangential to two geometric elements and centered on a curve;
+ * to build a line, when a tangency argument is more complex than a line or a circle.
-~~~~~
-Tangent ( curve ) & Center ( point )
-Tangent ( curve , point | line | circle | curve ) & Radius ( real )
-Tangent ( 2 {point | line | circle} ) & Center ( curve )
-Tangent ( curve ) & Center ( line | circle | curve ) & Radius ( real )
-Tangent ( point | line | circle ) & Center ( curve ) & Radius ( real )
-~~~~~
+Qualified curves (for tangency arguments) are provided either by:
+ * the <i> GccEnt</i> package, for direct use by <i> GccAna</i> algorithms, or
+ * the <i> Geom2dGcc </i> package, for general use by <i> Geom2dGcc </i> algorithms.
-All calculations will be done to the highest precision available from the hardware.
+The <i> GccEnt</i> and <i> Geom2dGcc</i> packages also provide simple functions for building qualified curves in a very efficient way.
-@subsubsection occt_modalg_2_10_5 Iterative Algorithms
-*Geom2dGcc* package offers iterative algorithms find a solution by refining an approximate solution. It produces 2d lines or circles with geometric constraints. For all geometric arguments except points, an approximate solution may be given as a starting parameter. The tolerance or angular tolerance value is given as an argument. The following services are provided:
+The <i> GccAna </i>package also provides algorithms for constructing bisecting loci between circles, lines or points. Bisecting loci between two geometric objects are such that each of their points is at the same distance from the two geometric objects. They
+are typically curves, such as circles, lines or conics for <i> GccAna</i> algorithms.
+Each elementary solution is given as an elementary bisecting locus object (line, circle, ellipse, hyperbola, parabola), described by the <i>GccInt</i> package.
-#### Creation of a Line
+Note: Curves used by <i>GccAna</i> algorithms to define the geometric problem to be solved, are 2D lines or circles from the <i> gp</i> package: they are not explicitly parameterized. However, these lines or circles retain an implicit parameterization, corresponding to that which they induce on equivalent Geom2d objects. This induced parameterization is the one used when returning parameter values on such curves, for instance with the functions <i> Tangency1, Tangency2, Tangency3, Intersection2</i> and <i> CenterOn3</i> provided by construction algorithms from the <i> GccAna </i> or <i> Geom2dGcc</i> packages.
-~~~~~
-Tangent ( curve ) & Oblique ( line )
-Tangent ( curve , { point | circle | curve } )
-~~~~~
+@subsection occt_modalg_2_5 Curves and Surfaces from Constraints
-#### Creation of a Circle
+The Curves and Surfaces from Constraints component groups together high level functions used in 2D and 3D geometry for:
+ * creation of faired and minimal variation 2D curves
+ * construction of ruled surfaces
+ * construction of pipe surfaces
+ * filling of surfaces
+ * construction of plate surfaces
+ * extension of a 3D curve or surface beyond its original bounds.
+
+OPEN CASCADE company also provides a product known as <a href="http://www.opencascade.org/support/products/ssp/">Surfaces from Scattered Points</a>, which allows constructing surfaces from scattered points. This algorithm accepts or constructs an initial B-Spline surface and looks for its deformation (finite elements method) which would satisfy the constraints. Using optimized computation methods, this algorithm is able to construct a surface from more than 500 000 points.
-~~~~~
-Tangent ( curve , 2 { point | circle | curve } )
-Tangent ( curve , { point | circle | curve } )
-& Center ( line | circle | curve )
-~~~~~
+SSP product is not supplied with Open CASCADE Technology, but can be purchased separately.
-@subsection occt_modalg_2_1 Curves and Surfaces from Constraints
+@subsubsection occt_modalg_2_5_1 Faired and Minimal Variation 2D Curves
-@subsubsection occt_modalg_2_1_1 Fair Curve
+Elastic beam curves have their origin in traditional methods of modeling applied
+in boat-building, where a long thin piece of wood, a lathe, was forced to pass
+between two sets of nails and in this way, take the form of a curve based on the
+two points, the directions of the forces applied at those points, and the properties
+of the wooden lathe itself.
-*FairCurve* package provides a set of classes to create faired 2D curves or 2D curves with minimal variation in curvature.
+Maintaining these constraints requires both longitudinal and transversal forces to
+be applied to the beam in order to compensate for its internal elasticity. The longitudinal
+forces can be a push or a pull and the beam may or may not be allowed to slide over
+these fixed points.
-#### Creation of Batten Curves
+#### Batten Curves
-The class Batten allows producing faired curves defined on the basis of one or more constraints on each of the two reference points. These include point, angle of tangency and curvature settings.
+The class *FairCurve_Batten* allows producing faired curves defined on the basis of one or more constraints on each of the two reference points. These include point, angle of tangency and curvature settings.
The following constraint orders are available:
* 0 the curve must pass through a point
Only 0 and 1 constraint orders are used.
The function Curve returns the result as a 2D BSpline curve.
-#### Creation of Minimal Variation Curves
+#### Minimal Variation Curves
-The class *MinimalVariation* allows producing curves with minimal variation in curvature at each reference point. The following constraint orders are available:
+The class *FairCurve_MinimalVariation* allows producing curves with minimal variation in curvature at each reference point. The following constraint orders are available:
* 0 the curve must pass through a point
* 1 the curve must pass through a point and have a given tangent
The function *Curve* returns the result as a 2D BSpline curve.
-#### Specifying the length of the curve
-
If you want to give a specific length to a batten curve, use:
~~~~~
~~~~~
where *b* is the name of the batten curve object
-#### Limitations
-
-Free sliding is generally more aesthetically pleasing than constrained sliding.
-However, the computation can fail with values such as angles greater than p/2, because in this case, the length is theoretically infinite.
+Free sliding is generally more aesthetically pleasing than constrained sliding. However, the computation can fail with values such as angles greater than *p/2* because in this case the length is theoretically infinite.
In other cases, when sliding is imposed and the sliding factor is too large, the batten can collapse.
-#### Computation Time
-
The constructor parameters, *Tolerance* and *NbIterations*, control how precise the computation is, and how long it will take.
-@subsubsection occt_modalg_2_11_2 Surfaces from Boundary Curves
+@subsubsection occt_modalg_2_5_2 Ruled Surfaces
-The *GeomFill* package provides the following services for creating surfaces from boundary curves:
+A ruled surface is built by ruling a line along the length of two curves.
#### Creation of Bezier surfaces
-The class *BezierCurves* allows producing a Bezier surface from contiguous Bezier curves. Note that problems may occur with rational Bezier Curves.
+The class *GeomFill_BezierCurves* allows producing a Bezier surface from contiguous Bezier curves. Note that problems may occur with rational Bezier Curves.
#### Creation of BSpline surfaces
-The class *BSplineCurves* allows producing a BSpline surface from contiguous BSpline curves. Note that problems may occur with rational BSplines.
+The class *GeomFill_BSplineCurves* allows producing a BSpline surface from contiguous BSpline curves. Note that problems may occur with rational BSplines.
+
+@subsubsection occt_modalg_2_5_2 Pipe Surfaces
+
+The class *GeomFill_Pipe* allows producing a pipe by sweeping a curve (the section) along another curve (the path). The result is a BSpline surface.
+
+The following types of construction are available:
+ * pipes with a circular section of constant radius,
+ * pipes with a constant section,
+ * pipes with a section evolving between two given curves.
+
+
+@subsubsection occt_modalg_2_5_3 Filling a contour
-#### Creation of a Pipe
+It is often convenient to create a surface from two or more curves which will form the boundaries that define the new surface.
+This is done by the class *GeomFill_ConstrainedFilling*, which allows filling a contour defined by two, three or four curves as well as by tangency constraints. The resulting surface is a BSpline.
-The class *Pipe* allows producing a pipe by sweeping a curve (the section) along another curve (the path). The result is a BSpline surface.
+A case in point is the intersection of two fillets at a corner. If the radius of the fillet on one edge is different from that of the fillet on another, it becomes impossible to sew together all the edges of the resulting surfaces. This leaves a gap in the overall surface of the object which you are constructing.
-#### Filling a contour
+@figure{/technical_overview/images/modeling_algos_image059.png,"Intersecting filleted edges with differing radiuses"}
-The class *GeomFill_ConstrainedFilling* allows filling a contour defined by two, three or four curves as well as by tangency constraints. The resulting surface is a BSpline.
+These algorithms allow you to fill this gap from two, three or four curves. This can be done with or without constraints, and the resulting surface will be either a Bezier or a BSpline surface in one of a range of filling styles.
#### Creation of a Boundary
@image html /user_guides/modeling_algos/images/modeling_algos_image018.png "Intersecting filleted edges with different radii leave a gap, is filled by a surface"
@image latex /user_guides/modeling_algos/images/modeling_algos_image018.png "Intersecting filleted edges with different radii leave a gap, is filled by a surface"
+@subsubsection occt_modalg_2_5_4 Plate surfaces
+
+In CAD, it is often necessary to generate a surface which has no exact mathematical definition, but which is defined by respective constraints. These can be of a mathematical, a technical or an aesthetic order.
+
+Essentially, a plate surface is constructed by deforming a surface so that it conforms to a given number of curve or point constraints. In the figure below, you can see four segments of the outline of the plane, and a point which have been used as the
+curve constraints and the point constraint respectively. The resulting surface can be converted into a BSpline surface by using the function <i> MakeApprox </i>.
+
+The surface is built using a variational spline algorithm. It uses the principle of deformation of a thin plate by localised mechanical forces. If not already given in the input, an initial surface is calculated. This corresponds to the plate prior
+to deformation. Then, the algorithm is called to calculate the final surface. It looks for a solution satisfying constraints and minimizing energy input.
+
+@figure{/technical_overview/images/modeling_algos_image061.png,"Surface generated from two curves and a point"}
-@subsubsection occt_modalg_2_11_3 Surfaces from curve and point constraints
-The *GeomPlate* package provides the following services for creating surfaces respecting curve and point constraints:
+The package *GeomPlate* provides the following services for creating surfaces respecting curve and point constraints:
#### Definition of a Framework
The class *MakeApprox* allows converting a *GeomPlate* surface into a *Geom_BSplineSurface*.
-@image html /user_guides/modeling_algos/images/modeling_algos_image019.png "Surface generated from four curves and a point"
-@image latex /user_guides/modeling_algos/images/modeling_algos_image019.png "Surface generated from four curves and a point"
+@figure{/technical_overview/images/modeling_algos_image060.png,"Surface generated from four curves and a point"}
Let us create a Plate surface and approximate it from a polyline as a curve constraint and a point constraint
BRepBuilderAPI_MakeFace MF(Surf,Umin, Umax, Vmin, Vmax);
~~~~~
-@subsection occt_modalg_2_12 Projections
-This package provides functionality for projecting points onto 2D and 3D curves and surfaces.
+@subsection occt_modalg_2_6 Projections
-@subsubsection occt_modalg_2_12_1 Projection of a Point onto a Curve
-*Geom2dAPI_ProjectPointOnCurve* allows calculation of all the normals projected from a point (*gp_Pnt2d*) onto a geometric curve (*Geom2d_Curve*). The calculation may be restricted to a given domain.
+Projections provide for computing the following:
+ * the projections of a 2D point onto a 2D curve
+ * the projections of a 3D point onto a 3D curve or surface
+ * the projection of a 3D curve onto a surface.
+ * the planar curve transposition from the 3D to the 2D parametric space of an underlying plane and v. s.
+ * the positioning of a 2D gp object in the 3D geometric space.
+@subsubsection occt_modalg_2_6_1 Projection of a 2D Point on a Curve
+
+*Geom2dAPI_ProjectPointOnCurve* allows calculation of all normals projected from a point (*gp_Pnt2d*) onto a geometric curve (*Geom2d_Curve*). The calculation may be restricted to a given domain.
@image html /user_guides/modeling_algos/images/modeling_algos_image020.png "Normals from a point to a curve"
@image latex /user_guides/modeling_algos/images/modeling_algos_image020.png "Normals from a point to a curve"
+The curve does not have to be a *Geom2d_TrimmedCurve*. The algorithm will function with any class inheriting *Geom2d_Curve*.
-The curve does not have to be a *Geom2d_TrimmedCurve*. The algorithm will function with any
-class inheriting Geom2d_Curve.
-
-@subsubsection occt_modalg_2_12_2 Geom2dAPI_ProjectPointOnCurve
-This class may be instantiated as in the following example:
+The class *Geom2dAPI_ProjectPointOnCurve* may be instantiated as in the following example:
~~~~~
gp_Pnt2d P;
Standard_Real D = Projector.LowerDistance();
~~~~~
-@subsubsection occt_modalg_2_12_3 Redefined operators
+#### Redefined operators
Some operators have been redefined to find the closest solution.
However, note that in this second case no intermediate *Geom2dAPI_ProjectPointOnCurve* object is created, and thus it is impossible to have access to other solution points.
-@subsubsection occt_modalg_2_12_4 Access to lower-level functionalities
+#### Access to lower-level functionalities
If you want to use the wider range of functionalities available from the *Extrema* package, a call to the *Extrema()* method will return the algorithmic object for calculating extrema. For example:
Extrema_ExtPC2d& TheExtrema = Projector.Extrema();
~~~~~
-@subsubsection occt_modalg_2_12_5 GeomAPI_ProjectPointOnCurve
+@subsubsection occt_modalg_2_6_2 Projection of a 3D Point on a Curve
+
+The class *GeomAPI_ProjectPointOnCurve* is instantiated as in the following example:
-This class is instantiated as in the following example:
~~~~~
gp_Pnt P;
Handle(Geom_BezierCurve) C =
new Geom_BezierCurve(args);
GeomAPI_ProjectPointOnCurve Projector (P, C);
~~~~~
+
If you wish to restrict the search for normals to the given domain [U1,U2], use the following constructor:
+
~~~~~
GeomAPI_ProjectPointOnCurve Projector (P, C, U1, U2);
~~~~~
Extrema_ExtPC& TheExtrema = Projector.Extrema();
~~~~~
-@subsubsection occt_modalg_2_12_6 Projection of a Point on a Surface
+@subsubsection occt_modalg_2_6_3 Projection of a Point on a Surface
-*GeomAPI_ProjectPointOnSurf* class allows calculation of all normals projected from a point from *gp_Pnt* onto a geometric surface from Geom_Surface.
+The class *GeomAPI_ProjectPointOnSurf* allows calculation of all normals projected from a point from *gp_Pnt* onto a geometric surface from *Geom_Surface*.
@image html /user_guides/modeling_algos/images/modeling_algos_image021.png "Projection of normals from a point to a surface"
@image latex /user_guides/modeling_algos/images/modeling_algos_image021.png "Projection of normals from a point to a surface"
Note that the surface does not have to be of *Geom_RectangularTrimmedSurface* type.
-The algorithm will function with any class inheriting Geom_Surface.
+The algorithm will function with any class inheriting *Geom_Surface*.
*GeomAPI_ProjectPointOnSurf* is instantiated as in the following example:
~~~~~
GeomAPI_ProjectPointOnSurf Proj (P, S);
~~~~~
-To restrict the search for normals within the given rectangular domain [U1, U2, V1, V2], use the following constructor:
+To restrict the search for normals within the given rectangular domain [U1, U2, V1, V2], use the constructor <i>GeomAPI_ProjectPointOnSurf Proj (P, S, U1, U2, V1, V2)</i>
-~~~~~
-GeomAPI_ProjectPointOnSurf Proj (P, S, U1, U2, V1, V2);
-~~~~~
-
-The values of U1, U2, V1 and V2 lie at or within their maximum and minimum limits, i.e.:
+The values of *U1, U2, V1* and *V2* lie at or within their maximum and minimum limits, i.e.:
~~~~~
Umin <= U1 < U2 <= Umax
Vmin <= V1 < V2 <= Vmax
In the second case, however, no intermediate *GeomAPI_ProjectPointOnSurf* object is created, and it is impossible to access other solution points.
-@subsubsection occt_modalg_2_12_7 Access to lower-level functionalities
+#### Access to lower-level functionalities
If you want to use the wider range of functionalities available from the *Extrema* package, a call to the *Extrema()* method will return the algorithmic object for calculating the extrema as follows:
Extrema_ExtPS& TheExtrema = Proj.Extrema();
~~~~~
-
@subsubsection occt_modalg_2_12_8 Switching from 2d and 3d Curves
-The To2d and To3d methods are used to;
+
+The *To2d* and *To3d* methods are used to;
* build a 2d curve from a 3d *Geom_Curve* lying on a *gp_Pln* plane
* build a 3d curve from a *Geom2d_Curve* and a *gp_Pln* plane.
Handle(Geom_Curve) C3d = GeomAPI::To3d(C2d, Pln);
~~~~~
+@section occt_modalg_3a The Topology API
+
+The Topology API of Open CASCADE Technology (**OCCT**) includes the following six packages:
+ * *BRepAlgoAPI*
+ * *BRepBuilderAPI*
+ * *BRepFilletAPI*
+ * *BRepFeat*
+ * *BRepOffsetAPI*
+ * *BRepPrimAPI*
+
+The classes provided by the API have the following features:
+ * The constructors of classes provide different construction methods;
+ * The class retains different tools used to build objects as fields;
+ * The class provides a casting method to obtain the result automatically with a function-like call.
+
+Let us use the class *BRepBuilderAPI_MakeEdge* to create a linear edge from two points.
+
+~~~~~
+gp_Pnt P1(10,0,0), P2(20,0,0);
+TopoDS_Edge E = BRepBuilderAPI_MakeEdge(P1,P2);
+~~~~~
+
+This is the simplest way to create edge E from two points P1, P2, but the developer can test for errors when he is not as confident of the data as in the previous example.
+
+~~~~~
+#include <gp_Pnt.hxx>
+#include <TopoDS_Edge.hxx>
+#include <BRepBuilderAPI_MakeEdge.hxx>
+void EdgeTest()
+{
+gp_Pnt P1;
+gp_Pnt P2;
+BRepBuilderAPI_MakeEdge ME(P1,P2);
+if (!ME.IsDone())
+{
+// doing ME.Edge() or E = ME here
+// would raise StdFail_NotDone
+Standard_DomainError::Raise
+(“ProcessPoints::Failed to createan edge”);
+}
+TopoDS_Edge E = ME;
+}
+~~~~~
-@section occt_modalg_3 Topological Tools
+In this example an intermediary object ME has been introduced. This can be tested for the completion of the function before accessing the result. More information on **error handling** in the topology programming interface can be found in the next section.
-Open CASCADE Technology topological tools include:
+*BRepBuilderAPI_MakeEdge* provides valuable information. For example, when creating an edge from two points, two vertices have to be created from the points. Sometimes you may be interested in getting these vertices quickly without exploring the new edge. Such information can be provided when using a class. The following example shows a function creating an edge and two vertices from two points.
- * Standard topological objects combining topological data structure and boundary representation
- * Geometric Transformations
- * Conversion to NURBS geometry
- * Finding Planes
- * Duplicating Shapes
- * Checking Validity
+~~~~~
+void MakeEdgeAndVertices(const gp_Pnt& P1,
+const gp_Pnt& P2,
+TopoDS_Edge& E,
+TopoDS_Vertex& V1,
+TopoDS_Vertex& V2)
+{
+BRepBuilderAPI_MakeEdge ME(P1,P2);
+if (!ME.IsDone()) {
+Standard_DomainError::Raise
+(“MakeEdgeAndVerices::Failed to create an edge”);
+}
+E = ME;
+V1 = ME.Vextex1();
+V2 = ME.Vertex2();
+~~~~~
+The class *BRepBuilderAPI_MakeEdge* provides two methods *Vertex1* and *Vertex2*, which return two vertices used to create the edge.
+
+How can *BRepBuilderAPI_MakeEdge* be both a function and a class? It can do this because it uses the casting capabilities of C++. The *BRepBuilderAPI_MakeEdge* class has a method called Edge; in the previous example the line <i>E = ME</i> could have been written.
+
+~~~~~
+E = ME.Edge();
+~~~~~
+
+This instruction tells the C++ compiler that there is an **implicit casting** of a *BRepBuilderAPI_MakeEdge* into a *TopoDS_Edge* using the *Edge* method. It means this method is automatically called when a *BRepBuilderAPI_MakeEdge* is found where a *TopoDS_Edge* is required.
+
+This feature allows you to provide classes, which have the simplicity of function calls when required and the power of classes when advanced processing is necessary. All the benefits of this approach are explained when describing the topology programming interface classes.
+
+
+@subsection occt_modalg_3a_1 Error Handling in the Topology API
+
+A method can report an error in the two following situations:
+ * The data or arguments of the method are incorrect, i.e. they do not respect the restrictions specified by the methods in its specifications. Typical example: creating a linear edge from two identical points is likely to lead to a zero divide when computing the direction of the line.
+ * Something unexpected happened. This situation covers every error not included in the first category. Including: interruption, programming errors in the method or in another method called by the first method, bad specifications of the arguments (i.e. a set of arguments that was not expected to fail).
+
+The second situation is supposed to become increasingly exceptional as a system is debugged and it is handled by the **exception mechanism**. Using exceptions avoids handling error statuses in the call to a method: a very cumbersome style of programming.
+
+In the first situation, an exception is also supposed to be raised because the calling method should have verified the arguments and if it did not do so, there is a bug. For example, if before calling *MakeEdge* you are not sure that the two points are non-identical, this situation must be tested.
+
+Making those validity checks on the arguments can be tedious to program and frustrating as you have probably correctly surmised that the method will perform the test twice. It does not trust you.
+As the test involves a great deal of computation, performing it twice is also time-consuming.
+
+Consequently, you might be tempted to adopt the highly inadvisable style of programming illustrated in the following example:
+
+~~~~~
+#include <Standard_ErrorHandler.hxx>
+try {
+TopoDS_Edge E = BRepBuilderAPI_MakeEdge(P1,P2);
+// go on with the edge
+}
+catch {
+// process the error.
+}
+~~~~~
+
+To help the user, the Topology API classes only raise the exception *StdFail_NotDone*. Any other exception means that something happened which was unforeseen in the design of this API.
+
+The *NotDone* exception is only raised when the user tries to access the result of the computation and the original data is corrupted. At the construction of the class instance, if the algorithm cannot be completed, the internal flag *NotDone* is set. This flag can be tested and in some situations a more complete description of the error can be queried. If the user ignores the *NotDone* status and tries to access the result, an exception is raised.
+
+~~~~~
+BRepBuilderAPI_MakeEdge ME(P1,P2);
+if (!ME.IsDone()) {
+// doing ME.Edge() or E = ME here
+// would raise StdFail_NotDone
+Standard_DomainError::Raise
+(“ProcessPoints::Failed to create an edge”);
+}
+TopoDS_Edge E = ME;
+~~~~~
-@subsection occt_modalg_3_1 Creation of Standard Topological Objects
+@section occt_modalg_3 Standard Topological Objects
-The standard topological objects include
+The following standard topological objects can be created:
* Vertices
* Edges
- * Wires
* Faces
+ * Wires
+ * Polygonal wires
* Shells
* Solids.
There are two root classes for their construction and modification:
* The deferred class *BRepBuilderAPI_MakeShape* is the root of all *BRepBuilderAPI* classes, which build shapes. It inherits from the class *BRepBuilderAPI_Command* and provides a field to store the constructed shape.
-* The deferred *BRepBuilderAPI_ModifyShape* is used as a root for the shape modifications. It inherits *BRepBuilderAPI_MakeShape* and implements the methods used to trace the history of all sub-shapes.
+* The deferred class *BRepBuilderAPI_ModifyShape* is used as a root for the shape modifications. It inherits *BRepBuilderAPI_MakeShape* and implements the methods used to trace the history of all sub-shapes.
-@subsubsection occt_modalg_3_1_1 Vertex
+@subection occt_modalg_3_1 Vertex
*BRepBuilderAPI_MakeVertex* creates a new vertex from a 3D point from gp.
~~~~~
This class always creates a new vertex and has no other methods.
-@subsubsection occt_modalg_3_1_2 Edge
+@subsection occt_modalg_3_2 Edge
-Use *BRepBuilderAPI_MakeEdge* to create from a curve and vertices. The basic method is to construct an edge from a curve, two vertices, and two parameters. All other constructions are derived from this one. The basic method and its arguments are described first, followed by the other methods. The BRepBuilderAPI_MakeEdge class can provide extra information and return an error status.
+@subsubsection occt_modalg_3_2_1 Basic edge construction method
-#### Basic Edge construction
+Use *BRepBuilderAPI_MakeEdge* to create from a curve and vertices. The basic method constructs an edge from a curve, two vertices, and two parameters.
~~~~~
Handle(Geom_Curve) C = ...; // a curve
@image html /user_guides/modeling_algos/images/modeling_algos_image023.png "Infinite and Periodic Edges"
@image latex /user_guides/modeling_algos/images/modeling_algos_image023.png "Infinite and Periodic Edges"
+@subsubsection occt_modalg_3_2_2 Supplementary edge construction methods
-#### Other Edge constructions
+There exist supplementary edge construction methods derived from the basic one.
*BRepBuilderAPI_MakeEdge* class provides methods, which are all simplified calls of the previous one:
E = BRepBuilderAPI_MakeEdge(P1,P2);
~~~~~
-#### Other information and error status
+@subsubsection occt_modalg_3_2_3 Other information and error status
+
+The class *BRepBuilderAPI_MakeEdge* can provide extra information and return an error status.
If *BRepBuilderAPI_MakeEdge* is used as a class, it can provide two vertices. This is useful when the vertices were not provided as arguments, for example when the edge was constructed from a curve and parameters. The two methods *Vertex1* and *Vertex2* return the vertices. Note that the returned vertices can be null if the edge is open in the corresponding direction.
}
~~~~~
-@subsubsection occt_modalg_3_1_3 Edge 2D
+@subsection occt_modalg_3_3 Edge 2D
Use *BRepBuilderAPI_MakeEdge2d* class to make edges on a working plane from 2d curves. The working plane is a default value of the *BRepBuilderAPI* package (see the *Plane* methods).
*BRepBuilderAPI_MakeEdge2d* class is strictly similar to BRepBuilderAPI_MakeEdge, but it uses 2D geometry from gp and Geom2d instead of 3D geometry.
-@subsubsection occt_modalg_3_1_4 Polygon
+@subsection occt_modalg_3_4 Polygon
*BRepBuilderAPI_MakePolygon* class is used to build polygonal wires from vertices or points. Points are automatically changed to vertices as in *BRepBuilderAPI_MakeEdge*.
When the added point or vertex has the same location as the previous one it is not added to the current wire but the most recently created edge becomes Null. The *Added* method can be used to test this condition. The *MakePolygon* class never raises an error. If no vertex has been added, the *Wire* is *Null*. If two vertices are at the same location, no edge is created.
-@subsubsection occt_modalg_3_1_5 Face
+@subsection occt_modalg_3_5 Face
Use *BRepBuilderAPI_MakeFace* class to create a face from a surface and wires. An underlying surface is constructed from a surface and optional parametric values. Wires can be added to the surface. A planar surface can be constructed from a wire. An error status can be returned after face construction.
-#### Basic face construction
+@subsubsection occt_modalg_3_5_1 Basic face construction method
A face can be constructed from a surface and four parameters to determine a limitation of the UV space. The parameters are optional, if they are omitted the natural bounds of the surface are used. Up to four edges and vertices are created with a wire. No edge is created when the parameter is infinite.
* On a *U (V)* periodic surface *umin* and *umax (vmin,vmax)* are adjusted.
* *umin, umax, vmin, vmax* can be infinite. There will be no edge in the corresponding direction.
+@subsubsection occt_modalg_3_5_2 Supplementary face construction methods
-#### Other face constructions
-
-The two basic constructions (from a surface and from a surface and parameters) are implemented for all the gp package surfaces, which are transformed in the corresponding Surface from Geom.
+The two basic constructions (from a surface and from a surface and parameters) are implemented for all *gp* package surfaces, which are transformed in the corresponding Surface from Geom.
| gp package surface | | Geom package surface |
| :------------------- | :----------- | :------------- |
| *gp_Sphere* | | *Geom_SphericalSurface* |
| *gp_Torus* | | *Geom_ToroidalSurface* |
-Once a face has been created, a wire can be added using the Add method. For example, the following code creates a cylindrical surface and adds a wire.
+Once a face has been created, a wire can be added using the *Add* method. For example, the following code creates a cylindrical surface and adds a wire.
~~~~~
gp_Cylinder C = ..; // a cylinder
}
~~~~~
-The last use of *MakeFace* is to copy an existing face to add new wires. For example the following code adds a new wire to a face:
+The last use of *MakeFace* is to copy an existing face to add new wires. For example, the following code adds a new wire to a face:
~~~~~
TopoDS_Face F = ...; // a face
F = BRepBuilderAPI_MakeFace(F,W);
~~~~~
-To add more than one wire an instance of the *BRepBuilderAPI_MakeFace* class can be created with the face and the first wire and the new wires inserted with the Add method.
+To add more than one wire an instance of the *BRepBuilderAPI_MakeFace* class can be created with the face and the first wire and the new wires inserted with the *Add* method.
+
+@subsubsection occt_modalg_3_5_3 Error status
-Error status
-------------
-The Error method returns an error status, which is a term from the *BRepBuilderAPI_FaceError* enumeration.
+The *Error* method returns an error status, which is a term from the *BRepBuilderAPI_FaceError* enumeration.
* *FaceDone* - no error occurred.
* *NoFace* - no initialization of the algorithm; an empty constructor was used.
* *CurveProjectionFailed* - no curve was found in the parametric space of the surface for an edge.
* *ParametersOutOfRange* - the parameters *umin, umax, vmin, vmax* are out of the surface.
-@subsubsection occt_modalg_3_1_6 Wire
+@subsection occt_modalg_3_6 Wire
The wire is a composite shape built not from a geometry, but by the assembly of edges. *BRepBuilderAPI_MakeWire* class can build a wire from one or more edges or connect new edges to an existing wire.
Up to four edges can be used directly, for example:
*DisconnectedWire* - the last added edge was not connected to the wire.
*NonManifoldWire* - the wire with some singularity.
-@subsubsection occt_modalg_3_1_7 Shell
+@subsection occt_modalg_3_7 Shell
The shell is a composite shape built not from a geometry, but by the assembly of faces.
Use *BRepBuilderAPI_MakeShell* class to build a Shell from a set of Faces. What may be important is that each face should have the required continuity. That is why an initial surface is broken up into faces.
-@subsubsection occt_modalg_3_1_8 Solid
+@subsection occt_modalg_3_8 Solid
The solid is a composite shape built not from a geometry, but by the assembly of shells. Use *BRepBuilderAPI_MakeSolid* class to build a Solid from a set of Shells. Its use is similar to the use of the MakeWire class: shells are added to the solid in the same way that edges are added to the wire in MakeWire.
-@subsubsection occt_modalg_3_2 Modification Operators
+@section occt_modalg_3b Object Modification
-@subsubsection occt_modalg_3_2_1 Transformation
+@subsection occt_modalg_3b_1 Transformation
*BRepBuilderAPI_Transform* class can be used to apply a transformation to a shape (see class *gp_Trsf*). The methods have a boolean argument to copy or share the original shape, as long as the transformation allows (it is only possible for direct isometric transformations). By default, the original shape is shared.
The following example deals with the rotation of shapes.
TopoDS_Shape myNewShape2 = theTrsf.Shape()
~~~~~
-@subsubsection occt_modalg_3_2_2 Duplication
+@subsection occt_modalg_3b_2 Duplication
Use the *BRepBuilderAPI_Copy* class to duplicate a shape. A new shape is thus created.
In the following example, a solid is copied:
TopoDS_Solid myCopy = BRepBuilderAPI_Copy(mySolid);
~~~~~
-@section occt_modalg_4 Construction of Primitives
+
+@section occt_modalg_4 Primitives
+
+The <i> BRepPrimAPI</i> package provides an API (Application Programming Interface) for construction of primitives such as:
+ * Boxes;
+ * Cones;
+ * Cylinders;
+ * Prisms.
+
+It is possible to create partial solids, such as a sphere limited by longitude. In real models, primitives can be used for easy creation of specific sub-parts.
+
+ * Construction by sweeping along a profile:
+ * Linear;
+ * Rotational (through an angle of rotation).
+
+Sweeps are objects obtained by sweeping a profile along a path. The profile can be any topology and the path is usually a curve or a wire. The profile generates objects according to the following rules:
+ * Vertices generate Edges
+ * Edges generate Faces.
+ * Wires generate Shells.
+ * Faces generate Solids.
+ * Shells generate Composite Solids.
+
+It is not allowed to sweep Solids and Composite Solids. Swept constructions along complex profiles such as BSpline curves also available in the <i> BRepOffsetAPI </i> package. This API provides simple, high level calls for the most common operations.
+
@subsection occt_modalg_4_1 Making Primitives
@subsubsection occt_modalg_4_1_1 Box
-BRepPrimAPI_MakeBox class allows building a parallelepiped box. The result is either a Shell or a Solid. There are four ways to build a box:
+The class *BRepPrimAPI_MakeBox* allows building a parallelepiped box. The result is either a **Shell** or a **Solid**. There are four ways to build a box:
-* From three dimensions dx,dy,dz. The box is parallel to the axes and extends for [0,dx] [0,dy] [0,dz].
+* From three dimensions *dx, dy* and *dz*. The box is parallel to the axes and extends for <i>[0,dx] [0,dy] [0,dz] </i>.
* From a point and three dimensions. The same as above but the point is the new origin.
* From two points, the box is parallel to the axes and extends on the intervals defined by the coordinates of the two points.
-* From a system of axes (gp_Ax2) and three dimensions. Same as the first way but the box is parallel to the given system of axes.
+* From a system of axes *gp_Ax2* and three dimensions. Same as the first way but the box is parallel to the given system of axes.
An error is raised if the box is flat in any dimension using the default precision. The following code shows how to create a box:
~~~~~
@subsubsection occt_modalg_4_1_2 Wedge
*BRepPrimAPI_MakeWedge* class allows building a wedge, which is a slanted box, i.e. a box with angles. The wedge is constructed in much the same way as a box i.e. from three dimensions dx,dy,dz plus arguments or from an axis system, three dimensions, and arguments.
-The following figure shows two ways to build wedges. One is to add an ltx dimension, which is the length in x of the face at dy. The second is to add xmin, xmax, zmin, zmax to describe the face at dy.
+The following figure shows two ways to build wedges. One is to add a dimension *ltx*, which is the length in *x* of the face at *dy*. The second is to add *xmin, xmax, zmin* and *zmax* to describe the face at *dy*.
-The first method is a particular case of the second with xmin = 0, xmax = ltx, zmin = 0, zmax = dz.
-To make a centered pyramid you can use xmin = xmax = dx / 2, zmin = zmax = dz / 2.
+The first method is a particular case of the second with *xmin = 0, xmax = ltx, zmin = 0, zmax = dz*.
+To make a centered pyramid you can use *xmin = xmax = dx / 2, zmin = zmax = dz / 2*.
@image html /user_guides/modeling_algos/images/modeling_algos_image027.png "Making Wedges"
@image latex /user_guides/modeling_algos/images/modeling_algos_image027.png "Making Wedges"
@image latex /user_guides/modeling_algos/images/modeling_algos_image028.png "MakeOneAxis arguments"
@subsubsection occt_modalg_4_1_4 Cylinder
-*BRepPrimAPI_MakeCylinder* class allows creating cylindrical primitives. A cylinder is created either in the default coordinate system or in a given coordinate system (gp_Ax2). There are two constructions:
+*BRepPrimAPI_MakeCylinder* class allows creating cylindrical primitives. A cylinder is created either in the default coordinate system or in a given coordinate system *gp_Ax2*. There are two constructions:
* Radius and height, to build a full cylinder.
* Radius, height and angle to build a portion of a cylinder.
-The following code builds the cylindrical face of the figure, which is a quarter of cylinder along the Y axis with the origin at X,Y,Z, a length of DY, and a radius R.
+The following code builds the cylindrical face of the figure, which is a quarter of cylinder along the *Y* axis with the origin at *X,Y,Z* the length of *DY* and radius *R*.
~~~~~
* Two radii and height, to build a full cone. One of the radii can be null to make a sharp cone.
* Radii, height and angle to build a truncated cone.
-The following code builds the solid cone of the figure, which is located in the default system with radii R1 and R2 and height H.
+The following code builds the solid cone of the figure, which is located in the default system with radii *R1* and *R2* and height *H*.
~~~~~
Standard_Real R1 = 30, R2 = 10, H = 15;
@image latex /user_guides/modeling_algos/images/modeling_algos_image030.png "Cone"
@subsubsection occt_modalg_4_1_6 Sphere
-*BRepPrimAPI_MakeSphere* class allows creating spherical primitives. Like a cylinder, a sphere is created either in the default coordinate system or in a given coordinate system (gp_Ax2). There are four constructions:
+*BRepPrimAPI_MakeSphere* class allows creating spherical primitives. Like a cylinder, a sphere is created either in the default coordinate system or in a given coordinate system *gp_Ax2*. There are four constructions:
* From a radius - builds a full sphere.
* From a radius and an angle - builds a lune (digon).
- * From a radius and two angles - builds a wraparound spherical segment between two latitudes. The angles a1, a2 must follow the relation: PI/2 <= a1 < a2 <= PI/2.
+ * From a radius and two angles - builds a wraparound spherical segment between two latitudes. The angles *a1* and *a2* must follow the relation: <i>PI/2 <= a1 < a2 <= PI/2 </i>.
* From a radius and three angles - a combination of two previous methods builds a portion of spherical segment.
The following code builds four spheres from a radius and three angles.
@subsubsection occt_modalg_4_1_7 Torus
-*BRepPrimAPI_MakeTorus* class allows creating toroidal primitives. Like the other primitives, a torus is created either in the default coordinate system or in a given coordinate system (gp_Ax2). There are four constructions similar to the sphere constructions:
+*BRepPrimAPI_MakeTorus* class allows creating toroidal primitives. Like the other primitives, a torus is created either in the default coordinate system or in a given coordinate system *gp_Ax2*. There are four constructions similar to the sphere constructions:
* Two radii - builds a full torus.
* Two radii and an angle - builds an angular torus segment.
@image html /user_guides/modeling_algos/images/modeling_algos_image034.png "Finite, infinite, and semi-infinite prisms"
@image latex /user_guides/modeling_algos/images/modeling_algos_image034.png "Finite, infinite, and semi-infinite prisms"
-@subsubsection occt_modalg_4_2_3 Rotation
+@subsubsection occt_modalg_4_2_3 Rotational Sweep
*BRepPrimAPI_MakeRevol* class allows creating a rotational sweep from a shape, an axis (gp_Ax1), and an angle. The angle has a default value of 2*PI which means a closed revolution.
*BRepPrimAPI_MakeRevol* constructors have a last argument to copy or share the original shape. The following code creates a a full and a partial rotation using a face, an axis and an angle.
@section occt_modalg_5 Boolean Operations
Boolean operations are used to create new shapes from the combinations of two shapes.
-See @ref occt_user_guides__boolean_operations "Boolean Operations" for detailed documentation.
| Operation | Result |
| :---- | :------ |
| Common | all points in S1 and S2 |
| Cut S1 by S2| all points in S1 and not in S2 |
-BRepAlgoAPI_BooleanOperation class is the deferred root class for Boolean operations.
-
@image html /user_guides/modeling_algos/images/modeling_algos_image036.png "Boolean Operations"
@image latex /user_guides/modeling_algos/images/modeling_algos_image036.png "Boolean Operations"
-@subsection occt_modalg_5_1 Fuse
+From the viewpoint of Topology these are topological operations followed by blending (putting fillets onto edges created after the topological operation).
+
+Topological operations are the most convenient way to create real industrial parts. As most industrial parts consist of several simple elements such as gear wheels, arms, holes, ribs, tubes and pipes. It is usually easy to create those elements separately and then to combine them by Boolean operations in the whole final part.
+
+See @ref occt_user_guides__boolean_operations "Boolean Operations" for detailed documentation.
+
+@subsection occt_modalg_5_1 Input and Result Arguments
+
+Boolean Operations have the following types of the arguments and produce the following results:
+* For arguments having the same shape type (e.g. SOLID / SOLID) the type of the resulting shape will be a COMPOUND, containing shapes of this type;
+* For arguments having different shape types (e.g. SHELL / SOLID) the type of the resulting shape will be a COMPOUND, containing shapes of the type that is the same as that of the low type of the argument. Example: For SHELL/SOLID the result is a COMPOUND of SHELLs.
+* For arguments with different shape types some of Boolean Operations can not be done using the default implementation, because of a non-manifold type of the result. Example: the FUSE operation for SHELL and SOLID can not be done, but the CUT operation can be done, where SHELL is the object and SOLID is the tool.
+* It is possible to perform Boolean Operations on arguments of the COMPOUND shape type. In this case each compound must not be heterogeneous, i.e. it must contain equidimensional shapes (EDGEs or/and WIREs, FACEs or/and SHELLs, SOLIDs). SOLIDs inside the COMPOUND must not contact (intersect or touch) each other. The same condition should be respected for SHELLs or FACEs, WIREs or EDGEs.
+* Boolean Operations for COMPSOLID type of shape are not supported.
+
+@subsection occt_modalg_5_2 Implementation
+
+*BRepAlgoAPI_BooleanOperation* class is the deferred root class for Boolean operations.
+
+#### Fuse
*BRepAlgoAPI_Fuse* performs the Fuse operation.
TopoDS_Shape S = BRepAlgoAPI_Fuse(A,B);
~~~~~
-@subsection occt_modalg_5_2 Common
+#### Common
*BRepAlgoAPI_Common* performs the Common operation.
TopoDS_Shape S = BRepAlgoAPI_Common(A,B);
~~~~~
-@subsection occt_modalg_5_3 Cut
+#### Cut
*BRepAlgoAPI_Cut* performs the Cut operation.
~~~~~
TopoDS_Shape S = BRepAlgoAPI_Cut(A,B);
~~~~~
-@subsection occt_modalg_5_4 Section
+#### Section
*BRepAlgoAPI_Section* performs the section, described as a *TopoDS_Compound* made of *TopoDS_Edge*.
~~~~~
@section occt_modalg_6 Fillets and Chamfers
+
+This library provides algorithms to make fillets and chamfers on shape edges.
+The following cases are addressed:
+
+ * Corners and apexes with different radii;
+ * Corners and apexes with different concavity.
+
+If there is a concavity, both surfaces that need to be extended and those, which do not, are processed.
+
@subsection occt_modalg_6_1 Fillets
@subsection occt_modalg_6_1_1 Fillet on shape
~~~~~
@section occt_modalg_7 Offsets, Drafts, Pipes and Evolved shapes
+
+These classes provide the following services:
+
+ * Creation of offset shapes and their variants such as:
+ * Hollowing;
+ * Shelling;
+ * Lofting;
+ * Creation of tapered shapes using draft angles;
+ * Creation of sweeps.
+
@subsection occt_modalg_7_1 Shelling
Shelling is used to offset given faces of a solid by a specific value. It rounds or intersects adjacent faces along its edges depending on the convexity of the edge.
BRepOffsetAPI_MakeEvolved(Spine,Profile);
~~~~~
-@section occt_modalg_8 Sewing operators
-@subsection occt_modalg_8_1 Sewing
+@section occt_modalg_8 Sewing
+
+@subsection occt_modalg_8_1 Introduction
-*BRepOffsetAPI_Sewing* class allows sewing TopoDS Shapes together along their common edges. The edges can be partially shared as in the following example.
+Sewing allows creation of connected topology (shells and wires) from a set of separate topological elements (faces and edges). For example, Sewing can be used to create of shell from a compound of separate faces.
@image html /user_guides/modeling_algos/images/modeling_algos_image045.png "Shapes with partially shared edges"
@image latex /user_guides/modeling_algos/images/modeling_algos_image045.png "Shapes with partially shared edges"
-The constructor takes as arguments the tolerance (default value is 10-6) and a flag, which is used to mark the degenerate shapes.
-
-The following methods are used in this class:
-* *Add* adds shapes, as it is needed;
-* *Perform* forces calculation of the sewed shape.
-* *SewedShape* returns the result.
+It is important to distinguish between sewing and other procedures, which modify the geometry, such as filling holes or gaps, gluing, bending curves and surfaces, etc.
-Additional methods can be used to give information on the number of free boundaries, multiple edges and degenerate shapes.
+Sewing does not change geometrical representation of the shapes. Sewing applies to topological elements (faces, edges) which are not connected but can be connected because they are geometrically coincident : it adds the information about topological connectivity. Already connected elements are left untouched in case of manifold sewing.
-@subsection occt_modalg_8_2 Find Contiguous Edges
-*BRepOffsetAPI_FindContiguousEdges* class is used to find edges, which coincide among a set of shapes within the given tolerance; these edges can be analyzed for tangency, continuity (C1, G2, etc.)...
+Let us define several terms:
+* **Floating edges** do not belong to any face;
+* **Free boundaries** belong to one face only;
+* **Shared edges** belong to several faces, (i.e. two faces in a manifold topology).
+* **Sewn faces** should have edges shared with each other.
+* **Sewn edges** should have vertices shared with each other.
-The constructor takes as arguments the tolerance defining the edge proximity (10-6 by default) and a flag used to mark degenerated shapes.
+@subsection occt_modalg_8_2 Sewing Algorithm
+
+The sewing algorithm is one of the basic algorithms used for shape processing, therefore its quality is very important.
+
+Sewing algorithm is implemented in the class *BRepBuilder_Sewing*. This class provides the following methods:
+* loading initial data for global or local sewing;
+* setting customization parameters, such as special operation modes, tolerances and output results;
+* applying analysis methods that can be used to obtain connectivity data required by external algorithms;
+* sewing of the loaded shapes.
+
+Sewing supports working mode with big value tolerance. It is not necessary to repeat sewing step by step while smoothly increasing tolerance.
+
+It is also possible to sew edges to wire and to sew locally separate faces and edges from a shape.
+
+The Sewing algorithm can be subdivided into several independent stages, some of which can be turned on or off using Boolean or other flags.
+
+In brief, the algorithm should find a set of merge candidates for each free boundary, filter them according to certain criteria, and finally merge the found candidates and build the resulting sewn shape.
+
+Each stage of the algorithm or the whole algorithm can be adjusted with the following parameters:
+* **Working tolerance** defines the maximal distance between topological elements which can be sewn. It is not ultimate that such elements will be actually sewn as many other criteria are applied to make the final decision.
+* **Minimal tolerance** defines the size of the smallest element (edge) in the resulting shape. It is declared that no edges with size less than this value are created after sewing. If encountered, such topology becomes degenerated.
+* **Non-manifold mode** enables sewing of non-manifold topology.
+
+#### Example
+
+To connect a set of *n* contiguous but independent faces, do the following:
+
+~~~~~
+ BRepBuilderAPI_Sewing Sew;
+ Sew.Add(Face1);
+ Sew.Add(Face2);
+ ...
+ Sew.Add(Facen);
+ Sew.Perform();
+ TopoDS_Shape result= Sew.SewedShape();
+~~~~~
-The following methods are used in this class:
-* *Add* adds shapes, which are to be analyzed;
-* *NbEdges* returns the total number of edges;
-* *NbContiguousEdges* returns the number of contiguous edges within the given tolerance as defined above;
-* *ContiguousEdge* takes an edge number as an argument and returns the *TopoDS* edge contiguous to another edge;
-* *ContiguousEdgeCouple* gives all edges or sections, which are common to the edge with the number given above.
-* *SectionToBoundary* finds the original edge on the original shape from the section.
+If all faces have been sewn correctly, the result is a shell. Otherwise, it is a compound. After a successful sewing operation all faces have a coherent orientation.
+
+@subsection occt_modalg_8_3 Tolerance Management
+
+To produce a closed shell, Sewing allows specifying the value of working tolerance, exceeding the size of small faces belonging to the shape.
+
+However, if we produce an open shell, it is possible to get incorrect sewing results if the value of working tolerance is too large (i.e. it exceeds the size of faces lying on an open boundary).
+
+The following recommendations can be proposed for tuning-up the sewing process:
+- Use as small working tolerance as possible. This will reduce the sewing time and, consequently, the number of incorrectly sewn edges for shells with free boundaries.
+- Use as large minimal tolerance as possible. This will reduce the number of small geometry in the shape, both original and appearing after cutting.
+- If it is expected to obtain a shell with holes (free boundaries) as a result of sewing, the working tolerance should be set to a value not greater than the size of the smallest element (edge) or smallest distance between elements of such free boundary. Otherwise the free boundary may be sewn only partially.
+- It should be mentioned that the Sewing algorithm is unable to understand which small (less than working tolerance) free boundary should be kept and which should be sewn.
+
+@subsection occt_modalg_8_4 Manifold and Non-manifold Sewing
+
+To create one or several shells from a set of faces, sewing merges edges, which belong to different faces or one closed face.
+
+Face sewing supports manifold and non manifold modes. Manifold mode can produce only a manifold shell. Sewing should be used in the non manifold mode to create non manifold shells.
+
+Manifold sewing of faces merges only two nearest edges belonging to different faces or one closed face with each other. Non manifold sewing of faces merges all edges at a distance less than the specified tolerance.
+
+For a complex topology it is advisable to apply first the manifold sewing and then the non manifold sewing a minimum possible working tolerance. However, this is not necessary for a easy topology.
+
+Giving a large tolerance value to non manifold sewing will cause a lot of incorrectness since all nearby geometry will be sewn.
+
+@subsection occt_modalg_8_5 Local Sewing
+
+If a shape still has some non-sewn faces or edges after sewing, it is possible to use local sewing with a greater tolerance.
+
+Local sewing is especially good for open shells. It allows sewing an unwanted hole in one part of the shape and keeping a required hole, which is smaller than the working tolerance specified for the local sewing in the other part of the shape. Local sewing is much faster than sewing on the whole shape.
+
+All preexisting connections of the whole shape are kept after local sewing.
+
+For example, if you want to sew two open shells having coincided free edges using local sewing, it is necessary to create a compound from two shells then load the full compound using method *BRepBuilderAPI_Sewing::Load()*. After that it is necessary to add local sub-shapes, which should be sewn using method *BRepBuilderAPI_Sewing::Add()*. The result of sewing can be obtained using method *BRepBuilderAPI_Sewing::SewedShape()*.
+
+See the example:
+
+~~~~
+
+//initial sewn shapes
+TopoDS_Shape aS1, aS2; // these shapes are expected to be well sewn shells
+TopoDS_Shape aComp;
+BRep_Builder aB;
+aB.MakeCompound(aComp);
+aB.Add(aComp, aS1);
+aB.Add(aComp, aS2);
+................................
+aSewing.Load(aComp);
+
+//sub shapes which should be locally sewed
+aSewing.Add(aF1);
+aSewing.Add(aF2);
+//performing sewing
+aSewing.Perform();
+//result shape
+TopoDS_Shape aRes = aSewing.SewedShape();
+
+~~~~
@section occt_modalg_9 Features
-@subsection occt_modalg_9_1 The BRepFeat Classes and their use
-*BRepFeat* package is used to manipulate extensions of the classical boundary representation of shapes closer to features. In that sense, *BRepFeat* is an extension of *BRepBuilderAPI* package.
+This library contained in *BRepFeat* package is necessary for creation and manipulation of form and mechanical features that go beyond the classical boundary representation of shapes. In that sense, *BRepFeat* is an extension of *BRepBuilderAPI* package.
+
+@subsection occt_modalg_9_1 Form Features
+
+The form features are depressions or protrusions including the following types:
+
+ * Cylinder;
+ * Draft Prism;
+ * Prism;
+ * Revolved feature;
+ * Pipe.
+
+Depending on whether you wish to make a depression or a protrusion,
+you can choose either to remove matter (Boolean cut: Fuse equal to 0) or to add it (Boolean fusion: Fuse equal to 1).
-@subsubsection occt_modalg_9_1_1 Form classes
-The *Form* from *BRepFeat* class is a deferred class used as a root for form features. It inherits *MakeShape* from *BRepBuilderAPI* and provides implementation of methods keep track of all sub-shapes.
+The semantics of form feature creation is based on the construction of shapes:
-#### MakePrism
+ * for a certain length in a certain direction;
+ * up to the limiting face;
+ * from the limiting face at a height;
+ * above and/or below a plane.
-*MakePrism* from *BRepFeat* class is used to build a prism interacting with a shape. It is created or initialized from
+The shape defining the construction of a feature can be either a supporting edge or a concerned area of a face.
+
+In case of supporting edge, this contour can be attached to a face of the basis shape by binding. When the contour is bound to this face, the information that the contour will slide on the face becomes available
+to the relevant class methods. In case of the concerned area of a face, you can, for example, cut it out and move it at a different height, which defines the limiting face of a protrusion or depression.
+
+Topological definition with local operations of this sort makes calculations simpler
+and faster than a global operation. The latter would entail a second phase
+of removing unwanted matter to get the same result.
+
+The *Form* from *BRepFeat* package is a deferred class used as a root for form features. It inherits *MakeShape* from *BRepBuilderAPI* and provides implementation of methods keep track of all sub-shapes.
+
+@subsubsection occt_modalg_9_1_1 Prism
+
+The class *BRepFeat_MakePrism* is used to build a prism interacting with a shape. It is created or initialized from
* a shape (the basic shape),
* the base of the prism,
* a face (the face of sketch on which the base has been defined and used to determine whether the base has been defined on the basic shape or not),
@image html /user_guides/modeling_algos/images/modeling_algos_image048.png "Creating a prism between two faces with Perform(From, Until)"
@image latex /user_guides/modeling_algos/images/modeling_algos_image048.png "Creating a prism between two faces with Perform(From, Until)"
-#### MakeDPrism
+@subsubsection occt_modalg_9_1_2 Draft Prism
-*MakeDPrism* from *BRepFeat* class is used to build draft prism topologies interacting with a basis shape . These can be depressions or protrusions. A class object is created or initialized from
+The class *BRepFeat_MakeDPrism* is used to build draft prism topologies interacting with a basis shape. These can be depressions or protrusions. A class object is created or initialized from:
* a shape (basic shape),
* the base of the prism,
* a face (face of sketch on which the base has been defined and used to determine whether the base has been defined on the basic shape or not),
@image html /user_guides/modeling_algos/images/modeling_algos_image049.png "A tapered prism"
@image latex /user_guides/modeling_algos/images/modeling_algos_image049.png "A tapered prism"
-#### MakeRevol
-
-The *MakeRevol* from *BRepFeat* class is used to build a revolution interacting with a
-shape. It is created or initialized from
+@subsubsection occt_modalg_9_1_3 Revolution
+The class *BRepFeat_MakeRevol* is used to build a revolution interacting with a shape. It is created or initialized from:
* a shape (the basic shape,)
* the base of the revolution,
* a face (the face of sketch on which the base has been defined and used to determine whether the base has been defined on the basic shape or not),
}
~~~~~
-#### MakePipe
+@subsubsection occt_modalg_9_1_4 Pipe
-This method constructs compound shapes with pipe features: depressions or protrusions. A class object is created or initialized from
+The class *BRepFeat_MakePipe* constructs compound shapes with pipe features: depressions or protrusions. A class object is created or initialized from:
* a shape (basic shape),
* a base face (profile of the pipe)
* a face (face of sketch on which the base has been defined and used to determine whether the base has been defined on the basic shape or not),
| *Perform(Until)* | The pipe is defined along the path until a given face |
| *Perform(From, Until)* | The pipe is defined between the two faces From and Until |
+Let us have a look at the example:
+
~~~~~
TopoDS_Shape S = BRepPrimAPI_MakeBox(400.,250.,300.);
TopExp_Explorer Ex;
@image html /user_guides/modeling_algos/images/modeling_algos_image050.png "Pipe depression"
@image latex /user_guides/modeling_algos/images/modeling_algos_image050.png "Pipe depression"
+@subsection occt_modalg_9_2 Mechanical Features
-
-@subsubsection occt_modalg_9_1_2 Linear Form
-
-*MakeLinearForm* class creates a rib or a groove along a planar surface.
+Mechanical features include ribs, protrusions and grooves (or slots), depressions along planar (linear) surfaces or revolution surfaces.
The semantics of mechanical features is built around giving thickness to a contour. This thickness can either be symmetrical - on one side of the contour - or dissymmetrical - on both sides. As in the semantics of form features, the thickness is defined by construction of shapes in specific contexts.
* to a limiting face of the basis shape;
* to or from a limiting plane;
* to a height.
+
A class object is created or initialized from
* a shape (basic shape);
* a wire (base of rib or groove);
* direction2 (vector opposite to the previous one along which thickness will be built up, may be null);
* a Boolean indicating the type of operation (fusion=rib or cut=groove) on the basic shape;
* another Boolean indicating if self-intersections have to be found (not used in every case).
-
-There is one *Perform()* method, which performs a prism from the wire along the *direction1* and *direction2* interacting with base shape *Sbase*. The height of the prism is *Magnitude(Direction1)+Magnitude(direction2)*.
+
+@subsubsection occt_modalg_9_2_1 Linear Form
+
+Linear form is implemented in *MakeLinearForm* class, which creates a rib or a groove along a planar surface. There is one *Perform()* method, which performs a prism from the wire along the *direction1* and *direction2* interacting with base shape *Sbase*. The height of the prism is *Magnitude(Direction1)+Magnitude(direction2)*.
~~~~~
BRepBuilderAPI_MakeWire mkw;
@image html /user_guides/modeling_algos/images/modeling_algos_image051.png "Creating a rib"
@image latex /user_guides/modeling_algos/images/modeling_algos_image051.png "Creating a rib"
-@subsubsection occt_modalg_9_1_3 Gluer
+@subsubsection occt_modalg_9_2_3 Gluer
+
+The class *BRepFeat_Gluer* allows gluing two solids along faces. The contact faces of the glued shape must not have parts outside the contact faces of the basic shape. Upon completion the algorithm gives the glued shape with cut out parts of faces inside the shape.
-The *Gluer* from *BRepFeat* class allows gluing two solids along faces. The contact faces of the glued shape must not have parts outside the contact faces of the basic shape.
The class is created or initialized from two shapes: the “glued” shape and the basic shape (on which the other shape is glued).
Two *Bind* methods are used to bind a face of the glued shape to a face of the basic shape and an edge of the glued shape to an edge of the basic shape.
}
~~~~~
-@subsubsection occt_modalg_9_1_4 Split Shape
+@subsubsection occt_modalg_9_2_4 Split Shape
-*SplitShape* from *BRepFeat* class is used to split faces of a shape with wires or edges. The shape containing the new entities is rebuilt, sharing the unmodified ones.
+The class *BRepFeat_SplitShape* is used to split faces of a shape into wires or edges. The shape containing the new entities is rebuilt, sharing the unmodified ones.
The class is created or initialized from a shape (the basic shape).
Three Add methods are available:
To provide the precision required in industrial design, drawings need to offer the possibility of removing lines, which are hidden in a given projection.
-For this the Hidden Line Removal component provides two algorithms: *HLRBRep_Algo* and *HLRBRep_PolyAlgo*.
+For this the Hidden Line Removal component provides two algorithms: *HLRBRep_Algo* and *HLRBRep_PolyAlgo*.
These algorithms are based on the principle of comparing each edge of the shape to be visualized with each of its faces, and calculating the visible and the hidden parts of each edge. Note that these are not the algorithms used in generating shading, which calculate the visible and hidden parts of each face in a shape to be visualized by comparing each face in the shape with every other face in the same shape.
These algorithms operate on a shape and remove or indicate edges hidden by faces. For a given projection, they calculate a set of lines characteristic of the object being represented. They are also used in conjunction with extraction utilities, which reconstruct a new, simplified shape from a selection of the results of the calculation. This new shape is made up of edges, which represent the shape visualized in the projection.
-*HLRBRep_Algo* takes the shape itself into account whereas *HLRBRep_PolyAlgo* works with a polyhedral simplification of the shape. When you use *HLRBRep_Algo*, you obtain an exact result, whereas, when you use *HLRBRep_PolyAlgo*, you reduce the computation time.
+*HLRBRep_Algo* allows working with the shape itself, whereas *HLRBRep_PolyAlgo* works with a polyhedral simplification of the shape. When you use *HLRBRep_Algo*, you obtain an exact result, whereas, when you use *HLRBRep_PolyAlgo*, you reduce the computation time, but obtain polygonal segments.
No smoothing algorithm is provided. Consequently, a polyhedron will be treated as such and the algorithms will give the results in form of line segments conforming to the mathematical definition of the polyhedron. This is always the case with *HLRBRep_PolyAlgo*.
aPolyHLRToShape.OutLineHCompound();
~~~~~
-@section occt_modalg_10_2 Meshing of Shapes
+@section occt_modalg_11 Meshing
+
+@subsection occt_modalg_11_1 Mesh presentations
+
+In addition to support of exact geometrical representation of 3D objects Open CASCADE Technology provides functionality to work with tessellated representations of objects in form of meshes.
+
+Open CASCADE Technology mesh functionality provides:
+- data structures to store surface mesh data associated to shapes, and some basic algorithms to handle these data
+- data structures and algorithms to build surface triangular mesh from *BRep* objects (shapes).
+- tools to extend 3D visualization capabilities of Open CASCADE Technology with displaying meshes along with associated pre- and post-processor data.
+
+Open CASCADE Technology includes two mesh converters:
+- VRML converter translates Open CASCADE shapes to VRML 1.0 files (Virtual Reality Modeling Language). Open CASCADE shapes may be translated in two representations: shaded or wireframe. A shaded representation present shapes as sets of triangles computed by a mesh algorithm while a wireframe representation present shapes as sets of curves.
+- STL converter translates Open CASCADE shapes to STL files. STL (STtereoLithography) format is widely used for rapid prototyping.
+
+Open CASCADE SAS also offers Advanced Mesh Products:
+- <a href="http://www.opencascade.org/support/products/omf">Open CASCADE Mesh Framework (OMF)</a>
+- <a href="http://www.opencascade.org/support/products/emesh">Express Mesh</a>
+
+Besides, we can efficiently help you in the fields of surface and volume meshing algorithms, mesh optimization algorithms etc. If you require a qualified advice about meshing algorithms, do not hesitate to benefit from the expertise of our team in that domain.
+
+The projects dealing with numerical simulation can benefit from using SALOME - an Open Source Framework for CAE with CAD data interfaces, generic Pre- and Post- F.E. processors and API for integrating F.E. solvers.
+
+Learn more about SALOME platform on http://www.salome-platform.org
+
+@subsection occt_modalg_11_2 Meshing algorithm
The algorithm of shape triangulation is provided by the functionality of *BRepMesh_IncrementalMesh* class, which adds a triangulation of the shape to its topological data structure. This triangulation is used to visualize the shape in shaded mode.
BRepMesh_IncrementalMesh aMesh(aShape, aLinearDeflection, Standard_False, anAngularDeflection);
~~~~~
-The default meshing algorithm *BRepMesh_IncrementalMesh* has two major options to define triangulation – linear and angular deflections.
+The default meshing algorithm *BRepMesh_IncrementalMesh* has two major options to define triangulation – linear and angular deflections.
-At the first step all edges from a face are discretized according to the specified parameters.
+At the first step all edges from a face are discretized according to the specified parameters.
At the second step, the faces are tessellated. Linear deflection limits the distance between a curve and its tessellation, whereas angular deflection limits the angle between subsequent segments in a polyline.
However, an application that imports models created in other applications may not use the same deflection for all models. Note that actually this is an abnormal situation and this application is probably just a viewer for CAD models with dimensions varying by an order of magnitude. This problem can be solved by introducing the concept of a relative linear deflection with some LOD (level of detail). The level of detail is a scale factor for absolute deflection, which is applied to model dimensions.
-Meshing covers a shape with a triangular mesh. Other than hidden line removal, you can use meshing to transfer the shape to another tool: a manufacturing tool, a shading algorithm, a finite element algorithm, or a collision algorithm.
+Meshing covers a shape with a triangular mesh. Other than hidden line removal, you can use meshing to transfer the shape to another tool: a manufacturing tool, a shading algorithm, a finite element algorithm, or a collision algorithm.
-You can obtain information on the shape by first exploring it. To access triangulation of a face in the shape later, use *BRepTool::Triangulation*. To access a polygon, which is the approximation of an edge of the face, use *BRepTool::PolygonOnTriangulation*.
+You can obtain information on the shape by first exploring it. To access triangulation of a face in the shape later, use *BRepTool::Triangulation*. To access a polygon, which is the approximation of an edge of the face, use *BRepTool::PolygonOnTriangulation*.
\ No newline at end of file
@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
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.
* 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"
* 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:
* 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:
* 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.
@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,
### 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 :**
- 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,
- 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.
- 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
- 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.
+
+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.
-Packages **GeomLProp**, **Geom2dLProp** provide algorithms calculating the local properties of curves and surfaces
+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
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.
+
+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.
-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
+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.
**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
@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} :
ProcessTheVertexConnectingTheCurrentEdgeToThePrevious
One(Ex.CurrentVertex());
}
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
\ No newline at end of file
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+
@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
@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
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.
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
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.
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.
#### 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;
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);
#### 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);
@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.
+
+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.
+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"
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
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"
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@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
@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
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
@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
@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
@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
@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
@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}
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
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;
* **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
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
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
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:
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.
-
- 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.
+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
+~~~~
- 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
@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.
-
- 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.
+@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.
- 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,
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.
+
@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
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.
@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:
@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.
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:
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.
@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 |
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>
+
+ @figure{/user_guides/xde/images/xde_image006.png, "Colors and Layers"}
- @image html /user_guides/xde/images/xde_image006.png "Colors and Layers"
- @image latex /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.
-
-@subsubsection occt_xde_2_1_1 General Check
+ * 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 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:
~~~~~
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)
// 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.
~~~~~
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.
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
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>
projects / occt.git / commitdiff
