0024602: Documentation Code Snippets missing sign
[occt.git] / dox / user_guides / ocaf_wp / ocaf_wp.md
1 OCAF White-Paper {#occt_user_guides__ocaf_wp}
2 ========================
3  @tableofcontents 
4  
5 @section ocaf_wp_1 What is OCAF ?
6
7 @subsection ocaf_wp_1_1 Purpose of  OCAF
8  
9   The Open CASCADE Application Framework (OCAF) is an  easy-to-use platform for rapidly developing
10   sophisticated domain-specific  design applications. 
11   A typical application developed using OCAF deals with two or three-dimensional (2D or 3D) geometric modeling 
12   in trade-specific Computer Aided Design (CAD) systems, manufacturing or analysis applications, 
13   simulation  applications or illustration tools.  
14  
15   Developing a design application requires addressing many technical aspects. 
16   In particular, given the functional specification of your application, you must at least:  
17  
18   * Design the  architecture of the application — definition of the software components and the  way they cooperate
19   * Define the  data model able to support the functionality required — a design application  operates on data maintained during the whole end-user working session
20   * Structure  the software in order to
21     * synchronize the display with the  data — commands modifying objects must update the views  
22     * support generalized undo-redo  commands — this feature has to be taken into account very early in the design  process  
23   * 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
24   * Build the  application user interface
25  
26   By providing architectural guidance and ready-to-use solutions to these issues, 
27   OCAF helps you to develop your application significantly faster: you concentrate on the application's functionality.  
28  
29 @subsection ocaf_wp_1_2 Overview of the Architecture
30  
31   OCAF provides you with an object-oriented Application-Document-Attribute model.
32   This consists of C++ class libraries. The  main class, Application, is an abstract class 
33   in charge of handling documents  during the working session. Services provided by this class include:  
34   * Creating new  documents
35   * Saving  documents and opening them
36   * Initializing  document views
37  
38   The document, implemented by the concrete class  Document, is the container for the application data. 
39   Its main purpose is to  centralize notifications of data editing in order to provide Undo-Redo. 
40   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).  
41  
42   Application data are attributes, that is, instances of  classes derived from the *Attribute* abstract class, 
43   organized according to the OCAF Data  Framework. 
44   The OCAF Data Framework references aggregations of attributes using  persistent identifiers in a single hierarchy (the Data Framework is described <a href="#ocaf_wp_2">in the next chapter</a>). A wide range of  attributes come with OCAF, including:    
45    
46   * Primitive  attributes such as *Integer, Real, Name* and *Comment*;
47   * Shape attribute  containing the geometry of the whole model or elements of it;
48   * Other  geometric attributes such as Datums (points, axis and plane) and Constraints (*tangent-to, at-a-given-distance, from-a-given-angle, concentric,* etc.)
49   * Modeling  step and Function attributes — the purpose of these attributes is to rebuild  objects after they have been modified (parameterization of models)
50   * Visualization  attributes — these attributes allow data to be visualized in a 2D or 3D viewer
51   * User  attributes, that is, attributes typed by the application
52   * In addition,  application-specific data can be added by defining new attribute classes; 
53    naturally, this changes the standard file format. The only functions that have to be implemented are:
54     * Copying the  attribute
55     * Converting  it from and to its persistent homolog (persistence is briefly presented in the paragraph <a href="#ocaf_wp_2_3">Persistent Data Storage</a>)
56
57 @image html ocaf_wp_image003.png "The Application-Document-Attribute model "
58 @image latex ocaf_wp_image003.png "The Application-Document-Attribute model "
59
60 OCAF uses other modules of Open CASCADE Technology — the Shape attribute is implemented with the geometry supported by the <a href="#user_guides__modeling_data">Modeling Data</a> module and the viewer is the one provided with the <a href="#user_guides__visualization">Visualization</a> module. Modeling functions can be implemented using the <a href="#user_guides__modeling_algos">Modeling Algorithms</a> module.
61  
62 @subsection ocaf_wp_1_3 Getting  Started
63
64   At the beginning of your development, you first define  an application class by inheriting from the Application abstract class. 
65   You only have to create and determine the resources of the application 
66   for specifying the format of your documents (you generally use the standard one)  and their file extension.  
67    
68   Then, you design the application data model by  organizing attributes you choose among those provided with OCAF. 
69   You can specialize these attributes using the User attribute. For example, if you need  a reflection coefficient, 
70   you aggregate a User attribute identified as a  reflection coefficient 
71   with a Real attribute containing the value of the  coefficient (as such, you don't define a new class).  
72    
73   If you need application specific data not provided with  OCAF, for example, 
74   to incorporate a finite element model in the data structure,  
75   you define a new attribute class containing the mesh, 
76   and you include its persistent homolog in a new file format.  
77    
78   Once you have implemented the commands which create and modify the data structure 
79   according to your specification, OCAF provides you, without any additional programming:  
80    
81   * Persistent  reference to any data, including geometric elements — several documents can be  linked with such reference;
82   * Document-View  association;
83   * Ready-to-use  functions such as :
84     * Undo-redo;  
85     * Save and open application data.  
86  
87   Finally, you  develop the application's graphical user interface using the toolkit of your  choice, for example:
88   * KDE Qt or  GNOME GTK+ on Linux;
89   * Microsoft  Foundation Classes (MFC) on Windows Motif on Sun;
90   * Other  commercial products such as Ilog Views.
91  
92   You can also implement the user interface in the Java language using 
93   the Swing-based Java Application Desktop component (JAD)  provided with OCAF.  
94  
95 @subsection ocaf_wp_1_4 Benefits  of OCAF
96
97   As you use the architecture provided by OCAF, the design  of your application is made easy: 
98   the application developer concentrates on the functionality 
99   instead of the underlying mechanisms required to support this functionality.  
100  
101   Also, thanks to the coupling with the other Open CASCADE Technology modules, 
102   your application can rapidly be prototyped. In addition, the final application 
103   can be developed by industrializing the prototype — you don't need to restart the development from scratch.  
104  
105   Last but not least, you base your application on an Open Source component: 
106   this guarantees the long-term usefulness of your development.  
107  
108 @section ocaf_wp_2 A Look Inside OCAF
109
110 @subsection ocaf_wp_2_1 The Design  of OCAF
111  
112 @subsubsection ocaf_wp_2_1_1 Reference-key model
113  
114   In most existing geometric modeling systems, the data are topology driven. 
115   They usually use a boundary representation (BRep), where geometric models 
116   are defined by a collection of faces, edges and vertices, 
117   to which application data are attached. Examples of data include:  
118  
119   * a color;
120   * a material;
121   * information that a particular edge is blended.
122  
123   When the geometric model is parameterized, that is, when you can change 
124   the value of parameters used to build the model (the radius of a  blend, the thickness of a rib, etc.), 
125   the geometry is highly subject to change. 
126   In order to maintain the attachment of application data, the geometry must be  distinguished from other data.  
127    
128   In OCAF, the data are reference-key driven. It is a  uniform model in which reference-keys 
129   are the persistent identification of  data. All **accessible** data, including the geometry, 
130   are implemented as attributes attached to reference-keys. 
131   The geometry becomes the  value of the Shape attribute, just as a number is the value 
132   of the Integer and  Real attributes and a string that of the Name attribute.  
133    
134   On a single reference-key, many attributes can be  aggregated; 
135   the application can ask at runtime which attributes are available. 
136   For example, to associate a texture to a face in a geometric model, 
137   both the face and the texture are attached to the same reference-key.  
138  
139 @image html ocaf_wp_image004.png "Figure 2. Topology driven versus reference-key driven approaches" 
140 @image latex ocaf_wp_image004.png "Figure 2. Topology driven versus reference-key driven approaches" 
141  
142 @subsubsection ocaf_wp_2_1_2 Topological naming
143  
144   Reference-keys can be created in two ways:   
145  
146   * At  programming time, by the application
147   * At runtime,  by the end-user of the application (providing that you include this capability  in the application)
148  
149   As an application developer, you generate reference-keys in order to give semantics to the data. 
150   For example, a function building a  prism may create three reference-keys: 
151   one for the base of the prism, a second  for the lateral faces and a third for the top face. 
152   This makes up a semantic  built-in the application's prism feature.
153   On the other hand, in a command  allowing the end-user to set a texture to a face he/she selects, 
154   you must create  a reference-key to the selected face 
155   if it has not previously been referenced in any feature 
156   (as in the case of one of the lateral faces of the prism).  
157  
158   When you create a reference-key to selected topological  elements (faces, edges or vertices), 
159   OCAF attaches to the reference-key  information defining the selected topology — the Naming attribute. 
160   For example,  it may be the faces to which a selected edge is common to. 
161   This information, as  well as information about the evolution of the topology at each modeling step 
162   (the modified, updated and deleted faces), is used by the naming algorithm to  maintain the topology 
163   attached to the reference-key. As such, on a  parametrized model, 
164   after modifying the value of a parameter, the reference-keys still address the appropriate faces, 
165   even if their geometry has  changed. 
166   Consequently, you change the size of the cube shown in the figure 2 above, 
167   the user texture stay attached to the right face.  
168  
169   <b>Note</b> As Topological naming is based on the reference-key and attributes such as Naming 
170   (selection information) and Shape (topology evolution  information), 
171   OCAF is not coupled to the underlying modeling libraries. 
172   The  only modeling services required by OCAF are the following:  
173
174   * Each  algorithm must provide information about the evolution of the topology 
175    (the  list of faces modified, updated and deleted by the algorithm)
176   * Exploration  of the geometric model must be available 
177    (a 3D model is made of faces bounded  by close wires, 
178    themselves composed by a sequence of edges connected by their  vertices)
179  
180   Currently, OCAF uses the Open CASCADE Technology  modeling libraries.   
181  
182 @subsubsection ocaf_wp_2_1_3 Aggregation of attributes
183  
184   To design an OCAF-based data model, the application  developer is encouraged to aggregate 
185   ready-to-use attributes instead of defining new attributes by inheriting from an abstract root class.  
186   There are two major advantages in using aggregation  rather than inheritance:
187   
188   * As you don't  implement data by defining new classes, the format of saved data 
189     provided with OCAF doesn't change; so you don't have to write the Save and Open functions
190   * The application can query the data at runtime if a particular attribute is  available
191  
192 @subsubsection ocaf_wp_2_1_4 Summary
193  
194   * OCAF is  based on a uniform reference-key model in which:
195     * Reference-keys provide  persistent identification of data;  
196     * Data, including geometry, are  implemented as attributes attached to reference-keys;  
197     * Topological naming maintains the  selected geometry attached to reference-keys in parametrized models ; 
198   * In many  applications, the data format provided with OCAF doesn't need to be extended;
199   * OCAF is not  coupled to the underlying modeling libraries.
200  
201 @subsection ocaf_wp_2_2 The Data  Framework
202  
203 @subsubsection ocaf_wp_2_2_1 Data structure
204  
205   The OCAF Data Framework is the Open CASCADE Technology  realization 
206   of the reference-key model presented in the previous paragraph. 
207   It implements the reference-key as label objects, 
208   organized in a tree structure characterized by the following features:  
209  
210   * A document  contains only one tree of labels
211   * Each label  has a tag expressed as an integer value unique at its level in the tree
212   * 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]
213   * Attributes  are of a type identified by a universal unique identifier (GUID)
214   * Attributes  are attached to labels; a label may refer to many attributes as long as each  has a different GUID
215  
216   As such, each piece of data has a unique persistent address made up of the document path, 
217   its entry and the GUID of its class.  
218  
219   In the image the application for designing coffee  machines first allocates 
220   a label for the machine unit. It then adds sub-labels  for the main features 
221   (glass coffee pot, water receptacle and filter) which it  refines as needed 
222   (handle and reservoir of the coffee pot and spout of the  reservoir). 
223   
224   You now attach technical data describing the handle — its geometry and color — 
225   and the reservoir — its geometry and material. 
226   Later on, you can  modify the handle's geometry without changing its color — 
227   both remain attached  to the same label.  
228  
229 @image html ocaf_wp_image005.png "Figure 3. The data structure of the coffee machine"  
230 @image latex ocaf_wp_image005.png "Figure 3. The data structure of the coffee machine"  
231  
232   The nesting of labels is key to OCAF. This allows a  label to have its own structure 
233   with its local addressing scheme which can be  reused in a more complex structure. 
234   Take, for example, the coffee machine.  Given that the coffee pot's handle has a label of tag [1], 
235   the entry for the handle in  the context of the coffee pot only (without the machine unit) is [0:1:1]. 
236   If you now model a coffee  machine with two coffee pots, one at the label [1], 
237   the second at the label [4] in the machine unit, 
238   the handle  of the first pot would have the entry [0:1:1:1] 
239   whereas the handle of the second pot would be [0:1:4:1]. 
240   This way, we avoid any  confusion between coffee pot handles.
241  
242 @subsubsection ocaf_wp_2_2_2 Compound documents
243  
244   As the identification of data is persistent, one document can reference data contained in another document, 
245   the referencing and  referenced documents being saved in two separate files.  
246  
247   Lets look at the coffee machine application again. The  coffee pot can be placed in one document. 
248   The coffee machine document then  includes an *occurrence* — a positioned copy — of the coffee pot. 
249   This occurrence is defined by an XLink attribute (the external Link) 
250   which references the coffee pot of the first document 
251   (the XLink contains the relative path of the coffee pot document and the entry of the coffee pot data [0:1] ).  
252
253 @image html ocaf_wp_image006.png "The coffee machine compound document"
254 @image latex ocaf_wp_image006.png "The coffee machine compound document"
255  
256   In this context, the end-user of the coffee machine application can open the coffee pot document, 
257   modify the geometry of, for  example, the reservoir, and overwrite the document without worrying 
258   about the impact of the modification in the coffee machine document. 
259   To deal with this  situation, OCAF provides a service which allows the application to check 
260   whether a document is up-to-date. This service is based on a modification counter included in each document: 
261   when an external link is created, a copy of  the referenced document counter is associated to the XLink 
262   in the referencing  document. Providing that each modification of the referenced document increments its own counter, 
263   we can detect that the referencing document has to  be updated by comparing the two counters 
264   (an update function importing the data  referenced by an XLink into the referencing document is also provided).  
265  
266  
267 @subsubsection ocaf_wp_2_2_3 Transaction mechanism
268  
269   The Data Framework also provides a transaction mechanism inspired from database management systems: 
270   the data are modified within a transaction which is terminated either by a Commit 
271   if the modifications are validated  or by an Abort if the modifications are abandoned — 
272   the data are then restored  to the state it was in prior to the transaction. 
273   This mechanism is extremely useful for:
274
275   * Securing  editing operations (if an error occurs, the transaction is abandoned and the  structure retains its integrity)
276   * Simplifying  the implementation of the Cancel function (when the end-user begins a command, 
277   the application may launch a transaction and operate directly in the data structure; 
278   abandoning the action causes the transaction to Abort)
279   * Executing  Undo (at commit time, the modifications are recorded in order to be able to  restore the data to their previous state)
280  
281   The transaction mechanism consists simply of managing a  backup copy of attributes. 
282   During a transaction, attributes are copied before  their first modification. 
283   If the transaction is validated, the copy is  destroyed. 
284   If the transaction is abandoned, the attribute is restored to its initial value 
285   (when attributes are added or deleted, the operation is simply  reversed).
286
287   Transactions are document-centered, that is, the application starts a transaction on a document. 
288   So, modifying a referenced  document and updating one of its referencing documents requires 
289   two transactions, even if both operations are done in the same working session.
290
291 @subsection ocaf_wp_2_3 Persistent  Data Storage
292
293   In OCAF, persistence, that is, the mechanism used to  save a document in a file, 
294   is based on an explicit formal description of the  data saved.  
295  
296   When you open a document, the application reads the corresponding file 
297   and first creates a memory representation of it. 
298   This representation is then converted to the application data model — 
299   the OCAF-based data structure the application operates on. 
300   The file's memory representation  consists of objects defined by classes known as persistent. 
301   The persistent  classes needed by an application to save its documents make the application's data schema.
302   This schema defines the way the data are organized in the file — the format of the data. 
303   In other words, the file is simply an ASCII dump of the  persistent data defined by the schema, 
304   the persistent data being created from  the application data model during the save process.  
305    
306   Only canonical information is saved. As a matter of  fact, 
307   the application data model usually contains additional data to optimize  processing. 
308   For example, the persistent Bézier curve is defined by its poles, whereas 
309   its data model equivalent also contains coefficients used to compute a point at a given parameter. 
310   The additional data is calculated when the document is opened.  
311  
312   The major advantages of this approach are the following:  
313   
314   * Providing  that the data format is published, files created by OCAF-based applications 
315    can be read without needing a runtime of the application (openness)
316   * Although the  persistence approach makes the data format more stable, 
317    OCAF provides a  framework for managing compatibility of data between versions of the application — 
318    modification of the data format is supported through the  versioning of schema.
319  
320   OCAF includes a ready-to-use schema suitable for most  applications. 
321   However, it can be extended if needed. For that, the only things  you have to do are:  
322
323   * To define  the additional persistent attributes
324   * To implement  the functions converting these persistent attribute to and from the application  data model.
325   
326 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:
327 * Version and configuration management of compound documents;
328 * Querying a referenced document for its referencing documents.
329
330 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.
331
332