0026478: There is a lack of documentation on OCAF / Topological naming
authorysn <ysn@opencascade.com>
Thu, 10 Sep 2015 14:49:32 +0000 (17:49 +0300)
committerbugmaster <bugmaster@opencascade.com>
Thu, 10 Sep 2015 14:50:32 +0000 (17:50 +0300)
Article content added in @subsection occt_ocaf_5_8 Example of topological naming usage

The description of topological naming mechanism has been added in sub-section 5_6.

dox/user_guides/ocaf/images/ocaf_image020.png [new file with mode: 0644]
dox/user_guides/ocaf/images/ocaf_image021.png [new file with mode: 0644]
dox/user_guides/ocaf/images/ocaf_image022.png [new file with mode: 0644]
dox/user_guides/ocaf/ocaf.md

diff --git a/dox/user_guides/ocaf/images/ocaf_image020.png b/dox/user_guides/ocaf/images/ocaf_image020.png
new file mode 100644 (file)
index 0000000..8919389
Binary files /dev/null and b/dox/user_guides/ocaf/images/ocaf_image020.png differ
diff --git a/dox/user_guides/ocaf/images/ocaf_image021.png b/dox/user_guides/ocaf/images/ocaf_image021.png
new file mode 100644 (file)
index 0000000..f32e884
Binary files /dev/null and b/dox/user_guides/ocaf/images/ocaf_image021.png differ
diff --git a/dox/user_guides/ocaf/images/ocaf_image022.png b/dox/user_guides/ocaf/images/ocaf_image022.png
new file mode 100644 (file)
index 0000000..86bae55
Binary files /dev/null and b/dox/user_guides/ocaf/images/ocaf_image022.png differ
index 012b889..24e3e06 100644 (file)
@@ -687,7 +687,7 @@ If a shape is newly created, then the old shape of a corresponding named shape i
 @image html /user_guides/ocaf/images/ocaf_image013.png
 @image latex /user_guides/ocaf/images/ocaf_image013.png
 
-### Shape attributes in data framework. 
+@subsection occt_ocaf_5_2 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: 
 
@@ -717,9 +717,7 @@ This is necessary and sufficient information for the functionality of the right
 
 After any modification of source boxes the application must automatically rebuild the naming entities: recompute the named shapes of the boxes (solids and faces) and fuse the resulting named shapes (solids and faces) that reference to the new named shapes. 
 
-@subsection occt_ocaf_5_2 Services provided
-
-@subsubsection occt_ocaf_5_2_1 Registering shapes and their evolution
+@subsection occt_ocaf_5_3 Registering shapes and their evolution
 
 When using TNaming_NamedShape to create attributes, the following fields of an attribute are filled: 
 
@@ -733,9 +731,9 @@ When using TNaming_NamedShape to create attributes, the following fields of an a
 
 Only pairs of shapes with equal evolution can be stored in one named shape. 
 
-@subsubsection occt_ocaf_5_2_2 Using naming resources
+@subsection occt_ocaf_5_4 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 creating 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" 
@@ -747,7 +745,8 @@ builder.Generated(oldshape2,newshape2);
 // get the result – TNaming_NamedShape attribute 
 Handle(TNaming_NamedShape) ns = builder.NamedShape(); 
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-@subsubsection occt_ocaf_5_2_3 Reading the contents of a named shape attribute
+
+@subsection occt_ocaf_5_5 Reading the contents of a named shape attribute
 
 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.
   
@@ -775,19 +774,55 @@ iter.Next();
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 
-@subsubsection occt_ocaf_5_2_4 Selection Mechanism
+@subsection occt_ocaf_5_6 Topological naming
+
+The Topological Naming mechanism is based on 3 components:
+* History of the used modeling operation algorithm;
+* Registering of the built result in Data Framework (i.e. loading the necessary elements of the extracted history in OCAF document);
+* Selection / Recomputation of a "selected" sub-shape of the algorithm result.
+
+To get the expected result the work of the three components should be synchronized and the rules of each component should be respected.
+
+@subsubsection occt_ocaf_5_6_1 Algorithm history
+
+The "correct" history of a used modeling operation serves the basis of naming mechanism. It should be provided by the algorithm supporting the operation. The history content depends on the type of the topological result. The purpose of the history is to provide all entities for consistent and correct work of the Selection / Recomputation mechanism. The table below presents expected types of entities depending on the result type.
+
+| Result type |        Type of sub-shapes to be returned by history of algorithm | Comments |
+| :---------- | :-------------------------------------------------------- | :------- |
+| Solid or closed shell        | Faces | All faces |
+| Open shell or single face | Faces and edges of opened boundaries only        | All faces plus all edges of opened boundaries |
+| Closed wire | Edges | All edges |
+| Opened wire |        Edges and ending vertexes | All edges plus ending vertexes of the wire |
+| Edge | Vertexes |    Two vertexes are expected |
+| Compound or CompSolid        | To be used consequentially the above declared rule applied to all sub-shapes of the first level | Compound/CompSolid to be explored level by level until any the mentioned above types will be met | 
+
+The history should return (and track) only elementary types of sub-shapes, i.e. Faces, Edges and Vertexes, while other so-called aggregation types: Compounds, Shells, Wires, are calculated by Selection mechanism automatically.
 
-One of user interfaces for topological naming resources is the *TNaming_Selector* class. You can use this class to: 
+There are some simple exceptions for several cases. For example, if the Result contains a seam edge - in conical, cylindrical or spherical surfaces - this seam edge should be tracked by the history and in addition should be defined before the types. All degenerated entities should be filtered and excluded from consideration.
 
-  * Store a selected shape on a label
-  * Access the named shape
-  * Update this naming
+@subsubsection occt_ocaf_5_6_2 Loading history in data framework
 
-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. 
+All elements returned by the used algorithm according to the aforementioned rules should be put in the Data Framework (or OCAF document in other words) consequently in linear order under the so-called **Result Label**. 
 
-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. 
+The "Result Label" is *TDF_label* used to keep the algorithm result *Shape* from *TopoDS* in *NamedShape* attribute. During loading sub-shapes of the result in Data Framework should be used the rules of chapter @ref occt_ocaf_5_3.  These rules are also applicable for loading the main shape, i.e. the resulting shape produced by the modeling algorithm.
 
-@subsubsection occt_ocaf_5_2_5 Exploring shape evolution
+@subsubsection occt_ocaf_5_6_3 Selection / re-computation mechanism
+
+When the Data Framework is filled with all impacted entities (including the data structures resulting from the current modeling operation and the data structures resulting from the previous modeling operations, on which the current operation depends) any sub-shape of the current result can be **selected**, i.e. the corresponding new naming data structures, which support this functionality, can be produced and kept in the Data Framework.
+
+One of the user interfaces for topological naming is the class *TNaming_Selector*. It implements the above mentioned sub-shape "selection" functionality as an additional one. I.e. it can be used for:
+* Storing the selected shape on a label - its **Selection**;
+* Accessing the named shape – check the kept value of the shape
+* Update of this naming – recomputation of an earlier selected shape.
+
+The selector places a new named shape with evolution **SELECTED** to the given label. The selector creates a **name** of the selected shape, which is a unique description (data structure) of how to find the selected topology using as resources:
+* the given context shape, i.e. the main shape kept on **Result Label**, which contains a selected sub-shape, 
+* its evolution and
+* naming structure.
+
+After any modification of a context shape and update of the corresponding naming structure, it is necessary to call method *TNaming_Selector::Solve*. If the naming structure, i.e. the above mentioned **name**, is correct, the selector automatically updates the selected sub-shape in the corresponding named shape, else it fails.
+
+@subsection occt_ocaf_5_7 Exploring shape evolution
 
 The class *TNaming_Tool* provides a toolkit to read current data contained in the attribute. 
 
@@ -807,6 +842,54 @@ Standard_Boolean CafTest_MyClass::SameEdge (const Handle(CafTest_Line)& L1, cons
 } 
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
+
+@subsection occt_ocaf_5_8 Example of topological naming usage
+
+**Topological naming** is a mechanism of Open CASCADE aimed to keep reference to the selected shape. If, for example, we select a vertex of a solid shape and “ask” the topological naming to keep reference to this vertex, it will refer to the vertex whatever happens with the shape (translations, scaling, fusion with another shape, etc.).
+
+Let us consider an example: imagine a wooden plate. The job is to drive several nails in it:
+
+@figure{/user_guides/ocaf/images/ocaf_image020.png, "A nail driven in a wooden plate"}
+
+There may be several nails with different size and position. A **Hammer** should push each **Nail** exactly in the center point of the top surface. For this the user does the following:
+*      Makes several Nails of different height and diameter (according to the need),
+*      Chooses (selects) the upper surface of each Nail for the Hammer.
+
+The job is done. The application should do the rest – the Hammer calculates a center point for each selected surface of the Nail and “strikes” each Nail driving it into the wooden plate.
+
+What happens if the user changes the position of some Nails? How will the Hammer know about it? It keeps reference to the surface of each Nail. However, if a Nail is relocated, the Hammer should know the new position of the selected surface. Otherwise, it will “strike” at the old position (keep the fingers away!)…
+
+Topological naming mechanism should help the Hammer to obtain the relocated surfaces. The Hammer “asks” the mechanism to “resolve” the selected shapes by calling method *TNaming_Selection::Solve()* and the mechanism “returns” the modified surfaces located at the new position by calling  *TNaming_Selector::NamedShape()*.
+
+The topological naming is represented as a “black box” in the example above. Now it is time to make the box a little more “transparent”.
+
+The application contains 3 functions:
+* **Nail** - produces a shape representing a nail,
+* **Translator** - translates a shape along the wooden plate,
+* **Hammer** - drives the nail in the wooden plate.
+
+Each function gives the topological naming some hints how to “re-solve” the selected sub-shapes:
+* The Nail constructs a solid shape and puts each face of the shape into sub-labels: 
+
+@figure{/user_guides/ocaf/images/ocaf_image021.png, "Distribution of faces through sub-labels of the Nail"}
+
+* The **Translator** moves a shape and registers modification for each face: it puts a pair: “old” shape – “new” shape at a sub-label of each moving Nail. The “old” shape represents a face of the Nail at the initial position. The “new” shape – is the same face, but at a new position:
+
+@figure{/user_guides/ocaf/images/ocaf_image022.png, "Registration of relocation of faces of a Nail"}
+
+How does it work?
+* The Hammer selects a face of a Nail calling *TNaming_Selector::Select()*. This call makes a unique name for the selected shape. In our example, it will be a direct reference to the label of the top face of the Nail (Face 1).
+* When the user moves a Nail along the wooden plate, the Translator registers this modification by putting the pairs: “old” face of the Nail – new face of the Nail into its sub-labels. 
+* When the Hammer calls *TNaming::Solve()*, the topological naming “looks” at the unique name of the selected shape and tries to re-solve it:
+       * It finds the 1st appearance of the selected shape in the data tree – it is a label under the Nail function *Face 1*.
+       * It follows the evolution of this face. In our case, there is only one evolution – the translation: *Face 1* (top face) – <i>Face 1’</i> (relocated top face). So, the last evolution is the relocated top face.
+* Calling the method *TNaming_Selector::NamedShape()* the Hammer obtains the last evolution of the selected face – the relocated top face.
+
+The job is done.
+
+P.S. Let us say a few words about a little more complicated case – selection of a wire of the top face. Its topological name is an “intersection” of two faces. We remember that the **Nail** puts only faces under its label. So, the selected wire will represent an “intersection” of the top face and the conic face keeping the “head” of the nail. Another example is a selected vertex. Its unique name may be represented as an “intersection” of three or even more faces (depends on the shape).
+
+
 @section occt_ocaf_6_ Standard Attributes
 
 @subsection occt_ocaf_6_1 Overview