0024722: Move functionality of WOK command wgendoc to OCCT tool gendoc
[occt.git] / dox / user_guides / ocaf_tree_wp / ocaf_tree_wp.md
1  Distribution of Data Through OCAF Tree {#occt_user_guides__ocaf_tree_wp}
2 =======================================
3 @tableofcontents 
4  
5 @section occt_ocaf_tree_wp_1 Introduction
6
7   Open CASCADE Application Framework (OCAF) represents a set of classes for Rapid Application Development. 
8   OCAF helps to  implement such functions as undo and redo, copy, cut and paste, storage and  retrieval of documents, and many others.  
9    
10   OCAF is based on a notion of label-attribute. The labels form a tree. 
11   The attributes are attached to the labels and store user data in the OCAF document.  
12  
13 This document describes how data should be stored in the OCAF document and considers the following issues:
14   
15   * Should we choose standard attributes  or is it better to create new ones?
16   * How can we optimize data allocation to make it easy to use and efficient for memory usage and application speed?
17  
18 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.
19
20  
21 @section occt_ocaf_tree_wp_2 Description
22
23   When you start to design an application  based on OCAF, 
24   usually you need to choose between standard and newly-created attributes 
25   to be used for allocation of data in the OCAF document. 
26   Before giving an answer to this question, let’s overview standard OCAF attributes.  
27    
28   All basic data types are represented in OCAF as special attributes: 
29   * Integer, 
30   * Double,
31   * String,
32   * Array of integer values,
33   * Array of double values,
34   * Array of string values,
35   * Topological shapes.
36
37   An attentive reader might have noticed that there is no Boolean type. 
38   This is because the  Integer type is usually used instead.  
39    
40   So, we have an opportunity to describe any model by means of standard OCAF attributes. 
41   But will this description be  efficient for memory, speed, and, at the same time, convenient to use? 
42   It  depends on a particular model.  
43    
44   OCAF has one restriction: only one  attribute type may be allocated to one label. 
45   It is necessary to take into  account the design of the application data tree. 
46   For example, if a label should  possess several double values, 
47   it is necessary to distribute them through several child sub-labels or use an array of double values.   
48    
49   Let’s consider several boundary implementations of the same model in OCAF tree 
50   and analyse the advantages and disadvantages of each approach.  
51
52 @section occt_ocaf_tree_wp_3 Comparison  and analysis of approaches
53
54   Below are described two different model implementations: 
55   one is based on standard OCAF attributes and the other is based 
56   on the creation of a new attribute possessing all data of the model.  
57    
58   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 
59   to convert the local co-ordinate system to the global one, but this is optional.   
60    
61   So, we have 15 double values at each point  of measurement. 
62   If the number of such points is 100 000, for example, it means 
63   that we have to store 1 500 000 double values in the OCAF document.  
64    
65   The first  approach consists in using standard OCAF attributes. 
66   Besides, there are several  variants of how the standard attributes may be used:  
67   * Allocation of all 1 500 000 double values as one array of double values attached to one label;
68   * 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;
69   * 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.  
70   
71   Certainly, other variants are also  possible.   
72  
73 @image html ocaf_tree_wp_image003.png "Allocation of all data as one  array of double values"
74 @image latex ocaf_tree_wp_image003.png "Allocation of all data as one  array of double values"
75  
76   The first approach to allocation of all  data represented as one array of double values 
77   saves initial memory and is easy to implement. 
78   But access to the data is difficult because the values are stored in a flat array. 
79   It will be necessary to implement a class with several methods giving access 
80   to particular fields like the measurement points, loads and so  on.  
81    
82   If the values may be edited in the  application, 
83   it means that the whole array will be backed-up on each edition. 
84   The memory usage will increase very fast! 
85   So, this approach may be considered only in case of non-editable data.  
86    
87   Let’s consider the allocation of data of  each measurement point per label (the second case). 
88   In this case we create 100  000 labels – one label for each measurement point 
89   and attach an array of double  values to these labels:  
90  
91 @image html ocaf_tree_wp_image004.png "Allocation of data of each  measurement point as arrays of double values"
92 @image latex ocaf_tree_wp_image004.png "Allocation of data of each  measurement point as arrays of double values"
93  
94   Now edition of data is safer as far as  memory usage is concerned. 
95   Change of value for one measurement point (any  value: point co-ordinates, load, and so on) 
96   backs-up only one small array of double values. 
97   But this structure (tree) requires more memory space (additional  labels and attributes).  
98    
99   Besides, access to the values is still difficult and it is necessary 
100   to have a class with methods of access to the  array fields.  
101    
102   The third case of allocation of data  through OCAF tree is represented below:  
103
104 @image html ocaf_tree_wp_image005.png "Allocation of data into separate arrays of double values"
105 @image latex ocaf_tree_wp_image005.png "Allocation of data into separate arrays of double values"
106
107   In this case sub-labels are involved and we  can easily access the values of each measurement point, 
108   load or matrix. We don’t need an interface class with methods of access to the data 
109   (if it exists, it would help to use the data structure, but this is optional).  
110
111   On the one hand, this approach requires more  memory for allocation of the attributes (arrays of double values). 
112   On the other  hand, it saves memory during the edition of data 
113   by backing-up only the small array containing the modified data. 
114   So, if the data is fully modifiable, this  approach is more preferable.  
115
116   Before making a conclusion, let’s consider the same model implemented through a newly created OCAF attribute.  
117
118   For example, we might allocate all data  belonging to one measurement point as one OCAF attribute. 
119   In this case we  implement the third variant of using the standard attributes (see picture 3), 
120   but we use less memory (because we use only one attribute instead of three):  
121  
122 @image html ocaf_tree_wp_image006.png "Allocation of data into newly  created OCAF attribute"
123 @image latex ocaf_tree_wp_image006.png "Allocation of data into newly  created OCAF attribute"
124
125   The second variant of using standard OCAF attributes still has drawbacks: 
126   when data is edited, OCAF backs-up all values  of the measurement point.   
127    
128   Let’s imagine that we have some  non-editable data. 
129   It would be better for us to allocate this data separately from editable data. 
130   Back-up will not affect non-editable data and memory will not increase so much during data edition.  
131  
132 @section occt_ocaf_tree_wp_4 Conclusion
133
134   When deciding which variant of data model implementation to choose, 
135   it is necessary to take into account the application  response time, 
136   memory allocation and memory usage in transactions.   
137    
138   Most of the models may be implemented using only standard OCAF attributes. 
139   Some other models need special treatment and require implementation of new OCAF attributes.