diff --git a/dox/FILES_HTML.txt b/dox/FILES_HTML.txt index a1ef0b24e6..60df2dcbc7 100644 --- a/dox/FILES_HTML.txt +++ b/dox/FILES_HTML.txt @@ -32,9 +32,6 @@ user_guides/ocaf/ocaf.md user_guides/tobj/tobj.md user_guides/draw_test_harness/draw_test_harness.md user_guides/brep_wp/brep_wp.md -user_guides/ocaf_functionmechanism_wp/ocaf_functionmechanism_wp.md -user_guides/ocaf_tree_wp/ocaf_tree_wp.md -user_guides/ocaf_wp/ocaf_wp.md user_guides/vis/vis.md dev_guides/dev_guides.md diff --git a/dox/FILES_PDF.txt b/dox/FILES_PDF.txt index f4f7ffcdcb..aad07226cc 100644 --- a/dox/FILES_PDF.txt +++ b/dox/FILES_PDF.txt @@ -12,9 +12,6 @@ user_guides/modeling_algos/modeling_algos.md user_guides/boolean_operations/boolean_operations.md user_guides/shape_healing/shape_healing.md user_guides/ocaf/ocaf.md -user_guides/ocaf_functionmechanism_wp/ocaf_functionmechanism_wp.md -user_guides/ocaf_tree_wp/ocaf_tree_wp.md -user_guides/ocaf_wp/ocaf_wp.md user_guides/step/step.md user_guides/draw_test_harness/draw_test_harness.md user_guides/tobj/tobj.md diff --git a/dox/technical_overview/technical_overview.md b/dox/technical_overview/technical_overview.md index f0077cee03..776d707a1c 100644 --- a/dox/technical_overview/technical_overview.md +++ b/dox/technical_overview/technical_overview.md @@ -285,10 +285,7 @@ OCAF differs from any other CAD framework in the organization of application dat OCAF organizes and embeds these attributes in a document. OCAF documents, in their turn, are managed by an OCAF application. -For more details see @ref occt_user_guides__ocaf "OCAF User's Guide" and the OCAF white papers: -* @ref occt_user_guides__ocaf_wp "Application Framework" -* @ref occt_user_guides__ocaf_tree_wp "Distribution of Data through OCAF Tree" -* @ref occt_user_guides__ocaf_functionmechanism_wp "Application Framework Function Mechanism" +For more details see @ref occt_user_guides__ocaf "OCAF User's Guide". See also: our E-learning & Training offerings. diff --git a/dox/user_guides/ocaf_functionmechanism_wp/images/ocaf_functionmechanism_wp_image003.png b/dox/user_guides/ocaf/images/ocaf_functionmechanism_wp_image003.png similarity index 100% rename from dox/user_guides/ocaf_functionmechanism_wp/images/ocaf_functionmechanism_wp_image003.png rename to dox/user_guides/ocaf/images/ocaf_functionmechanism_wp_image003.png diff --git a/dox/user_guides/ocaf_functionmechanism_wp/images/ocaf_functionmechanism_wp_image005.png b/dox/user_guides/ocaf/images/ocaf_functionmechanism_wp_image005.png similarity index 100% rename from dox/user_guides/ocaf_functionmechanism_wp/images/ocaf_functionmechanism_wp_image005.png rename to dox/user_guides/ocaf/images/ocaf_functionmechanism_wp_image005.png diff --git a/dox/user_guides/ocaf/images/ocaf_image009.png b/dox/user_guides/ocaf/images/ocaf_image009.png deleted file mode 100644 index 2605b03e06..0000000000 Binary files a/dox/user_guides/ocaf/images/ocaf_image009.png and /dev/null differ diff --git a/dox/user_guides/ocaf_tree_wp/images/ocaf_tree_wp_image003.png b/dox/user_guides/ocaf/images/ocaf_tree_wp_image003.png similarity index 100% rename from dox/user_guides/ocaf_tree_wp/images/ocaf_tree_wp_image003.png rename to dox/user_guides/ocaf/images/ocaf_tree_wp_image003.png diff --git a/dox/user_guides/ocaf_tree_wp/images/ocaf_tree_wp_image004.png b/dox/user_guides/ocaf/images/ocaf_tree_wp_image004.png similarity index 100% rename from dox/user_guides/ocaf_tree_wp/images/ocaf_tree_wp_image004.png rename to dox/user_guides/ocaf/images/ocaf_tree_wp_image004.png diff --git a/dox/user_guides/ocaf_tree_wp/images/ocaf_tree_wp_image005.png b/dox/user_guides/ocaf/images/ocaf_tree_wp_image005.png similarity index 100% rename from dox/user_guides/ocaf_tree_wp/images/ocaf_tree_wp_image005.png rename to dox/user_guides/ocaf/images/ocaf_tree_wp_image005.png diff --git a/dox/user_guides/ocaf_tree_wp/images/ocaf_tree_wp_image006.png b/dox/user_guides/ocaf/images/ocaf_tree_wp_image006.png similarity index 100% rename from dox/user_guides/ocaf_tree_wp/images/ocaf_tree_wp_image006.png rename to dox/user_guides/ocaf/images/ocaf_tree_wp_image006.png diff --git a/dox/user_guides/ocaf_wp/images/ocaf_wp_image003.png b/dox/user_guides/ocaf/images/ocaf_wp_image003.png similarity index 100% rename from dox/user_guides/ocaf_wp/images/ocaf_wp_image003.png rename to dox/user_guides/ocaf/images/ocaf_wp_image003.png diff --git a/dox/user_guides/ocaf_wp/images/ocaf_wp_image005.png b/dox/user_guides/ocaf/images/ocaf_wp_image005.png similarity index 100% rename from dox/user_guides/ocaf_wp/images/ocaf_wp_image005.png rename to dox/user_guides/ocaf/images/ocaf_wp_image005.png diff --git a/dox/user_guides/ocaf_wp/images/ocaf_wp_image006.png b/dox/user_guides/ocaf/images/ocaf_wp_image006.png similarity index 100% rename from dox/user_guides/ocaf_wp/images/ocaf_wp_image006.png rename to dox/user_guides/ocaf/images/ocaf_wp_image006.png diff --git a/dox/user_guides/ocaf/images/ocaf_wp_image007.png b/dox/user_guides/ocaf/images/ocaf_wp_image007.png new file mode 100644 index 0000000000..b57cd24ed5 Binary files /dev/null and b/dox/user_guides/ocaf/images/ocaf_wp_image007.png differ diff --git a/dox/user_guides/ocaf/ocaf.md b/dox/user_guides/ocaf/ocaf.md index 5ff36cd73f..0b9b3c446b 100644 --- a/dox/user_guides/ocaf/ocaf.md +++ b/dox/user_guides/ocaf/ocaf.md @@ -9,21 +9,33 @@ This manual explains how to use the Open CASCADE Application Framework (OCAF). It provides basic documentation on using OCAF. For advanced information on OCAF and its applications, see our E-learning & Training offerings. -OCAF (the Open CASCADE Application Framework) is a RAD (Rapid Application Development) framework used for -specifying and organizing application data. To do this, OCAF provides: +@subsection occt_ocaf_1_1 Purpose of OCAF - * Ready-to-use data common to most CAD/CAM applications, - * A scalable extension protocol for implementing new application specific data, - * An infrastructure - * To attach any data to any topological element - * To link data produced by different applications (*associativity of data*) - * To register the modeling process - the creation history, or parametrics, used to carry out the modifications. +OCAF (the Open CASCADE Application Framework) is an easy-to-use platform for rapidly developing + sophisticated domain-specific design applications. + A typical application developed using OCAF deals with two or three-dimensional (2D or 3D) geometric modeling + in trade-specific Computer Aided Design (CAD) systems, manufacturing or analysis applications, + simulation applications or illustration tools. + + Developing a design application requires addressing many technical aspects. + In particular, given the functional specification of your application, you must at least: + + * Design the architecture of the application — definition of the software components and the way they cooperate; + * Define the data model able to support the functionality required — a design application operates on data maintained during the whole end-user working session; + * Structure the software in order to: + * synchronize the display with the data — commands modifying objects must update the views; + * support generalized undo-redo commands — this feature has to be taken into account very early in the design process; + * Implement the function for saving the data — if the application has a long life cycle, the compatibility of data between versions of the application has to be addressed; + * Build the application user interface. + +Architectural guidance and ready-to-use solutions provided by OCAF offer you the following benefits: + * You can concentrate on the functionality specific for your application; + * The underlying mechanisms required to support the application are already provided; + * The application can be rapidly be prototyped thanks to the coupling the other Open CASCADE Technology modules; + * The final application can be developed by industrializing the prototype — you don't need to restart the development from scratch. + * The Open Source nature of the platform guarantees the long-term usefulness of your development. -Using OCAF, the application designer concentrates on the functionality and its specific algorithms. In this way, he avoids architectural problems notably implementing Undo-redo and saving application data. - -In OCAF, all of the above are already handled for the application designer, allowing him to reach a significant increase in productivity. - -In this respect, OCAF is much more than just one toolkit among many in the CAS.CADE Object Libraries. Since it can handle any data and algorithms in these libraries - be it modeling algorithms, topology or geometry - OCAF is a logical supplement to these libraries. +OCAF is much more than just one toolkit among many in the CAS.CADE Object Libraries. Since it can handle any data and algorithms in these libraries - be it modeling algorithms, topology or geometry - OCAF is their logical supplement. The table below contrasts the design of a modeling application using object libraries alone and using OCAF. @@ -39,137 +51,155 @@ The table below contrasts the design of a modeling application using object libr | Undo-Redo | Robust, multi-level | To be created by the user | Provided | | Application-specific dialog boxes | | To be created by the user | To be created by the user | - +OCAF uses other modules of Open CASCADE Technology — the Shape is implemented with the geometry supported by the Modeling Data module and the viewer is the one provided with the Visualization module. Modeling functions can be implemented using the Modeling Algorithms module. The relationship between OCAF and the Open CASCADE Technology (**OCCT**) Object Libraries can be seen in the image below. -@figure{/user_guides/ocaf/images/ocaf_image003.svg, "OCAF Architecture"} +@figure{/user_guides/ocaf/images/ocaf_image003.svg, "OCCT Architecture"} In the image, the OCAF (Open CASCADE Application Framework) is shown with black rectangles and OCCT Object Libraries required by OCAF are shown with white rectangles. - + The subsequent chapters of this document explain the concepts and show how to use the services of OCAF. -@section occt_ocaf_2 Basic Concepts +@subsection occt_ocaf_1_2 Architecture Overview -@subsection occt_ocaf_2_1 Overview +OCAF provides you with an object-oriented Application-Document-Attribute model consisting of C++ class libraries. -In most existing geometric modeling systems, the data structure is shape driven. They usually use a brep model, where solids and surfaces are defined by a collection of entities such as faces, edges etc., and by attributes such as application data. These attributes are attached to the entities. Examples of application data include: +@image html ocaf_wp_image003.png "The Application-Document-Attribute model " +@image latex ocaf_wp_image003.png "The Application-Document-Attribute model " - * color, - * material, - * information that a particular edge is blended. +@subsubsection occt_ocaf_1_2_1 Application -A shape, however, is inevitably tied to its underlying geometry. And geometry is highly subject to change in applications such as parametric modeling or product development. In this sort of application, using a brep (boundary representation) data structure proves to be a not very effective solution. A solution other than the shape must be found, i.e. a solution where attributes are attached to a deeper invariant structure of the model. Here, the topology itself will be one attribute among many. - -In OCAF, data structure is reference key-driven. The reference key is implemented in the form of labels. Application data is attached to these labels as attributes. By means of these labels and a tree structure they are organized in, the reference key aggregates all user data, not just shapes and their geometry. These attributes have similar importance; no attribute is master in respect of the others. - -The reference keys of a model - in the form of labels - have to be kept together in a single container. This container is called a document. - -@image html /user_guides/ocaf/images/ocaf_image004.png "Topology-driven vs. reference key-driven approaches" -@image latex /user_guides/ocaf/images/ocaf_image004.png "Topology-driven vs. reference key-driven approaches" - -@subsection occt_ocaf_2_2 Applications and documents - -OCAF documents are in turn managed by an OCAF application, which is in charge of: - - * Creating new documents - * Saving documents and opening them +The *Application* is an abstract class in charge of handling documents during the working session, namely: + * Creating new documents; + * Saving documents and opening them; * Initializing document views. - -Apart from their role as a container of application data, documents can refer to each other; Document A, for example, can refer to a specific label in Document B. This functionality is made possible by means of the reference key. - -@subsection occt_ocaf_2_3 The document and the data framework - -Inside a document, there is a data framework, a model, for example. This is a set of labels organized in a tree structure characterized by the following features: - * The first label in a framework is the root of the tree; - * Each label has a tag expressed as an integer value; - * Sub-labels of a label are called its children; - * Each label which is not the root has one father – label from an upper level of the framework; - * Labels which have the same father are called brothers; - * Brothers cannot share the same tag; - * A label is uniquely defined by an entry expressed as a list of tags (entry) of fathers from the root: this list of tags is written from right to left: tag of label, tag of its father, tag of father of its father,..., 0 (tag of the root label). -@image html /user_guides/ocaf/images/ocaf_image005.png "A simple framework model" -@image latex /user_guides/ocaf/images/ocaf_image005.png "A simple framework model" - -In the above figure inside the circles are the tags of corresponding labels. Under the circles are the lists of tags. The root label always has a zero tag. - -The children of a root label are middle-level labels with tags 1 and 3. These labels are brothers. - -List of tags of the right-bottom label is "0:3:4": this label has tag 4, its father (with entry "0:3") has tag 3, father of father has tag 0 (the root label always has "0" entry). - -For example, an application for designing table lamps will first allocate a label for the lamp unit (the lamp is illustrated below). The root label never has brother labels, so, for a lot of lamps in the framework allocation, one of the root label sub-labels for the lamp unit is used. By doing so, you would avoid any confusion between table lamps in the data framework. Parts of the lamp have different material, color and other attributes, so, for each sub-unit of the lamp a child label of the lamp label with specified tags is allocated: - - * a lamp-shade label with tag 1 - * a bulb label with tag 2 - * a stem label with tag 3 - -Label tags are chosen at will. They are just identifiers of the lamp parts. Now you can refine all units: set to the specified label geometry, color, material and other information about the lamp or it’s parts. This information is placed into special attributes of the label: the pure label contains no data – it is only a key to access data. - -The thing to remember is that tags are private addresses without any meaning outside the data framework. It would, for instance, be an error to use part names as tags. These might change or be removed from production in next versions of the application, whereas the exact form of that part might be what you wanted to use in your design, the part name could be integrated into the framework as an attribute. - -@image html /user_guides/ocaf/images/ocaf_image006.png -@image latex /user_guides/ocaf/images/ocaf_image006.png - -So, after the user changes the lamp design, only corresponding attributes are changed, but the label structure is maintained. The lamp shape must be recreated by new attribute values and attributes of the lamp shape must refer to a new shape. - -@image html /user_guides/ocaf/images/ocaf_image007.png -@image latex /user_guides/ocaf/images/ocaf_image007.png - - -The previous figure shows the table-lamps document structure: each child of the root label contains a lamp shape attribute and refers to the sub-labels, which contain some design information about corresponding sub-units. - -The data framework structure allows to create more complex structures: each lamp label sub-label may have children labels with more detailed information about parts of the table lamp and its components. - -Note that the root label can have attributes too, usually global attributes: the name of the document, for example. - -As in the case of the table lamp example above, OCAF documents aggregate a battery of ready-to-use attributes, which represent typical data used in CAD. This data includes not only the Shape attribute, but a wide range of Standard attributes corresponding to the following types: - - * Geometric attributes - * General attributes - * Relationship attributes - * Auxiliary attributes - -@subsubsection occt_ocaf_2_3_1 Documents - -Documents offer access to the data framework and manage the following items: +@subsubsection occt_ocaf_1_2_2 Document + + The document, implemented by the concrete class *Document*, is the container for the application data. Documents offer access to the data framework and serve the following purposes: * Manage the notification of changes * Update external links * Manage the saving and restoring of data * Store the names of software extensions. * Manage command transactions - * Manage Undo and Redo options. + * Manage Undo and Redo options. + + Each document is saved in a single flat ASCII file defined by its format and extension (a ready-to-use format is provided with OCAF). -@subsubsection occt_ocaf_2_3_2 Shape attribute + Apart from their role as a container of application data, documents can refer to each other; Document A, for example, can refer to a specific label in Document B. This functionality is made possible by means of the reference key. + +@subsubsection occt_ocaf_1_2_3 Attribute -The shape attribute implements the functionality of the OCCT topology manipulation: - * reference to the shapes - * tracking of shape evolution + Application data is described by **Attributes**, which are instances of classes derived from the *Attribute* abstract class, organized according to the OCAF Data Framework. + + The OCAF Data Framework references aggregations of attributes using persistent identifiers in a single hierarchy. A wide range of attributes come with OCAF, including: + + * Standard attributes allow operating with simple common data in the data framework (for example: integer, real, string, array kinds of data), realize auxiliary functions (for example: tag sources attribute for the children of the label counter), create dependencies (for example: reference, tree node)....; + * Shape attributes contain the geometry of the whole model or its elements including reference to the shapes and tracking of shape evolution; + * Other geometric attributes such as **Datums** (points, axis and plane) and **Constraints** (*tangent-to, at-a-given-distance, from-a-given-angle, concentric,* etc.) + * User attributes, that is, attributes typed by the application + * Visualization attributes allow placing viewer information to the data framework, visual representation of objects and other auxiliary visual information, which is needed for graphical data representation. + * Function services — the purpose of these attributes is to rebuild objects after they have been modified (parameterization of models). While the document manages the notification of changes, a function manages propagation of these changes. The function mechanism provides links between functions and calls to various algorithms. + +In addition, application-specific data can be added by defining new attribute classes; naturally, this changes the standard file format. The only functions that have to be implemented are: + * Copying the attribute + * Converting it from and to its persistent homologue (persistence is briefly presented in the paragraph Persistent Data Storage) + +@subsection occt_ocaf_1_3 Reference-key model -@subsubsection occt_ocaf_2_3_3 Standard attributes + In most existing geometric modeling systems, the data are topology driven. + They usually use a boundary representation (BRep), where geometric models + are defined by a collection of faces, edges and vertices, + to which application data are attached. Examples of data include: + + * a color; + * a material; + * information that a particular edge is blended. + + When the geometric model is parameterized, that is, when you can change + the value of parameters used to build the model (the radius of a blend, the thickness of a rib, etc.), + the geometry is highly subject to change. + In order to maintain the attachment of application data, the geometry must be distinguished from other data. + + In OCAF, the data are reference-key driven. It is a uniform model in which reference-keys + are the persistent identification of data. All **accessible** data, including the geometry, + are implemented as attributes attached to reference-keys. + The geometry becomes the value of the Shape attribute, just as a number is the value + of the Integer and Real attributes and a string that of the Name attribute. + + On a single reference-key, many attributes can be aggregated; + the application can ask at runtime which attributes are available. + For example, to associate a texture to a face in a geometric model, + both the face and the texture are attached to the same reference-key. + +@image html ocaf_image004.png "Topology driven versus reference-key driven approaches" +@image latex ocaf_image004.png "Topology driven versus reference-key driven approaches" -Several ready-to-use base attributes already exist. These allow operating with simple common data in the data framework (for example: integer, real, string, array kinds of data), realize auxiliary functions (for example: tag sources attribute for the children of the label counter), create dependencies (for example: reference, tree node).... + Reference-keys can be created in two ways: + + * At programming time, by the application + * At runtime, by the end-user of the application (providing that you include this capability in the application) + + As an application developer, you generate reference-keys in order to give semantics to the data. + For example, a function building a prism may create three reference-keys: + one for the base of the prism, a second for the lateral faces and a third for the top face. + This makes up a semantic built-in the application's prism feature. + On the other hand, in a command allowing the end-user to set a texture to a face he/she selects, + you must create a reference-key to the selected face + if it has not previously been referenced in any feature + (as in the case of one of the lateral faces of the prism). + + When you create a reference-key to selected topological elements (faces, edges or vertices), + OCAF attaches to the reference-key information defining the selected topology — the Naming attribute. + For example, it may be the faces to which a selected edge is common to. + This information, as well as information about the evolution of the topology at each modeling step + (the modified, updated and deleted faces), is used by the naming algorithm to maintain the topology + attached to the reference-key. As such, on a parametrized model, + after modifying the value of a parameter, the reference-keys still address the appropriate faces, + even if their geometry has changed. + Consequently, you change the size of the cube shown in the figure 2 above, + the user texture stay attached to the right face. + + Note As Topological naming is based on the reference-key and attributes such as Naming + (selection information) and Shape (topology evolution information), + OCAF is not coupled to the underlying modeling libraries. + The only modeling services required by OCAF are the following: -@subsubsection occt_ocaf_2_3_4 Visualization attributes + * Each algorithm must provide information about the evolution of the topology + (the list of faces modified, updated and deleted by the algorithm) + * Exploration of the geometric model must be available + (a 3D model is made of faces bounded by close wires, + themselves composed by a sequence of edges connected by their vertices) + + Currently, OCAF uses the Open CASCADE Technology modeling libraries. + + To design an OCAF-based data model, the application developer is encouraged to aggregate + ready-to-use attributes instead of defining new attributes by inheriting from an abstract root class. + There are two major advantages in using aggregation rather than inheritance: + + * As you don't implement data by defining new classes, the format of saved data + provided with OCAF doesn't change; so you don't have to write the Save and Open functions + * The application can query the data at runtime if a particular attribute is available + +**Summary** -These attributes allow placing viewer information to the data framework, visual representation of objects and other auxiliary visual information, which is needed for graphical data representation. - -@subsubsection occt_ocaf_2_3_5 Function services - -Where the document manages the notification of changes, a function manages propagation of these changes. The function mechanism provides links between functions and calls to various algorithms. - -@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 - -The data framework offers a single environment in which data from different application components can be handled. - -This allows you to exchange and modify data simply, consistently, with a maximum level of information, and with stable semantics. + * OCAF is based on a uniform reference-key model in which: + * Reference-keys provide persistent identification of data; + * Data, including geometry, are implemented as attributes attached to reference-keys; + * Topological naming maintains the selected geometry attached to reference-keys in parametrized models; + * In many applications, the data format provided with OCAF doesn't need to be extended; + * OCAF is not coupled to the underlying modeling libraries. + + +@section occt_ocaf_3 The Data Framework + +@subsection occt_ocaf_3_1 Data Structure + + The OCAF Data Framework is the Open CASCADE Technology realization + of the reference-key model in a tree structure. It offers a single environment where data from different application components can be handled. This allows exchanging and modifying data simply, consistently, with a maximum level of information and stable semantics. + The building blocks of this approach are: @@ -184,11 +214,74 @@ Each label can have a list of attributes, which contain data, and several attrib The sub-labels of a label are called its children. Conversely, each label, which is not the root, has a father. Brother labels cannot share the same tag. The most important property is that a label’s entry is its persistent address in the data framework. + +@image html /user_guides/ocaf/images/ocaf_image005.png "A simple framework model" +@image latex /user_guides/ocaf/images/ocaf_image005.png "A simple framework model" -@image html /user_guides/ocaf/images/ocaf_image009.png "Contents of a document" -@image latex /user_guides/ocaf/images/ocaf_image009.png "Contents of a document" +In this image the circles contain tags of the corresponding labels. The lists of tags are located under the circles. The root label always has a zero tag. -@subsection occt_ocaf_3_2 The Tag +The children of a root label are middle-level labels with tags 1 and 3. These labels are brothers. + +List of tags of the right-bottom label is "0:3:4": this label has tag 4, its father (with entry "0:3") has tag 3, father of father has tag 0 (the root label always has "0" entry). + +@subsection occt_ocaf_3_2 Examples of a Data Structure + +Let's have a look at the example: + +@image html ocaf_wp_image007.png "The coffee machine" +@image latex ocaf_wp_image007.png "The coffee machine" + + In the image the application for designing coffee machines first allocates + a label for the machine unit. It then adds sub-labels for the main features + (glass coffee pot, water receptacle and filter) which it refines as needed + (handle and reservoir of the coffee pot and spout of the reservoir). + + You now attach technical data describing the handle — its geometry and color — + and the reservoir — its geometry and material. + Later on, you can modify the handle's geometry without changing its color — + both remain attached to the same label. + +@image html ocaf_wp_image005.png "The data structure of the coffee machine" +@image latex ocaf_wp_image005.png "The data structure of the coffee machine" + + The nesting of labels is key to OCAF. This allows a label to have its own structure + with its local addressing scheme which can be reused in a more complex structure. + Take, for example, the coffee machine. Given that the coffee pot's handle has a label of tag [1], + the entry for the handle in the context of the coffee pot only (without the machine unit) is [0:1:1]. + If you now model a coffee machine with two coffee pots, one at the label [1], + the second at the label [4] in the machine unit, + the handle of the first pot would have the entry [0:1:1:1] + whereas the handle of the second pot would be [0:1:4:1]. + This way, we avoid any confusion between coffee pot handles. + +Another example is the application for designing table lamps. The first label is allocated to the lamp unit. + +@image html /user_guides/ocaf/images/ocaf_image006.png +@image latex /user_guides/ocaf/images/ocaf_image006.png + +The root label cannot have brother labels. Consequently, various lamps in the framework allocation correspond to the sub-labels of the root label. This allows avoiding any confusion between table lamps in the data framework. Different lamp parts have different material, color and other attributes, so a child label of the lamp with the specified tags is allocated for each sub-unit of the lamp: + + * a lamp-shade label with tag 1 + * a bulb label with tag 2 + * a stem label with tag 3 + +Label tags are chosen at will. They are only identifiers of the lamp parts. Now you can refine all units: by setting geometry, color, material and other information about the lamp or its parts to the specified label. This information is placed into special attributes of the label: the pure label contains no data – it is only a key to access data. + +Remember that tags are private addresses without any meaning outside the data framework. It would, for instance, be an error to use part names as tags. These might change or be removed from production in next versions of the application, whereas the exact form of that part might be reused in your design, the part name could be integrated into the framework as an attribute. + +So, after the user changes the lamp design, only corresponding attributes are changed, but the label structure is maintained. The lamp shape must be recreated by new attribute values and attributes of the lamp shape must refer to a new shape. + +@image html /user_guides/ocaf/images/ocaf_image007.png +@image latex /user_guides/ocaf/images/ocaf_image007.png + + +The previous figure shows the table-lamps document structure: each child of the root label contains a lamp shape attribute and refers to the sub-labels, which contain some design information about corresponding sub-units. + +The data framework structure allows to create more complex structures: each lamp label sub-label may have children labels with more detailed information about parts of the table lamp and its components. + +Note that the root label can have attributes too, usually global attributes: the name of the document, for example. + +@subsection occt_ocaf_3_3 Tag A tag is an integer, which identifies a label in two ways: @@ -208,7 +301,7 @@ The tag can be created in two ways: As the names suggest, in random delivery, the tag value is generated by the system in a random manner. In user-defined delivery, you assign it by passing the tag as an argument to a method. -@subsubsection occt_ocaf_3_2_1 Creating child labels using random delivery of tags +@subsubsection occt_ocaf_3_3_1 Creating child labels using random delivery of tags To append and return a new child label, you use *TDF_TagSource::NewChild*. In the example below, the argument *level2*, which is passed to *NewChild,* is a *TDF_Label*. @@ -218,7 +311,7 @@ TDF_Label child1 = TDF_TagSource::NewChild (level2); TDF_Label child2 = TDF_TagSource::NewChild (level2); ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -@subsubsection occt_ocaf_3_2_2 Creation of a child label by user delivery from a tag +@subsubsection occt_ocaf_3_3_2 Creation of a child label by user delivery from a tag The other way to create a child label from a tag is by user delivery. In other words, you specify the tag, which you want your child label to have. @@ -232,7 +325,7 @@ Standard_Integer tag = achild.Tag(); } ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -@subsection occt_ocaf_3_3 The Label +@subsection occt_ocaf_3_4 Label The tag gives a persistent address to a label. The label – the semantics of the tag – is a place in the data framework where attributes, which contain data, are attached. The data framework is, in fact, a tree of labels with a root as the ultimate father label (refer to the following figure): @@ -242,11 +335,11 @@ The tag gives a persistent address to a label. The label – the semantics of th Label can not be deleted from the data framework, so, the structure of the data framework that has been created can not be removed while the document is opened. Hence any kind of reference to an existing label will be actual while an application is working with the document. -@subsubsection occt_ocaf_3_3_1 Label creation +@subsubsection occt_ocaf_3_4_1 Label creation Labels can be created on any labels, compared with brother labels and retrieved. You can also find their depth in the data framework (depth of the root label is 0, depth of child labels of the root is 1 and so on), whether they have children or not, relative placement of labels, data framework of this label. The class *TDF_Label* offers the above services. -@subsubsection occt_ocaf_3_3_2 Creating child labels +@subsubsection occt_ocaf_3_4_2 Creating child labels To create a new child label in the data framework using explicit delivery of tags, use *TDF_Label::FindChild*. @@ -267,7 +360,7 @@ You could also use the same syntax but add the Boolean *true* as a value of the TDF_Label level1 = root.FindChild(3,Standard_True); TDF_Label level2 = level1.FindChild(1,Standard_True); ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -@subsubsection occt_ocaf_3_3_3 Retrieving child labels +@subsubsection occt_ocaf_3_4_3 Retrieving child labels You can retrieve child labels of your current label by iteration on the first level in the scope of this label. @@ -305,7 +398,7 @@ void DumpChildren(const TDF_Label& aLabel) } } ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -@subsubsection occt_ocaf_3_3_4 Retrieving the father label +@subsubsection occt_ocaf_3_4_4 Retrieving the father label Retrieving the father label of a current label. @@ -314,13 +407,14 @@ Retrieving the father label of a current label. TDF_Label father = achild.Father(); isroot = father.IsRoot(); ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -@subsection occt_ocaf_3_4 The Attribute + +@subsection occt_ocaf_3_5 Attribute The label itself contains no data. All data of any type whatsoever - application or non-application - is contained in attributes. These are attached to labels, and there are different types for different types of data. OCAF provides many ready-to-use standard attributes such as integer, real, constraint, axis and plane. There are also attributes for topological naming, functions and visualization. Each type of attribute is identified by a GUID. The advantage of OCAF is that all of the above attribute types are handled in the same way. Whatever the attribute type is, you can create new instances of them, retrieve them, attach them to and remove them from labels, "forget" and "remember" the attributes of a particular label. -@subsubsection occt_ocaf_3_4_1 Retrieving an attribute from a label +@subsubsection occt_ocaf_3_5_1 Retrieving an attribute from a label To retrieve an attribute from a label, you use *TDF_Label::FindAttribute*. In the example below, the GUID for integer attributes, and *INT*, a handle to an attribute are passed as arguments to *FindAttribute* for the current label. @@ -335,7 +429,7 @@ else // the attribute is not found } ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -@subsubsection occt_ocaf_3_4_2 Identifying an attribute using a GUID +@subsubsection occt_ocaf_3_5_2 Identifying an attribute using a GUID You can create a new instance of an attribute and retrieve its GUID. In the example below, a new integer attribute is created, and its GUID is passed to the variable *guid* by the method ID inherited from *TDF_Attribute*. @@ -345,7 +439,7 @@ Handle(TDataStd_Integer) INT = new TDataStd_Integer(); Standard_GUID guid = INT->ID(); ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -@subsubsection occt_ocaf_3_4_3 Attaching an attribute to a label +@subsubsection occt_ocaf_3_5_3 Attaching an attribute to a label To attach an attribute to a label, you use *TDF_Label::Add*. Repetition of this syntax raises an error message because there is already an attribute with the same GUID attached to the current label. @@ -357,7 +451,7 @@ current.Add (INT); // INT is now attached to current current.Add (INT); // causes failure TDF_Label attach = INT->Label(); ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -@subsubsection occt_ocaf_3_4_4 Testing the attachment to a label +@subsubsection occt_ocaf_3_5_4 Testing the attachment to a label You can test whether an attribute is attached to a label or not by using *TDF_Attribute::IsA* with the GUID of the attribute as an argument. In the example below, you test whether the current label has an integer attribute, and then, if that is so, how many attributes are attached to it. *TDataStd_Integer::GetID* provides the GUID argument needed by the method IsAttribute. @@ -376,7 +470,7 @@ Standard_Integer nbatt = current.NbAttributes(); // the label has nbatt attributes attached } ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -@subsubsection occt_ocaf_3_4_5 Removing an attribute from a label +@subsubsection occt_ocaf_3_5_5 Removing an attribute from a label To remove an attribute from a label, you use *TDF_Label::Forget* with the GUID of the deleted attribute. To remove all attributes of a label, *TDF_Label::ForgetAll*. @@ -387,7 +481,7 @@ current.Forget(TDataStd_Integer::GetID()); current.ForgetAll(); // current has now 0 attributes attached ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -@subsubsection occt_ocaf_3_4_6 Specific attribute creation +@subsubsection occt_ocaf_3_5_6 Specific attribute creation If the set of existing and ready to use attributes implementing standard data types does not cover the needs of a specific data presentation task, the user can build his own data type and the corresponding new specific attribute implementing this new data type. @@ -455,6 +549,54 @@ If the type of transformation is changed to rotation, the data tree looks like t @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). + +@subsection occt_ocaf_3_6 Compound documents + + As the identification of data is persistent, one document can reference data contained in another document, + the referencing and referenced documents being saved in two separate files. + + Lets look at the coffee machine application again. The coffee pot can be placed in one document. + The coffee machine document then includes an *occurrence* — a positioned copy — of the coffee pot. + This occurrence is defined by an XLink attribute (the external Link) + which references the coffee pot of the first document + (the XLink contains the relative path of the coffee pot document and the entry of the coffee pot data [0:1] ). + +@image html ocaf_wp_image006.png "The coffee machine compound document" +@image latex ocaf_wp_image006.png "The coffee machine compound document" + + In this context, the end-user of the coffee machine application can open the coffee pot document, + modify the geometry of, for example, the reservoir, and overwrite the document without worrying + about the impact of the modification in the coffee machine document. + To deal with this situation, OCAF provides a service which allows the application to check + whether a document is up-to-date. This service is based on a modification counter included in each document: + when an external link is created, a copy of the referenced document counter is associated to the XLink + in the referencing document. Providing that each modification of the referenced document increments its own counter, + we can detect that the referencing document has to be updated by comparing the two counters + (an update function importing the data referenced by an XLink into the referencing document is also provided). + + @subsection occt_ocaf_3_7 Transaction mechanism + + The Data Framework also provides a transaction mechanism inspired from database management systems: + the data are modified within a transaction which is terminated either by a Commit + if the modifications are validated or by an Abort if the modifications are abandoned — + the data are then restored to the state it was in prior to the transaction. + This mechanism is extremely useful for: + + * Securing editing operations (if an error occurs, the transaction is abandoned and the structure retains its integrity) + * Simplifying the implementation of the **Cancel** function (when the end-user begins a command, + the application may launch a transaction and operate directly in the data structure; + abandoning the action causes the transaction to Abort) + * Executing **Undo** (at commit time, the modifications are recorded in order to be able to restore the data to their previous state) + + The transaction mechanism simply manages a backup copy of attributes. + During a transaction, attributes are copied before their first modification. + If the transaction is validated, the copy is destroyed. + If the transaction is abandoned, the attribute is restored to its initial value + (when attributes are added or deleted, the operation is simply reversed). + + Transactions are document-centered, that is, the application starts a transaction on a document. + So, modifying a referenced document and updating one of its referencing documents requires + two transactions, even if both operations are done in the same working session. @section occt_ocaf_4_ Standard Document Services @@ -672,7 +814,7 @@ XLinkTool.Copy(target, source); ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -@section occt_ocaf_5_ OCAF Shape Attributes +@section occt_ocaf_5 OCAF Shape Attributes @subsection occt_ocaf_5_1 Overview A topological attribute can be seen as a hook into the topological structure. It is possible to attach data to define references to it. @@ -889,7 +1031,7 @@ 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 +@section occt_ocaf_6 Standard Attributes @subsection occt_ocaf_6_1 Overview @@ -899,6 +1041,8 @@ Standard attributes are ready-to-use attributes, which allow creating and modify * General attributes; * Relationship attributes; * Auxiliary attributes. + + ### Geometric attributes @@ -974,6 +1118,113 @@ It is usual to create standard named methods for the attributes: * Method *Get()* returns the value of an attribute if it is characterized by one value. * Method *Dump(Standard_OStream)* outputs debug information about a given attribute to a given stream. +@subsection occt_ocaf_6_3 The choice between standard and custom attributes + +When you start to design an application based on OCAF, usually it is necessary to choose, which attribute will be used for allocation of data in the OCAF document: standard or newly-created? + +It is possible to describe any model by means of standard OCAF attributes. + However, it is still a question if this description will be efficient in terms of memory and speed, and, at the same time, convenient to use. + + This depends on a particular model. + + OCAF imposes the restriction that only one attribute type may be allocated to one label. + It is necessary to take into account the design of the application data tree. + For example, if a label should possess several double values, + it is necessary to distribute them through several child sub-labels or use an array of double values. + + Let us consider several boundary implementations of the same model in OCAF tree and analyze the advantages and disadvantages of each approach. + + +@subsubsection occt_ocaf_6_2_3 Comparison and analysis of approaches + + Below are described two different model implementations: + one is based on standard OCAF attributes and the other is based + on the creation of a new attribute possessing all data of the model. + + A load is distributed through the shape. The measurements are taken at particular points defined by (x, y and z) co-ordinates. The load is represented as a projection onto X, Y and Z axes of the local co-ordinate system at each point of measurement. A matrix of transformation is needed + to convert the local co-ordinate system to the global one, but this is optional. + + So, we have 15 double values at each point of measurement. + If the number of such points is 100 000, for example, it means + that we have to store 1 500 000 double values in the OCAF document. + + The first approach consists in using standard OCAF attributes. + Besides, there are several variants of how the standard attributes may be used: + * Allocation of all 1 500 000 double values as one array of double values attached to one label; + * Allocation of values of one measure of load (15 values) as one array of double values and attachment of one point of measure to one label; + * Allocation of each point of measure as an array of 3 double values attached to one label, the projection of load onto the local co-ordinate system axes as another array of 3 double values attached to a sub-label, and the matrix of projection (9 values) as the third array also attached to a sub-label. + + Certainly, other variants are also possible. + +@image html ocaf_tree_wp_image003.png "Allocation of all data as one array of double values" +@image latex ocaf_tree_wp_image003.png "Allocation of all data as one array of double values" + + The first approach to allocation of all data represented as one array of double values + saves initial memory and is easy to implement. + But access to the data is difficult because the values are stored in a flat array. + It will be necessary to implement a class with several methods giving access + to particular fields like the measurement points, loads and so on. + + If the values may be edited in the application, + it means that the whole array will be backed-up on each edition. + The memory usage will increase very fast! + So, this approach may be considered only in case of non-editable data. + + Let’s consider the allocation of data of each measurement point per label (the second case). + In this case we create 100 000 labels – one label for each measurement point + and attach an array of double values to these labels: + +@image html ocaf_tree_wp_image004.png "Allocation of data of each measurement point as arrays of double values" +@image latex ocaf_tree_wp_image004.png "Allocation of data of each measurement point as arrays of double values" + + Now edition of data is safer as far as memory usage is concerned. + Change of value for one measurement point (any value: point co-ordinates, load, and so on) + backs-up only one small array of double values. + But this structure (tree) requires more memory space (additional labels and attributes). + + Besides, access to the values is still difficult and it is necessary + to have a class with methods of access to the array fields. + + The third case of allocation of data through OCAF tree is represented below: + +@image html ocaf_tree_wp_image005.png "Allocation of data into separate arrays of double values" +@image latex ocaf_tree_wp_image005.png "Allocation of data into separate arrays of double values" + + In this case sub-labels are involved and we can easily access the values of each measurement point, + load or matrix. We don’t need an interface class with methods of access to the data + (if it exists, it would help to use the data structure, but this is optional). + + On the one hand, this approach requires more memory for allocation of the attributes (arrays of double values). + On the other hand, it saves memory during the edition of data + by backing-up only the small array containing the modified data. + So, if the data is fully modifiable, this approach is more preferable. + + Before making a conclusion, let’s consider the same model implemented through a newly created OCAF attribute. + + For example, we might allocate all data belonging to one measurement point as one OCAF attribute. + In this case we implement the third variant of using the standard attributes (see picture 3), + but we use less memory (because we use only one attribute instead of three): + +@image html ocaf_tree_wp_image006.png "Allocation of data into newly created OCAF attribute" +@image latex ocaf_tree_wp_image006.png "Allocation of data into newly created OCAF attribute" + + The second variant of using standard OCAF attributes still has drawbacks: + when data is edited, OCAF backs-up all values of the measurement point. + + Let’s imagine that we have some non-editable data. + It would be better for us to allocate this data separately from editable data. + Back-up will not affect non-editable data and memory will not increase so much during data edition. + + @subsubsection occt_ocaf_6_2_4 Conclusion + + When deciding which variant of data model implementation to choose, + it is necessary to take into account the application response time, + memory allocation and memory usage in transactions. + + Most of the models may be implemented using only standard OCAF attributes. + Some other models need special treatment and require implementation of new OCAF attributes. + + @section occt_ocaf_7 Visualization Attributes @subsection occt_ocaf_7_1 Overview @@ -1021,16 +1272,18 @@ TPrsStd_AISPresentation::Set(NS}; // here, attach the AISPresentation to NS. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + @section occt_ocaf_8 Function Services Function services aggregate data necessary for regeneration of a model. The function mechanism - available in the package TFunction - provides links between functions and any execution algorithms, which take their arguments from the data framework, and write their results inside the same framework. When you edit any application model, you have to regenerate the model by propagating the modifications. Each propagation step calls various algorithms. To make these algorithms independent of your application model, you need to use function services. +@image html /user_guides/ocaf/images/ocaf_image008.png "Document structure" +@image latex /user_guides/ocaf/images/ocaf_image008.png "Document structure" + 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. @@ -1051,21 +1304,305 @@ An application must implement its functions, function drivers and the common sol @image latex /user_guides/ocaf/images/ocaf_image017.png The procedure of its creation is as follows: - * create a rectangular planar face F with height 100 and width 200 - * create prism P using face F as a basis - * create fillet L at the edge of the prism - * change the width of F from 200 to 300: - * the solver for the function of face F starts - * the solver detects that an argument of the face *F* function has been modified - * the solver calls the driver of the face F function for a regeneration of the face - * the driver rebuilds face F and adds the label of the face *width* argument to the logbook as touched and the label of the function of face F as impacted + * create a rectangular planar face *F* with height 100 and width 200; + * create prism *P* using face *F* as a basis; + * create fillet *L* at the edge of the prism; + * change the width of *F* from 200 to 300; + * the solver for the function of face *F* starts; + * the solver detects that an argument of the face *F* function has been modified; + * the solver calls the driver of the face *F* function for a regeneration of the face; + * the driver rebuilds face *F* and adds the label of the face *width* argument to the logbook as touched and the label of the function of face *F* as impacted; - * the solver detects the function of P – it depends on the function of F - * the solver calls the driver of the prism P function - * the driver rebuilds prism P and adds the label of this prism to the logbook as impacted - * the solver detects the function of L – it depends on the function of P - * the solver calls the L function driver - * the driver rebuilds fillet L and adds the label of the fillet to the logbook as impacted + * the solver detects the function of *P* – it depends on the function of *F*; + * the solver calls the driver of the prism *P* function; + * the driver rebuilds prism *P* and adds the label of this prism to the logbook as impacted; + * the solver detects the function of *L* – it depends on the function of *P*; + * the solver calls the *L* function driver; + * the driver rebuilds fillet *L* and adds the label of the fillet to the logbook as impacted. + + @section occt_ocaf_8a Example of Function Mechanism Usage + + @subsection occt_ocaf_8a_1 Introduction + + Let us describe the usage of the Function Mechanism of Open CASCADE Application Framework on a simple example. + This example represents a "nail" composed by a cone and two cylinders of different radius and height: + +@image html ocaf_functionmechanism_wp_image003.png "A nail" +@image latex ocaf_functionmechanism_wp_image003.png " A nail" + + These three objects (a cone and two cylinders) are independent, + but the Function Mechanism makes them connected to each other and representing one object – a nail. + The object "nail" has the following parameters: + + * The position of the nail is defined by the apex point of the cone. + The cylinders are built on the cone and therefore they depend on the position of the cone. + In this way we define a dependency of the cylinders on the cone. + * The height of the nail is defined by the height of the cone. + Let’s consider that the long cylinder has 3 heights of the cone + and the header cylinder has a half of the height of the cone. + * The radius of the nail is defined by the radius of the cone. + The radius of the long cylinder coincides with this value. + Let’s consider that the header cylinder has one and a half radiuses of the cone. + + So, the cylinders depend on the cone and the cone parameters define the size of the nail. + + It means that re-positioning the cone (changing its apex point) moves the nail, + the change of the radius of the cone produces a thinner or thicker nail, + and the change of the height of the cone shortens or prolongates the nail. +  It is suggested to examine the programming steps needed to create a 3D parametric model of the "nail". + +@subsection occt_ocaf_8a_2 Step 1: Data Tree + + The first step consists in model data allocation in the OCAF tree. + In other words, it is necessary to decide where to put the data. + + In this case, the data can be organized into a simple tree + using references for definition of dependent parameters: + +* Nail + * Cone + + Position (x,y,z) + + Radius + + Height + * Cylinder (stem) + + Position = "Cone" position translated for "Cone" height along Z; + + Radius = "Cone" radius; + + Height = "Cone" height multiplied by 3; + * Cylinder (head) + + Position = "Long cylinder" position translated for "Long cylinder" height along Z; + + Radius = "Long cylinder" radius multiplied by 1.5; + + Height = "Cone" height divided by 2. + + The "nail" object has three sub-leaves in the tree: the cone and two cylinders. + + The cone object is independent. + + The long cylinder representing a "stem" of the nail refers to the corresponding parameters + of the cone to define its own data (position, radius and height). It means that the long cylinder depends on the cone. + + The parameters of the head cylinder may be expressed through the cone parameters + only or through the cone and the long cylinder parameters. + It is suggested to express the position and the radius of the head cylinder + through the position and the radius of the long cylinder, and the height + of the head cylinder through the height of the cone. + It means that the head cylinder depends on the cone and the long cylinder. + +@subsection occt_ocaf_8a_3 Step 2: Interfaces + + The interfaces of the data model are responsible for dynamic creation + of the data tree of the represented at the previous step, data modification and deletion. + + The interface called *INail* should contain the methods for creation + of the data tree for the nail, setting and getting of its parameters, computation, visualization and removal. + +@subsubsection occt_ocaf_8a_3_1 Creation of the nail + + This method of the interface creates a data tree for the nail at a given leaf of OCAF data tree. + + It creates three sub-leaves for the cone and two cylinders and allocates the necessary data (references at the sub-leaves of the long and the head cylinders). + + It sets the default values of position, radius and height of the nail. + + The nail has the following user parameters: + * The position – coincides with the position of the cone + * The radius of the stem part of the nail – coincides with the radius of the cone + * The height of the nail – a sum of heights of the cone and both cylinders + + The values of the position and the radius of the nail are defined for the cone object data. + The height of the cone is recomputed as 2 * heights of nail and divided by 9. + +@subsubsection occt_ocaf_8a_3_2 Computation + + The Function Mechanism is responsible for re-computation of the nail. + It will be described in detail later in this document. + + A data leaf consists of the reference  to the location of the real data + and a real value defining a coefficient of multiplication of the referenced data. + + For example, the height of the long cylinder is defined as a reference to the height of the cone + with coefficient 3. The data leaf of the height of the long cylinder + should contain two attributes: a reference to the height of cone and a real value equal to 3. + +@subsubsection occt_ocaf_8a_3_3 Visualization + + The shape resulting of the nail function can be displayed using the standard OCAF visualization mechanism. + +@subsubsection occt_ocaf_8a_3_4 Removal of the nail + +To automatically erase the nail from the viewer and the data tree it is enough to clean the nail leaf from attributes. + +@subsection occt_ocaf_8a_4 Step 3: Functions + + The nail is defined by four functions: the cone, the two cylinders and the nail function. + The function of the cone is independent. The functions of the cylinders depend on the cone function. + The nail function depends on the results of all functions: + +@image html ocaf_functionmechanism_wp_image005.png "A graph of dependencies between functions" +@image latex ocaf_functionmechanism_wp_image005.png "A graph of dependencies between functions" + + Computation of the model starts with the cone function, then the long cylinder, + after that the header cylinder and, finally, the result is generated by the nail function at the end of function chain. + + The Function Mechanism of Open CASCADE Technology creates this graph of dependencies + and allows iterating it following the dependencies. + The only thing the Function Mechanism requires from its user + is the implementation of pure virtual methods of *TFunction_Driver*: + + * \::Arguments() – returns a list of arguments for the function + * \::Results() – returns a list of results of the function + + These methods give the Function Mechanism the information on the location of arguments + and results of the function and allow building a graph of functions. + The class *TFunction_Iterator* iterates the functions of the graph in the execution order. + + The pure virtual method *TFunction_Driver::Execute()* calculating the function should be overridden. + + The method \::MustExecute() calls the method \::Arguments() of the function driver + and ideally this information (knowledge of modification of arguments of the function) is enough + to make a decision whether the function should be executed or not. Therefore, this method usually shouldn’t be overridden. + + The cone and cylinder functions differ only in geometrical construction algorithms. + Other parameters are the same (position, radius and height). + + It means that it is possible to create a base class – function driver for the three functions, + and two descendant classes producing: a cone or a cylinder. + + For the base function driver the methods \::Arguments() and \::Results() will be overridden. + Two descendant function drivers responsible for creation of a cone and a cylinder will override only the method \::Execute(). + + The method \::Arguments() of the function driver of the nail returns the results of the functions located under it in the tree of leaves. The method \::Execute() just collects the results of the functions and makes one shape – a nail. + + This way the data model using the Function Mechanism is ready for usage. Do not forget to introduce the function drivers for a function driver table with the help of *TFunction_DriverTable* class. + +@subsection occt_ocaf_8a_5 Example 1: iteration and execution of functions. + + This is an example of the code for iteration and execution of functions. + +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.cpp} + + // The scope of functions is defined. + Handle(TFunction_Scope) scope = TFunction_Scope::Set( anyLabel ); + + // The information on modifications in the model is received. + TFunction_Logbook& log = scope-GetLogbook(); + + // The iterator is iInitialized by the scope of functions. + TFunction_Iterator iterator( anyLabel ); + Iterator.SetUsageOfExecutionOrder( true ); + + // The function is iterated,  its dependency is checked on the modified data and  executed if necessary. + for (; iterator.more(); iterator.Next()) + { + // The function iterator may return a list of current functions for execution. + // It might be useful for multi-threaded execution of functions. + const TDF_LabelList& currentFunctions = iterator.Current(); + + //The list of current functions is iterated. + TDF_ListIteratorOfLabelList currentterator( currentFucntions ); + for (; currentIterator.More(); currentIterator.Next()) + { + // An interface for the function is created. + TFunction_IFunction interface( currentIterator.Value() ); + + // The function driver is retrieved. + Handle(TFunction_Driver) driver = interface.GetDriver(); + + // The dependency of the function on the  modified data is checked. + If (driver-MustExecute( log )) + { + // The function is executed. + int ret = driver-Execute( log ); + if ( ret ) + return false; + } // end if check on modification + } // end of iteration of current functions + } // end of iteration of functions. + +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +@subsection occt_ocaf_8a_6 Example 2: Cylinder function driver + + This is an example of the code for a cylinder function driver. To make the things clearer, the methods \::Arguments() and \::Results() from the base class are also mentioned. + +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.cpp} + + // A virtual method ::Arguments() returns a list of arguments of the function. + CylinderDriver::Arguments( TDF_LabelList& args ) + { + // The direct arguments, located at sub-leaves of the fucntion, are collected (see picture 2). + TDF_ChildIterator cIterator( Label(), false ); + for (; cIterator.More(); cIterator.Next() ) + { + // Direct argument. + TDF_Label sublabel = cIterator.Value(); + Args.Append( sublabel ); + + // The references to the external data are checked. + Handle(TDF_Reference) ref; + If ( sublabel.FindAttribute( TDF_Reference::GetID(), ref ) ) + { + args.Append( ref-Get() ); + } + } + + // A virtual method ::Results() returns a list of result leaves. + CylinderDriver::Results( TDF_LabelList& res ) + { + // The result is kept at the function label. +   Res.Append( Label() ); + } + + // Execution of the function driver. + Int CylinderDriver::Execute( TFunction_Logbook& log ) + { + // Position of the cylinder – position of the first function (cone) + //is  elevated along Z for height values of all previous functions. + gp_Ax2 axes = …. // out of the scope of this guide. + // The radius value is retrieved. + // It is located at second child sub-leaf (see the picture 2). + TDF_Label radiusLabel = Label().FindChild( 2 ); + + // The multiplicator of the radius ()is retrieved. + Handle(TDataStd_Real) radiusValue; + radiusLabel.FindAttribute( TDataStd_Real::GetID(), radiusValue); + + // The reference to the radius is retrieved. + Handle(TDF_Reference) refRadius; + RadiusLabel.FindAttribute( TDF_Reference::GetID(), refRadius ); + + // The radius value is calculated. + double radius = 0.0; + + if ( refRadius.IsNull() ) + { + radius = radiusValue-Get(); + } + else + { + // The referenced radius value is retrieved. + Handle(TDataStd_Real) referencedRadiusValue; + RefRadius-Get().FindAttribute(TDataStd_Real::GetID() ,referencedRadiusValue ); + radius = referencedRadiusValue-Get() * radiusValue-Get(); + } + + // The height value is retrieved. + double height = … // similar code to taking the radius value. + + // The cylinder is created. + TopoDS_Shape cylinder = BRepPrimAPI_MakeCylinder(axes, radius, height); + + // The result (cylinder) is set + TNaming_Builder builder( Label() ); + Builder.Generated( cylinder ); + + // The modification of the result leaf is saved in the log. + log.SetImpacted( Label() ); + + return 0; + } +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + + @section occt_ocaf_9 XML Support @@ -1202,6 +1739,235 @@ Both the XML format and the XML OCAF persistence code are extensible in the sens * Declare (in *XSD* files) all elements and types in the targetNamespace to appear without a namespace prefix; all other elements and types use the appropriate prefix (such as "ocaf:"). * Add (in the new *DocumentStorageDriver*) the *targetNamespace* accompanied with its prefix, using method *XmlDrivers_DocumentStorageDriver::AddNamespace*. The same is done for all namespaces objects which are used by the new persistence, with the exception of the "ocaf" namespace. * Pass (in every OCAF attribute driver) the namespace prefix of the *targetNamespace* to the constructor of *XmlMDF_ADriver*. + +@section occt_ocaf_9a Persistent Data Storage + +@subsection occt_ocaf_9a_1 Introduction + +In OCAF, persistence, that is, the mechanism used to save a document in a file, is based on an explicit formal description of the data saved. + +When you open a document, the application reads the corresponding file and first creates a memory representation of it. This representation is then converted to the application data model — the OCAF-based data structure the application operates on. The file's memory representation consists of objects defined by classes known as persistent. + +The persistent classes needed by an application to save its documents make the application's data schema. This schema defines the way the data are organized in the file — the format of the data. In other words, the file is simply an ASCII dump of the persistent data defined by the schema, the persistent data being created from the application data model during the save process. + +Only canonical information is saved. As a matter of fact, the application data model usually contains additional data to optimize processing. For example, the persistent Bézier curve is defined by its poles, whereas its data model equivalent also contains coefficients used to compute a point at a given parameter. The additional data is calculated when the document is opened. + +The major advantages of this approach are the following: + * 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, + OCAF provides a framework for managing compatibility of data between versions of the application — + modification of the data format is supported through the versioning of schema. + + OCAF includes a ready-to-use schema suitable for most applications. + However, it can be extended if needed. For that, the only things you have to do are: + + * To define the additional persistent attributes + * To implement the functions converting these persistent attribute to and from the application data model. + +Applications using compound documents extensively (saving data in many files linked together) should implement data management services. As a matter of fact, it's out the scope of OCAF to provide functions such as: +* Version and configuration management of compound documents; +* Querying a referenced document for its referencing documents. + +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. + + +@subsection occt_ocaf_9a_2 Schemes of Persistence + +There are three schemes of persistence, which you can use to store and retrieve OCAF data (documents): + + * Standard persistence schema, compatible with previous OCAF applications + * XmlOcaf persistence, allowing the storage of all OCAF data in XML form + * BinOcaf 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 Standard 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. + +@subsection occt_ocaf_9a_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 Storage package is used to write and read persistent objects. +These objects are read and written by a retrieval or storage algorithm +( Storage_Schema object) in a container (disk, memory, network ...). +Drivers ( FSD_File 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 Storage_Data 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 Storage_Data class, then add the persistent data to write with the function AddRoot, +* call the function Write from the schema, setting the driver and the Storage_Data instance as parameters, +* close the driver. + +@subsection occt_ocaf_9a_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 TCollection 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, PCollection does not include sequences, lists, and so on (unlike TCollection). + +Persistent string and array classes are found in the PCollection package. In addition, PColStd package provides standard, and frequently used, instantiations of persistent arrays, for very simple objects. + +@subsection occt_ocaf_9a_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 PGeom 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 Geom package: for +each type of transient object provided by Geom there is a corresponding type of persistent +object in the PGeom package. In particular the inheritance structure is parallel. + +However the PGeom 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 Geom objects. To do this you use the MgtGeom::Translate 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 MgtGeom::Translate 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 PGeom package consists simply of a list of available objects. + +The PGeom2d 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 PGeom package, but for the 2D geometric objects provided by the Geom2d package. +Conversions are provided by the MgtGeom::Translate 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); +~~~~ + + +@subsection occt_ocaf_9a_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 TopoDS_Shape 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 PTopoDS package describes the persistent data model associated with any BRep shape; it is the persistent version of any shape of type TopoDS_Shape. 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 MgtBRep::Translate function. + +The MgtBRepAbs and PTColStd 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(); +~~~~ + @section occt_ocaf_10 GLOSSARY @@ -1255,6 +2021,135 @@ In C++, the application behavior is implemented in virtual functions redefined i * **Valid label** - in a data framework, this is a label, which is already recomputed in the scope of regeneration sequence and includes the label containing a feature which is to be recalculated. Consider the case of a box to which you first add a fillet, then a protrusion feature. For recalculation purposes, only valid labels of each construction stage are used. In recalculating a fillet, they are only those of the box and the fillet, not the protrusion feature which was added afterwards. @section occt_ocaf_11 Samples + +@subsection occt_ocaf_11_a Getting Started + + At the beginning of your development, you first define an application class by inheriting from the Application abstract class. + You only have to create and determine the resources of the application + for specifying the format of your documents (you generally use the standard one) and their file extension. + + Then, you design the application data model by organizing attributes you choose among those provided with OCAF. + You can specialize these attributes using the User attribute. For example, if you need a reflection coefficient, + you aggregate a User attribute identified as a reflection coefficient + with a Real attribute containing the value of the coefficient (as such, you don't define a new class). + + 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 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: + + * Persistent reference to any data, including geometric elements — several documents can be linked with such reference; + * Document-View association; + * Ready-to-use functions such as : + * Undo-redo; + * Save and open application data. + + Finally, you develop the application's graphical user interface using the toolkit of your choice, for example: + * KDE Qt or GNOME GTK+ on Linux; + * Microsoft Foundation Classes (MFC) on Windows Motif on Sun; + * Other commercial products such as Ilog Views. + + You can also implement the user interface in the Java language using + the Swing-based Java Application Desktop component (JAD) provided with OCAF. + +@subsection occt_ocaf_11_b An example of OCAF usage + +To create a useful OCAF-based application, it is necessary to redefine two deferred methods: Formats and ResourcesName + +In the Formats 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 ResourcesName 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: CSF_PluginDefaults, which defines the path of the plug-in file, and CSF_ResourcesDefault, 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 myDirector. +The name of the plugin file must be Plugin. + +### 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 uuidgen 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 PappStdPlugin 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 +~~~~ + + +### 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 FWOSPlugin and the plug-in drivers to run an OCAF application. + +The syntax of each item is Identification.Location Library_Name, 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 +~~~~ + + + @subsection occt_ocaf_11_1 Implementation of Attribute Transformation in a CDL file ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.cpp} diff --git a/dox/user_guides/ocaf_functionmechanism_wp/ocaf_functionmechanism_wp.md b/dox/user_guides/ocaf_functionmechanism_wp/ocaf_functionmechanism_wp.md deleted file mode 100644 index e6b2bd57db..0000000000 --- a/dox/user_guides/ocaf_functionmechanism_wp/ocaf_functionmechanism_wp.md +++ /dev/null @@ -1,286 +0,0 @@ -OCAF Function Mechanism {#occt_user_guides__ocaf_functionmechanism_wp} -======================== - -@tableofcontents - -@section occt_ocaf_functionmechanism_wp_1 Introduction - - This guide describes the usage of the Function Mechanism of Open CASCADE Application Framework on a simple example. - This example represents a "nail" composed by a cone and two cylinders of different radius and height: - -@image html ocaf_functionmechanism_wp_image003.png "A nail" -@image latex ocaf_functionmechanism_wp_image003.png " A nail" - - These three objects (a cone and two cylinders) are independent, - but the Function Mechanism makes them connected to each other and representing one object – a nail. - The object "nail" has the following parameters: - - * The position of the nail is defined by the apex point of the cone. - The cylinders are built on the cone and therefore they depend on the position of the cone. - In this way we define a dependency of the cylinders on the cone. - * The height of the nail is defined by the height of the cone. - Let’s consider that the long cylinder has 3 heights of the cone - and the header cylinder has a half of the height of the cone. - * The radius of the nail is defined by the radius of the cone. - The radius of the long cylinder coincides with this value. - Let’s consider that the header cylinder has one and a half radiuses of the cone. - - So, the cylinders depend on the cone and the cone parameters define the size of the nail. - - It means that re-positioning the cone (changing its apex point) moves the nail, - the change of the radius of the cone produces a thinner or thicker nail, - and the change of the height of the cone shortens or prolongates the nail. -  It is suggested to examine the programming steps needed to create a 3D parametric model of the "nail". - This guide describes in detail usage of the Function Mechanism. - Other aspects, such as the data model and the interfaces are mentioned in brief. - -@section occt_ocaf_functionmechanism_wp_2 Step 1: Data Tree - - The first step consists in model data allocation in the OCAF tree. - In other words, it is necessary to decide where to put the data. - - In this case, the data can be organized into a simple tree - using references for definition of dependent parameters: - -* Nail - * Cone - + Position (x,y,z) - + Radius - + Height - * Cylinder (stem) - + Position = "Cone" position translated for "Cone" height along Z; - + Radius = "Cone" radius; - + Height = "Cone" height multiplied by 3; - * Cylinder (head) - + Position = "Long cylinder" position translated for "Long cylinder" height along Z; - + Radius = "Long cylinder" radius multiplied by 1.5; - + Height = "Cone" height divided by 2. - - The "nail" object has three sub-leaves in the tree: the cone and two cylinders. - - The cone object is independent. - - The long cylinder representing a "stem" of the nail refers to the corresponding parameters - of the cone to define its own data (position, radius and height). It means that the long cylinder depends on the cone. - - The parameters of the head cylinder may be expressed through the cone parameters - only or through the cone and the long cylinder parameters. - It is suggested to express the position and the radius of the head cylinder - through the position and the radius of the long cylinder, and the height - of the head cylinder through the height of the cone. - It means that the head cylinder depends on the cone and the long cylinder. - -@section occt_ocaf_functionmechanism_wp_3 Step 2: Interfaces - - The interfaces of the data model are responsible for dynamic creation - of the data tree of the represented at the previous step, data modification and deletion. - - The interface called *INail* should contain the methods for creation - of the data tree for the nail, setting and getting of its parameters, computation, visualization and removal. - -@subsection occt_ocaf_functionmechanism_wp_3_1 Creation of the nail - - This method of the interface creates a data tree for the nail at a given leaf of OCAF data tree. - - It creates three sub-leaves for the cone and two cylinders and allocates the necessary data (references at the sub-leaves of the long and the head cylinders). - - It sets the default values of position, radius and height of the nail. - - The nail has the following user parameters: - * The position – coincides with the position of the cone - * The radius of the stem part of the nail – coincides with the radius of the cone - * The height of the nail – a sum of heights of the cone and both cylinders - - The values of the position and the radius of the nail are defined for the cone object data. - The height of the cone is recomputed as 2 * heights of nail and divided by 9. - -@subsection occt_ocaf_functionmechanism_wp_3_2 Computation - - The Function Mechanism is responsible for re-computation of the nail. - It will be described in detail later in this document. - - A data leaf consists of the reference  to the location of the real data - and a real value defining a coefficient of multiplication of the referenced data. - - For example, the height of the long cylinder is defined as a reference to the height of the cone - with coefficient 3. The data leaf of the height of the long cylinder - should contain two attributes: a reference to the height of cone and a real value equal to 3. - -@subsection occt_ocaf_functionmechanism_wp_3_3 Visualization - - The shape resulting of the nail function can be displayed using the standard OCAF visualization mechanism. - -@subsection occt_ocaf_functionmechanism_wp_3_4 Removal of the nail - -To automatically erase the nail from the viewer and the data tree it is enough to clean the nail leaf from attributes. - -@section occt_ocaf_functionmechanism_wp_4 Step 3: Functions - - The nail is defined by four functions: the cone, the two cylinders and the nail function. - The function of the cone is independent. The functions of the cylinders depend on the cone function. - The nail function depends on the results of all functions: - -@image html ocaf_functionmechanism_wp_image005.png "Picture 3. A graph of dependencies between functions" -@image latex ocaf_functionmechanism_wp_image005.png "Picture 3. A graph of dependencies between functions" - - Computation of the model starts with the cone function, then the long cylinder, - after that the header cylinder and, finally, the result is generated by the nail function at the end of function chain. - - The Function Mechanism of Open CASCADE Technology creates this graph of dependencies - and allows iterating it following the dependencies. - The only thing the Function Mechanism requires from its user - is the implementation of pure virtual methods of *TFunction_Driver*: - - * \::Arguments() – returns a list of arguments for the function - * \::Results() – returns a list of results of the function - - These methods give the Function Mechanism the information on the location of arguments - and results of the function and allow building a graph of functions. - The class *TFunction_Iterator* iterates the functions of the graph in the execution order. - - The pure virtual method *TFunction_Driver::Execute()* calculating the function should be overridden. - - The method \::MustExecute() calls the method \::Arguments() of the function driver - and ideally this information (knowledge of modification of arguments of the function) is enough - to make a decision whether the function should be executed or not. Therefore, this method usually shouldn’t be overridden. - - The cone and cylinder functions differ only in geometrical construction algorithms. - Other parameters are the same (position, radius and height). - - It means that it is possible to create a base class – function driver for the three functions, - and two descendent classes producing: a cone or a cylinder. - - For the base function driver the methods \::Arguments() and \::Results() will be overridden. - Two descendent function drivers responsible for creation of a cone and a cylinder will override only the method \::Execute(). - - The method \::Arguments() of the function driver of the nail returns the results of the functions located under it in the tree of leaves. The method \::Execute() just collects the results of the functions and makes one shape – a nail. - - This way the data model using the Function Mechanism is ready for usage. Do not forget to introduce the function drivers for a function driver table with the help of *TFunction_DriverTable* class. - -@section occt_ocaf_functionmechanism_wp_5 Appendix 1 - - This appendix gives an example of the code for iteration and execution of functions. - -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.cpp} - - // The scope of functions is defined. - Handle(TFunction_Scope) scope = TFunction_Scope::Set( anyLabel ); - - // The information on modifications in the model is received. - TFunction_Logbook& log = scope-GetLogbook(); - - // The iterator is iInitialized by the scope of functions. - TFunction_Iterator iterator( anyLabel ); - Iterator.SetUsageOfExecutionOrder( true ); - - // The function is iterated,  its dependency is checked on the modified data and  executed if necessary. - for (; iterator.more(); iterator.Next()) - { - // The function iterator may return a list of current functions for execution. - // It might be useful for multi-threaded execution of functions. - const TDF_LabelList& currentFunctions = iterator.Current(); - - //The list of current functions is iterated. - TDF_ListIteratorOfLabelList currentterator( currentFucntions ); - for (; currentIterator.More(); currentIterator.Next()) - { - // An interface for the function is created. - TFunction_IFunction interface( currentIterator.Value() ); - - // The function driver is retrieved. - Handle(TFunction_Driver) driver = interface.GetDriver(); - - // The dependency of the function on the  modified data is checked. - If (driver-MustExecute( log )) - { - // The function is executed. - int ret = driver-Execute( log ); - if ( ret ) - return false; - } // end if check on modification - } // end of iteration of current functions - } // end of iteration of functions. - -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -@section occt_ocaf_functionmechanism_wp_6 Appendix 2 - - This appendix gives an example of the code for a cylinder function driver. In order to make the things clearer, the methods \::Arguments() and \::Results() from the base class are also mentioned. - -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.cpp} - - // A virtual method ::Arguments() returns a list of arguments of the function. - CylinderDriver::Arguments( TDF_LabelList& args ) - { - // The direct arguments, located at sub-leaves of the fucntion, are collected (see picture 2). - TDF_ChildIterator cIterator( Label(), false ); - for (; cIterator.More(); cIterator.Next() ) - { - // Direct argument. - TDF_Label sublabel = cIterator.Value(); - Args.Append( sublabel ); - - // The references to the external data are checked. - Handle(TDF_Reference) ref; - If ( sublabel.FindAttribute( TDF_Reference::GetID(), ref ) ) - { - args.Append( ref-Get() ); - } - } - - // A virtual method ::Results() returns a list of result leaves. - CylinderDriver::Results( TDF_LabelList& res ) - { - // The result is kept at the function label. -   Res.Append( Label() ); - } - - // Execution of the function driver. - Int CylinderDriver::Execute( TFunction_Logbook& log ) - { - // Position of the cylinder – position of the first function (cone) - //is  elevated along Z for height values of all previous functions. - gp_Ax2 axes = …. // out of the scope of this guide. - // The radius value is retrieved. - // It is located at second child sub-leaf (see the picture 2). - TDF_Label radiusLabel = Label().FindChild( 2 ); - - // The multiplicator of the radius ()is retrieved. - Handle(TDataStd_Real) radiusValue; - radiusLabel.FindAttribute( TDataStd_Real::GetID(), radiusValue); - - // The reference to the radius is retrieved. - Handle(TDF_Reference) refRadius; - RadiusLabel.FindAttribute( TDF_Reference::GetID(), refRadius ); - - // The radius value is calculated. - double radius = 0.0; - - if ( refRadius.IsNull() ) - { - radius = radiusValue-Get(); - } - else - { - // The referenced radius value is retrieved. - Handle(TDataStd_Real) referencedRadiusValue; - RefRadius-Get().FindAttribute(TDataStd_Real::GetID() ,referencedRadiusValue ); - radius = referencedRadiusValue-Get() * radiusValue-Get(); - } - - // The height value is retrieved. - double height = … // similar code to taking the radius value. - - // The cylinder is created. - TopoDS_Shape cylinder = BRepPrimAPI_MakeCylinder(axes, radius, height); - - // The result (cylinder) is set - TNaming_Builder builder( Label() ); - Builder.Generated( cylinder ); - - // The modification of the result leaf is saved in the log. - log.SetImpacted( Label() ); - - return 0; - } -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ \ No newline at end of file diff --git a/dox/user_guides/ocaf_tree_wp/ocaf_tree_wp.md b/dox/user_guides/ocaf_tree_wp/ocaf_tree_wp.md deleted file mode 100644 index b9d5403113..0000000000 --- a/dox/user_guides/ocaf_tree_wp/ocaf_tree_wp.md +++ /dev/null @@ -1,139 +0,0 @@ - Distribution of Data Through OCAF Tree {#occt_user_guides__ocaf_tree_wp} -======================================= -@tableofcontents - -@section occt_ocaf_tree_wp_1 Introduction - - Open CASCADE Application Framework (OCAF) represents a set of classes for Rapid Application Development. - OCAF helps to implement such functions as undo and redo, copy, cut and paste, storage and retrieval of documents, and many others. - - OCAF is based on a notion of label-attribute. The labels form a tree. - The attributes are attached to the labels and store user data in the OCAF document. - -This document describes how data should be stored in the OCAF document and considers the following issues: - - * Should we choose standard attributes or is it better to create new ones? - * How can we optimize data allocation to make it easy to use and efficient for memory usage and application speed? - -In particular, the document describes an example of using standard OCAF attributes and creating new OCAF attributes. It is assumed that the reader is already familiar with some OCAF basics. - - -@section occt_ocaf_tree_wp_2 Description - - When you start to design an application based on OCAF, - usually you need to choose between standard and newly-created attributes - to be used for allocation of data in the OCAF document. - Before giving an answer to this question, let’s overview standard OCAF attributes. - - All basic data types are represented in OCAF as special attributes: - * Integer, - * Double, - * String, - * Array of integer values, - * Array of double values, - * Array of string values, - * Topological shapes. - - An attentive reader might have noticed that there is no Boolean type. - This is because the Integer type is usually used instead. - - So, we have an opportunity to describe any model by means of standard OCAF attributes. - But will this description be efficient for memory, speed, and, at the same time, convenient to use? - It depends on a particular model. - - OCAF has one restriction: only one attribute type may be allocated to one label. - It is necessary to take into account the design of the application data tree. - For example, if a label should possess several double values, - it is necessary to distribute them through several child sub-labels or use an array of double values. - - Let’s consider several boundary implementations of the same model in OCAF tree - and analyse the advantages and disadvantages of each approach. - -@section occt_ocaf_tree_wp_3 Comparison and analysis of approaches - - Below are described two different model implementations: - one is based on standard OCAF attributes and the other is based - on the creation of a new attribute possessing all data of the model. - - A load is distributed through the shape. The measurements are taken at particular points defined by (x, y and z) co-ordinates. The load is represented as a projection onto X, Y and Z axes of the local co-ordinate system at each point of measurement. A matrix of transformation is needed - to convert the local co-ordinate system to the global one, but this is optional. - - So, we have 15 double values at each point of measurement. - If the number of such points is 100 000, for example, it means - that we have to store 1 500 000 double values in the OCAF document. - - The first approach consists in using standard OCAF attributes. - Besides, there are several variants of how the standard attributes may be used: - * Allocation of all 1 500 000 double values as one array of double values attached to one label; - * Allocation of values of one measure of load (15 values) as one array of double values and attachment of one point of measure to one label; - * Allocation of each point of measure as an array of 3 double values attached to one label, the projection of load onto the local co-ordinate system axes as another array of 3 double values attached to a sub-label, and the matrix of projection (9 values) as the third array also attached to a sub-label. - - Certainly, other variants are also possible. - -@image html ocaf_tree_wp_image003.png "Allocation of all data as one array of double values" -@image latex ocaf_tree_wp_image003.png "Allocation of all data as one array of double values" - - The first approach to allocation of all data represented as one array of double values - saves initial memory and is easy to implement. - But access to the data is difficult because the values are stored in a flat array. - It will be necessary to implement a class with several methods giving access - to particular fields like the measurement points, loads and so on. - - If the values may be edited in the application, - it means that the whole array will be backed-up on each edition. - The memory usage will increase very fast! - So, this approach may be considered only in case of non-editable data. - - Let’s consider the allocation of data of each measurement point per label (the second case). - In this case we create 100 000 labels – one label for each measurement point - and attach an array of double values to these labels: - -@image html ocaf_tree_wp_image004.png "Allocation of data of each measurement point as arrays of double values" -@image latex ocaf_tree_wp_image004.png "Allocation of data of each measurement point as arrays of double values" - - Now edition of data is safer as far as memory usage is concerned. - Change of value for one measurement point (any value: point co-ordinates, load, and so on) - backs-up only one small array of double values. - But this structure (tree) requires more memory space (additional labels and attributes). - - Besides, access to the values is still difficult and it is necessary - to have a class with methods of access to the array fields. - - The third case of allocation of data through OCAF tree is represented below: - -@image html ocaf_tree_wp_image005.png "Allocation of data into separate arrays of double values" -@image latex ocaf_tree_wp_image005.png "Allocation of data into separate arrays of double values" - - In this case sub-labels are involved and we can easily access the values of each measurement point, - load or matrix. We don’t need an interface class with methods of access to the data - (if it exists, it would help to use the data structure, but this is optional). - - On the one hand, this approach requires more memory for allocation of the attributes (arrays of double values). - On the other hand, it saves memory during the edition of data - by backing-up only the small array containing the modified data. - So, if the data is fully modifiable, this approach is more preferable. - - Before making a conclusion, let’s consider the same model implemented through a newly created OCAF attribute. - - For example, we might allocate all data belonging to one measurement point as one OCAF attribute. - In this case we implement the third variant of using the standard attributes (see picture 3), - but we use less memory (because we use only one attribute instead of three): - -@image html ocaf_tree_wp_image006.png "Allocation of data into newly created OCAF attribute" -@image latex ocaf_tree_wp_image006.png "Allocation of data into newly created OCAF attribute" - - The second variant of using standard OCAF attributes still has drawbacks: - when data is edited, OCAF backs-up all values of the measurement point. - - Let’s imagine that we have some non-editable data. - It would be better for us to allocate this data separately from editable data. - Back-up will not affect non-editable data and memory will not increase so much during data edition. - -@section occt_ocaf_tree_wp_4 Conclusion - - When deciding which variant of data model implementation to choose, - it is necessary to take into account the application response time, - memory allocation and memory usage in transactions. - - Most of the models may be implemented using only standard OCAF attributes. - Some other models need special treatment and require implementation of new OCAF attributes. diff --git a/dox/user_guides/ocaf_wp/images/ocaf_wp_image004.png b/dox/user_guides/ocaf_wp/images/ocaf_wp_image004.png deleted file mode 100644 index 45eb829f8c..0000000000 Binary files a/dox/user_guides/ocaf_wp/images/ocaf_wp_image004.png and /dev/null differ diff --git a/dox/user_guides/ocaf_wp/ocaf_wp.md b/dox/user_guides/ocaf_wp/ocaf_wp.md deleted file mode 100644 index e1df41d035..0000000000 --- a/dox/user_guides/ocaf_wp/ocaf_wp.md +++ /dev/null @@ -1,624 +0,0 @@ -OCAF White-Paper {#occt_user_guides__ocaf_wp} -======================== - @tableofcontents - -@section ocaf_wp_1 What is OCAF ? - -@subsection ocaf_wp_1_1 Purpose of OCAF - - The Open CASCADE Application Framework (OCAF) is an easy-to-use platform for rapidly developing - sophisticated domain-specific design applications. - A typical application developed using OCAF deals with two or three-dimensional (2D or 3D) geometric modeling - in trade-specific Computer Aided Design (CAD) systems, manufacturing or analysis applications, - simulation applications or illustration tools. - - Developing a design application requires addressing many technical aspects. - In particular, given the functional specification of your application, you must at least: - - * Design the architecture of the application — definition of the software components and the way they cooperate - * Define the data model able to support the functionality required — a design application operates on data maintained during the whole end-user working session - * Structure the software in order to - * synchronize the display with the data — commands modifying objects must update the views - * support generalized undo-redo commands — this feature has to be taken into account very early in the design process - * Implement the function for saving the data — if the application has a long life cycle, the compatibility of data between versions of the application has to be addressed - * Build the application user interface - - 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 - - OCAF provides you with an object-oriented Application-Document-Attribute model. - This consists of C++ class libraries. The main class, Application, is an abstract class - in charge of handling documents during the working session. Services provided by this class include: - * Creating new documents - * Saving documents and opening them - * Initializing document views - - The document, implemented by the concrete class Document, is the container for the application data. - Its main purpose is to centralize notifications of data editing in order to provide Undo-Redo. - Each document is saved in a single flat ASCII file defined by its format and extension (a ready-to-use format is provided with OCAF). - - Application data are attributes, that is, instances of classes derived from the *Attribute* abstract class, - organized according to the OCAF Data Framework. - The OCAF Data Framework references aggregations of attributes using persistent identifiers in a single hierarchy (the Data Framework is described in the next chapter). A wide range of attributes come with OCAF, including: - - * Primitive attributes such as *Integer, Real, Name* and *Comment*; - * Shape attribute containing the geometry of the whole model or elements of it; - * Other geometric attributes such as Datums (points, axis and plane) and Constraints (*tangent-to, at-a-given-distance, from-a-given-angle, concentric,* etc.) - * Modeling step and Function attributes — the purpose of these attributes is to rebuild objects after they have been modified (parameterization of models) - * Visualization attributes — these attributes allow data to be visualized in a 2D or 3D viewer - * User attributes, that is, attributes typed by the application - * In addition, application-specific data can be added by defining new attribute classes; - naturally, this changes the standard file format. The only functions that have to be implemented are: - * Copying the attribute - * Converting it from and to its persistent homolog (persistence is briefly presented in the paragraph Persistent Data Storage) - -@image html ocaf_wp_image003.png "The Application-Document-Attribute model " -@image latex ocaf_wp_image003.png "The Application-Document-Attribute model " - -OCAF uses other modules of Open CASCADE Technology — the Shape attribute is implemented with the geometry supported by the Modeling Data module and the viewer is the one provided with the Visualization module. Modeling functions can be implemented using the Modeling Algorithms module. - -@subsection ocaf_wp_1_3 Getting Started - - At the beginning of your development, you first define an application class by inheriting from the Application abstract class. - You only have to create and determine the resources of the application - for specifying the format of your documents (you generally use the standard one) and their file extension. - - Then, you design the application data model by organizing attributes you choose among those provided with OCAF. - You can specialize these attributes using the User attribute. For example, if you need a reflection coefficient, - you aggregate a User attribute identified as a reflection coefficient - with a Real attribute containing the value of the coefficient (as such, you don't define a new class). - - 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 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: - - * Persistent reference to any data, including geometric elements — several documents can be linked with such reference; - * Document-View association; - * Ready-to-use functions such as : - * Undo-redo; - * Save and open application data. - - Finally, you develop the application's graphical user interface using the toolkit of your choice, for example: - * KDE Qt or GNOME GTK+ on Linux; - * Microsoft Foundation Classes (MFC) on Windows Motif on Sun; - * Other commercial products such as Ilog Views. - - 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 An example of OCAF usage - -To create a useful OCAF-based application, it is necessary to redefine two deferred methods: Formats and ResourcesName - -In the Formats 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 ResourcesName 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: CSF_PluginDefaults, which defines the path of the plug-in file, and CSF_ResourcesDefault, 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 myDirector. -The name of the plugin file must be Plugin. - -### 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 uuidgen 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 PappStdPlugin 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 -~~~~ - - -### 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 FWOSPlugin and the plug-in drivers to run an OCAF application. - -The syntax of each item is Identification.Location Library_Name, 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_1 The Design of OCAF - -@subsubsection ocaf_wp_2_1_1 Reference-key model - - In most existing geometric modeling systems, the data are topology driven. - They usually use a boundary representation (BRep), where geometric models - are defined by a collection of faces, edges and vertices, - to which application data are attached. Examples of data include: - - * a color; - * a material; - * information that a particular edge is blended. - - When the geometric model is parameterized, that is, when you can change - the value of parameters used to build the model (the radius of a blend, the thickness of a rib, etc.), - the geometry is highly subject to change. - In order to maintain the attachment of application data, the geometry must be distinguished from other data. - - In OCAF, the data are reference-key driven. It is a uniform model in which reference-keys - are the persistent identification of data. All **accessible** data, including the geometry, - are implemented as attributes attached to reference-keys. - The geometry becomes the value of the Shape attribute, just as a number is the value - of the Integer and Real attributes and a string that of the Name attribute. - - On a single reference-key, many attributes can be aggregated; - the application can ask at runtime which attributes are available. - For example, to associate a texture to a face in a geometric model, - both the face and the texture are attached to the same reference-key. - -@image html ocaf_wp_image004.png "Figure 2. Topology driven versus reference-key driven approaches" -@image latex ocaf_wp_image004.png "Figure 2. Topology driven versus reference-key driven approaches" - -@subsubsection ocaf_wp_2_1_2 Topological naming - - Reference-keys can be created in two ways: - - * At programming time, by the application - * At runtime, by the end-user of the application (providing that you include this capability in the application) - - As an application developer, you generate reference-keys in order to give semantics to the data. - For example, a function building a prism may create three reference-keys: - one for the base of the prism, a second for the lateral faces and a third for the top face. - This makes up a semantic built-in the application's prism feature. - On the other hand, in a command allowing the end-user to set a texture to a face he/she selects, - you must create a reference-key to the selected face - if it has not previously been referenced in any feature - (as in the case of one of the lateral faces of the prism). - - When you create a reference-key to selected topological elements (faces, edges or vertices), - OCAF attaches to the reference-key information defining the selected topology — the Naming attribute. - For example, it may be the faces to which a selected edge is common to. - This information, as well as information about the evolution of the topology at each modeling step - (the modified, updated and deleted faces), is used by the naming algorithm to maintain the topology - attached to the reference-key. As such, on a parametrized model, - after modifying the value of a parameter, the reference-keys still address the appropriate faces, - even if their geometry has changed. - Consequently, you change the size of the cube shown in the figure 2 above, - the user texture stay attached to the right face. - - Note As Topological naming is based on the reference-key and attributes such as Naming - (selection information) and Shape (topology evolution information), - OCAF is not coupled to the underlying modeling libraries. - The only modeling services required by OCAF are the following: - - * Each algorithm must provide information about the evolution of the topology - (the list of faces modified, updated and deleted by the algorithm) - * Exploration of the geometric model must be available - (a 3D model is made of faces bounded by close wires, - themselves composed by a sequence of edges connected by their vertices) - - Currently, OCAF uses the Open CASCADE Technology modeling libraries. - -@subsubsection ocaf_wp_2_1_3 Aggregation of attributes - - To design an OCAF-based data model, the application developer is encouraged to aggregate - ready-to-use attributes instead of defining new attributes by inheriting from an abstract root class. - There are two major advantages in using aggregation rather than inheritance: - - * As you don't implement data by defining new classes, the format of saved data - provided with OCAF doesn't change; so you don't have to write the Save and Open functions - * The application can query the data at runtime if a particular attribute is available - -@subsubsection ocaf_wp_2_1_4 Summary - - * OCAF is based on a uniform reference-key model in which: - * Reference-keys provide persistent identification of data; - * Data, including geometry, are implemented as attributes attached to reference-keys; - * Topological naming maintains the selected geometry attached to reference-keys in parametrized models ; - * In many applications, the data format provided with OCAF doesn't need to be extended; - * OCAF is not coupled to the underlying modeling libraries. - -@subsection ocaf_wp_2_2 The Data Framework - -@subsubsection ocaf_wp_2_2_1 Data structure - - The OCAF Data Framework is the Open CASCADE Technology realization - of the reference-key model presented in the previous paragraph. - It implements the reference-key as label objects, - organized in a tree structure characterized by the following features: - - * A document contains only one tree of labels - * Each label has a tag expressed as an integer value unique at its level in the tree - * A label is identified by a string — the entry — built by concatenation of tags from the root of the tree, for example [0:1:2:1] - * Attributes are of a type identified by a universal unique identifier (GUID) - * Attributes are attached to labels; a label may refer to many attributes as long as each has a different GUID - - As such, each piece of data has a unique persistent address made up of the document path, - its entry and the GUID of its class. - - In the image the application for designing coffee machines first allocates - a label for the machine unit. It then adds sub-labels for the main features - (glass coffee pot, water receptacle and filter) which it refines as needed - (handle and reservoir of the coffee pot and spout of the reservoir). - - You now attach technical data describing the handle — its geometry and color — - and the reservoir — its geometry and material. - Later on, you can modify the handle's geometry without changing its color — - both remain attached to the same label. - -@image html ocaf_wp_image007.png "Figure 3. The coffee machine" -@image latex ocaf_wp_image007.png "Figure 3. The coffee machine" - -@image html ocaf_wp_image005.png "Figure 4. The data structure of the coffee machine" -@image latex ocaf_wp_image005.png "Figure 4. The data structure of the coffee machine" - - The nesting of labels is key to OCAF. This allows a label to have its own structure - with its local addressing scheme which can be reused in a more complex structure. - Take, for example, the coffee machine. Given that the coffee pot's handle has a label of tag [1], - the entry for the handle in the context of the coffee pot only (without the machine unit) is [0:1:1]. - If you now model a coffee machine with two coffee pots, one at the label [1], - the second at the label [4] in the machine unit, - the handle of the first pot would have the entry [0:1:1:1] - whereas the handle of the second pot would be [0:1:4:1]. - This way, we avoid any confusion between coffee pot handles. - -@subsubsection ocaf_wp_2_2_2 Compound documents - - As the identification of data is persistent, one document can reference data contained in another document, - the referencing and referenced documents being saved in two separate files. - - Lets look at the coffee machine application again. The coffee pot can be placed in one document. - The coffee machine document then includes an *occurrence* — a positioned copy — of the coffee pot. - This occurrence is defined by an XLink attribute (the external Link) - which references the coffee pot of the first document - (the XLink contains the relative path of the coffee pot document and the entry of the coffee pot data [0:1] ). - -@image html ocaf_wp_image006.png "Figure 5. The coffee machine compound document" -@image latex ocaf_wp_image006.png "Figure 5. The coffee machine compound document" - - In this context, the end-user of the coffee machine application can open the coffee pot document, - modify the geometry of, for example, the reservoir, and overwrite the document without worrying - about the impact of the modification in the coffee machine document. - To deal with this situation, OCAF provides a service which allows the application to check - whether a document is up-to-date. This service is based on a modification counter included in each document: - when an external link is created, a copy of the referenced document counter is associated to the XLink - in the referencing document. Providing that each modification of the referenced document increments its own counter, - we can detect that the referencing document has to be updated by comparing the two counters - (an update function importing the data referenced by an XLink into the referencing document is also provided). - - -@subsubsection ocaf_wp_2_2_3 Transaction mechanism - - The Data Framework also provides a transaction mechanism inspired from database management systems: - the data are modified within a transaction which is terminated either by a Commit - if the modifications are validated or by an Abort if the modifications are abandoned — - the data are then restored to the state it was in prior to the transaction. - This mechanism is extremely useful for: - - * Securing editing operations (if an error occurs, the transaction is abandoned and the structure retains its integrity) - * Simplifying the implementation of the Cancel function (when the end-user begins a command, - the application may launch a transaction and operate directly in the data structure; - abandoning the action causes the transaction to Abort) - * Executing Undo (at commit time, the modifications are recorded in order to be able to restore the data to their previous state) - - The transaction mechanism consists simply of managing a backup copy of attributes. - During a transaction, attributes are copied before their first modification. - If the transaction is validated, the copy is destroyed. - If the transaction is abandoned, the attribute is restored to its initial value - (when attributes are added or deleted, the operation is simply reversed). - - Transactions are document-centered, that is, the application starts a transaction on a document. - So, modifying a referenced document and updating one of its referencing documents requires - two transactions, even if both operations are done in the same working session. - -@subsection ocaf_wp_2_3 Persistent Data Storage - -@subsubsection ocaf_wp_2_3_1 Introduction - -In OCAF, persistence, that is, the mechanism used to save a document in a file, is based on an explicit formal description of the data saved. - -When you open a document, the application reads the corresponding file and first creates a memory representation of it. This representation is then converted to the application data model — the OCAF-based data structure the application operates on. The file's memory representation consists of objects defined by classes known as persistent. - -The persistent classes needed by an application to save its documents make the application's data schema. This schema defines the way the data are organized in the file — the format of the data. In other words, the file is simply an ASCII dump of the persistent data defined by the schema, the persistent data being created from the application data model during the save process. - -Only canonical information is saved. As a matter of fact, the application data model usually contains additional data to optimize processing. For example, the persistent Bézier curve is defined by its poles, whereas its data model equivalent also contains coefficients used to compute a point at a given parameter. The additional data is calculated when the document is opened. - -The major advantages of this approach are the following: - * 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, - OCAF provides a framework for managing compatibility of data between versions of the application — - modification of the data format is supported through the versioning of schema. - - OCAF includes a ready-to-use schema suitable for most applications. - However, it can be extended if needed. For that, the only things you have to do are: - - * To define the additional persistent attributes - * To implement the functions converting these persistent attribute to and from the application data model. - -Applications using compound documents extensively (saving data in many files linked together) should implement data management services. As a matter of fact, it's out the scope of OCAF to provide functions such as: -* Version and configuration management of compound documents; -* Querying a referenced document for its referencing documents. - -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): - - * Standard persistence schema, compatible with previous OCAF applications - * XmlOcaf persistence, allowing the storage of all OCAF data in XML form - * BinOcaf 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 Standard 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 Storage package is used to write and read persistent objects. -These objects are read and written by a retrieval or storage algorithm -( Storage_Schema object) in a container (disk, memory, network ...). -Drivers ( FSD_File 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 Storage_Data 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 Storage_Data class, then add the persistent data to write with the function AddRoot, -* call the function Write from the schema, setting the driver and the Storage_Data 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 TCollection 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, PCollection does not include sequences, lists, and so on (unlike TCollection). - -Persistent string and array classes are found in the PCollection package. In addition, PColStd 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 PGeom 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 Geom package: for -each type of transient object provided by Geom there is a corresponding type of persistent -object in the PGeom package. In particular the inheritance structure is parallel. - -However the PGeom 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 Geom objects. To do this you use the MgtGeom::Translate 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 MgtGeom::Translate 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 PGeom package consists simply of a list of available objects. - -The PGeom2d 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 PGeom package, but for the 2D geometric objects provided by the Geom2d package. -Conversions are provided by the MgtGeom::Translate 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 TopoDS_Shape 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 PTopoDS package describes the persistent data model associated with any BRep shape; it is the persistent version of any shape of type TopoDS_Shape. 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 MgtBRep::Translate function. - -The MgtBRepAbs and PTColStd 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 TDocStd_Application -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. - diff --git a/dox/user_guides/user_guides.md b/dox/user_guides/user_guides.md index 289ed21f3c..aa9ff98082 100644 --- a/dox/user_guides/user_guides.md +++ b/dox/user_guides/user_guides.md @@ -16,8 +16,5 @@ OCCT User Guides are organized by OCCT modules: * @subpage occt_user_guides__step "STEP translator" * @subpage occt_user_guides__xde "Extended Data Exchange (XDE)" * @subpage occt_user_guides__ocaf "Open CASCADE Application Framework (OCAF)" - * @subpage occt_user_guides__ocaf_wp "Application Framework White Paper" - * @subpage occt_user_guides__ocaf_functionmechanism_wp "OCAF Function Mechanism" - * @subpage occt_user_guides__ocaf_tree_wp "Distribution of Data through OCAF Tree" * @subpage occt_user_guides__tobj "TObj package" * @subpage occt_user_guides__test_harness "DRAW Test Harness" \ No newline at end of file