08b55aa76f4104504fd75f994aadb34caf6f5320
[occt.git] / dox / user_guides / xde / xde.md
1  Extended Data Exchange (XDE)  {#occt_user_guides__xde}
2 ============================
3
4 @tableofcontents
5
6 @section occt_xde_1_ Introduction
7 @subsection occt_xde_1_1 Overview of the Extended Data Exchange (XDE)
8 This manual explains how to use the Extended Data Exchange (XDE). It provides basic documentation on setting up and using XDE. For advanced information on XDE and its applications, see our offerings  at <a href="http://www.opencascade.com/services/support/">on our web site</a>. 
9
10 Based on document architecture, XDE allows processing of various types of data to and from external files. 
11
12 XDE is available for users of Open CASCADE Technology on all supported platforms (Linux, Windows).
13  
14 @subsubsection occt_xde_1_1_1 Prerequisite
15 The Extended Data Exchange (XDE) component requires Advanced Shape Healing for operation. 
16
17 @subsubsection occt_xde_1_1_2 Environment variables
18 To use XDE you have to set the environment variables properly. Make sure that two important environment variables are set as follows: 
19   * *CSF_PluginDefaults* points to sources of  <i>\%CASROOT%/src/XCAFResources ($CASROOT/src/XCAFResources)</i>.
20   * *CSF_XCAFDefaults* points to sources of <i>\%CASROOT%/src/XCAFResources ($CASROOT/src/XCAFResources)</i>.
21 @subsubsection occt_xde_1_1_3 Basic terms
22 For better understanding of XDE, certain key terms are defined: 
23 * **Shape** - a standalone shape, which does not belong to the assembly structure.
24 * **Instance** - a replication of another shape with a location that can be the same location or a different one.
25 * **Assembly** - a construction that is either a root or a sub-assembly. 
26 @subsubsection occt_xde_1_1_4 XDE Data Types
27 The following types of data are currently supported: 
28   * assemblies
29   * validation properties
30   * names
31   * colors
32   * layers
33 It is also possible to add new types of data by using tools as prototypes. This makes XDE a basically extensible framework. 
34
35 In addition, XDE provides reading and writing tools to read and write the data supported by STEP and IGES files. 
36 @subsubsection occt_xde_1_1_5 XDE Organization
37 The basis of XDE, called XCAF, is a framework based on OCAF (Open CASCADE Technology Application Framework) and is intended to be used with assemblies and with various kinds of attached data (attributes). Attributes can be Individual attributes for a shape, specifying some characteristics of a shape, or they can be Grouping attributes, specifying that a shape belongs to a given group whose definition is specified apart from the shapes. 
38
39 XDE works in an OCAF document with a specific organization defined in a dedicated XCAF module. This organization is used by various functions of XDE to exchange standardized data other than shapes and geometry. 
40
41 The Assembly Structure and attributes assigned to shapes are stored in the OCAF tree. It is possible to obtain TopoDS representation for each level of the assembly in the form of *TopoDS_Compound* or *TopoDS_Shape* using the API. 
42
43 Basic elements used by XDE are introduced in the XCAF sub-module by the package XCAFDoc. These elements consist in descriptions of commonly used data structures (apart from the shapes themselves) in normalized data exchanges. They are not attached to specific applications and do not bring specific semantics, but are structured according to the use and needs of data exchanges. 
44 The Document used by XDE usually starts as a *TDocStd_Document*. 
45
46 @subsubsection occt_xde_1_1_6 Assemblies
47 XDE supports assemblies by separating shape definitions and their locations. Shapes are simple OCAF objects without a location definition. An assembly consists of several components. Each of these components references one and the same specified shape with different locations. All this provides an increased flexibility in working on multi-level assemblies. 
48
49 For example, a mechanical assembly can be defined as follows: 
50 @image html /user_guides/xde/images/xde_image003.png "Assembly Description"
51 @image latex /user_guides/xde/images/xde_image003.png "Assembly Description"
52
53
54 @image html /user_guides/xde/images/xde_image004.png "Assembly View"
55 @image latex /user_guides/xde/images/xde_image004.png "Assembly View"
56
57
58 XDE defines the specific organization of the assembly content. Shapes are stored on sub-labels of label 0:1:1. There can be one or more roots (called free shapes) whether they are true trees or simple shapes. A shape can be considered to be an Assembly (such as AS1 under 0:1:1:1 in Figure1) if it is defined with Components (sub-shapes, located or not). 
59
60 *XCAFDoc_ShapeTool* is a tool that allows you to manage the Shape section of the XCAF document. This tool is implemented as an attribute and located at the root label of the shape section. 
61
62 @subsubsection occt_xde_1_1_7 Validation Properties
63 Validation properties are geometric characteristics of Shapes (volume, centroid, surface area) written to STEP files by the sending system. These characteristics are read by the receiving system to validate the quality of the translation. This is done by comparing the values computed by the original system with the same values computed by the receiving system on the resulting model. 
64
65 Advanced Data Exchange supports both reading and writing of validation properties, and provides a tool to check them. 
66
67 @image html /user_guides/xde/images/xde_image005.png "Validation Property Descriptions" 
68 @image latex /user_guides/xde/images/xde_image005.png "Validation Property Descriptions" 
69
70
71
72 Check logs contain deviations of computed values from the values stored in a STEP file. A typical example appears as follows: 
73
74 | Label | Area defect   | Volume defect | dX    | dY    | DZ    | Name |
75 | :---- | :----- | :----- | :----- | :---- | :---- | :---- |
76 | 0:1:1:1 | 312.6 (0%) | -181.7 (0%) | 0.00 | 0.00 | 0.00       | "S1" |
77 | 0:1:1:2 |  -4.6 (0%) | -191.2 (0%)    | -0.00  | 0.00 | -0.00 | "MAINBODY" |
78 | 0:1:1:3 | -2.3 (0%) | -52.5 (0%)      | -0.00 | 0.00  | 0.00 | "MAIN_BODY_BACK" |
79 | 0:1:1:4 | -2.3 (0%) | -51.6 (0%) | 0.00 |     0.00 | -0.00 | "MAIN_BODY_FRONT" |
80 | 0:1:1:5 | 2.0 (0%) | 10.0 (0%) | -0.00 |      0.00 |  -0.00 | "HEAD" |
81 | 0:1:1:6 | 0.4 (0%) | 0.0 (0%) |       0.00    | -0.00 | -0.00 | "HEAD_FRONT" |
82 | 0:1:1:7 |  0.4 (0%) | 0.0 (0%) | 0.00 | -0.00 | -0.00 | "HEAD_BACK" |
83 | 0:1:1:8 | -320.6 (0%) | 10.9 (0%)     | -0.00 | 0.00 | 0.00 | "TAIL" |
84 | 0:1:1:9 | 0.0 (0%) | 0.0 (0%) | -0.00 | -0.00 | 0.00 | "TAIL_MIDDLE" |
85 | 0:1:1:10 | -186.2 (0%) |      4.8 (0%) |      -0.00 | 0.00 | -0.00 | "TAIL_TURBINE" |
86 | 0:1:1:11 | 0.3 (0%) | -0.0 (0%) |     -0.00 | -0.00 | 0.00 |  "FOOT" |
87 | 0:1:1:12      | 0.0 (0%) | -0.0 (0%) | 0.00 | -0.00 | -0.00 |"FOOT_FRONT" |
88 | 0:1:1:13 | 0.0 (0%) | 0.0 (0%) | -0.00 | 0.00 | 0.00 | "FOOT_BACK" |
89
90
91 In our example, it can be seen that no errors were detected for either area, volume or positioning data. 
92
93 @subsubsection occt_xde_1_1_8 Names
94 XDE supports reading and writing the names of shapes to and from IGES and STEP file formats. This functionality can be switched off if you do not need this type of data, thereby reducing the size of the document. 
95 @subsubsection occt_xde_1_1_9 Colors and Layers
96 XDE can read and write colors and layers assigned to shapes or their subparts (down to the level of faces and edges) to and from both IGES and STEP formats. Three types of colors are defined in the enumeration *XCAFDoc_ColorType*: 
97   * generic color <i>(XCAFDoc_ColorGen)</i>
98   * surface color <i>(XCAFDoc_ColorSurf)</i>
99   * curve color <i>(XCAFDoc_ColorCurv)</i>
100
101         @image html /user_guides/xde/images/xde_image006.png "Colors and Layers" 
102     @image latex /user_guides/xde/images/xde_image006.png "Colors and Layers" 
103
104
105
106 @section occt_xde_2_ Basic Concepts
107 @subsection occt_xde_2_1 Overview
108 As explained in the last chapter, XDE uses *TDocStd_Documents* as a starting point. The general purpose of XDE is: 
109   * Checking if an existing document is fit for XDE
110   * Getting an application and initialized document
111   * Initializing a document to fit it for XDE
112   * Adding, setting and finding data
113   * Querying and managing shapes
114   * Attaching properties to shapes
115 The Document used by XDE usually starts as a TDocStd_Document. 
116
117 @subsubsection occt_xde_2_1_1 General Check
118 Before working with shapes, properties, and other types of information, the global organization of an XDE Document can be queried or completed to determine if an existing Document is actually structured for use with XDE. 
119
120 To find out if an existing *TDocStd_Document* is suitable for XDE, use: 
121 ~~~~~
122 Handle(TDocStd_Document) doc... 
123 if ( XCAFDoc_DocumentTool::IsXCAFDocument (doc) ) { .. yes .. } 
124 ~~~~~
125 If the Document is suitable for XDE, you can perform operations and queries explained in this guide. However, if a Document is not fully structured for XDE, it must be initialized. 
126
127 @subsubsection occt_xde_2_1_2 Get an Application or an Initialized Document
128 If you want to retrieve an existing application or an existing document (known to be correctly structured for XDE), use: 
129 ~~~~~
130 Handle(TDocStd_Document) aDoc; 
131 Handle(XCAFApp_Application) anApp = XCAFApp_Application::GetApplication(); 
132 anApp->NewDocument(;MDTV-XCAF;,aDoc); 
133 ~~~~~
134 @subsection occt_xde_2_2 Shapes and Assemblies
135
136 @subsubsection occt_xde_2_2_1 Initialize an XDE Document (Shapes)
137 An XDE Document begins with a *TDocStd_Document*. Assuming you have a *TDocStd_Document* already created, you can ensure that it is correctly structured for XDE by initializing the XDE structure as follows: 
138 ~~~~~
139 Handle(TDocStd_Document) doc... 
140 Handle (XCAFDoc_ShapeTool) myAssembly = 
141 XCAFDoc_DocumentTool::ShapeTool (Doc->Main()); 
142 TDF_Label aLabel = myAssembly->NewShape() 
143 ~~~~~
144 **Note** that the method *XCAFDoc_DocumentTool::ShapeTool* returns the *XCAFDoc_ShapeTool*. The first time this method is used, it creates the *XCAFDoc_ShapeTool*. In our example, a handle is used for the *TDocStd_Document*.
145
146 @subsubsection occt_xde_2_2_2 Get a Node considered as an Assembly
147 To get a node considered as an Assembly from an XDE structure, you can use the Label of the node. Assuming that you have a properly initialized *TDocStd_Document*, use: 
148 ~~~~~
149 Handle(TDocStd_Document) doc... 
150 Handle(XCAFDoc_ShapeTool) myAssembly = XCAFDoc_DocumentTool::ShapeTool (aLabel); 
151 ~~~~~
152 In the previous example, you can also get the Main Item of an XDE document, which records the root shape representation (as a Compound if it is an Assembly) by using *ShapeTool(Doc->Main())* instead of *ShapeTool(aLabel)*. 
153
154 You can then query or edit this Assembly node, the Main Item or another one (*myAssembly* in our examples). 
155
156 **Note** that for the examples in the rest of this guide, *myAssembly* is always presumed to be accessed this way, so this information will not be repeated.
157
158 @subsubsection occt_xde_2_2_3 Updating the Assembly after Filling or Editing
159 Some actions in this chapter affect the content of the document, considered as an Assembly. As a result, you will sometimes need to update various representations (including the compounds). 
160
161 To update the representations, use: 
162 ~~~~~
163 myAssembly->UpdateAssembly(aLabel); 
164 ~~~~~
165 Since this call is always used by the editing functions, you need not apply it for such functions. However, you will need this call if special edits, not using XCAF functions, are used on the document. 
166
167 @subsubsection occt_xde_2_2_4 Adding or Setting Top Level Shapes
168
169 Shapes can be added as top-level shapes. Top level means that they can be added to an upper level assembly or added on their own at the highest level as a component or referred by a located instance. Therefore two types of top-level shapes can be added: 
170   * shapes with upper level references
171   * free shapes (that correspond to roots) without any upper reference
172
173 **Note** that several top-level shapes can be added to the same component.
174  
175 A shape to be added can be defined as a compound (if required), with the following interpretations: 
176   * If the Shape is a compound, according to the user choice, it may or may not be interpreted as representing an Assembly. If it is an Assembly, each of its sub-shapes defines a sub-label. 
177   * If the Shape is not a compound, it is taken as a whole, without breaking it down. 
178   
179 To break down a Compound in the assembly structure, use: 
180 ~~~~~
181 Standard_Boolean makeAssembly; 
182 // True to interpret a Compound as an Assembly, 
183 // False to take it as a whole 
184 aLabel = myAssembly->AddShape(aShape, makeAssembly); 
185 ~~~~~
186 Each node of the assembly therefore refers to its sub-shapes. 
187
188 Concerning located instances of sub-shapes, the corresponding shapes, (without location) appear at distinct sub-labels. They are referred to by a shape instance, which associates a location. 
189
190 @subsubsection occt_xde_2_2_5 Setting a given Shape at a given Label
191 A top-level shape can be changed. In this example, no interpretation of compound is performed: 
192 ~~~~~
193 Standard_CString LabelString ...; 
194 // identifies the Label (form ;0:i:j...;) 
195 TDF_Label aLabel...; 
196 // A label must be present 
197 myAssembly->SetShape(aLabel, aShape); 
198 ~~~~~
199
200 @subsubsection occt_xde_2_2_6 Getting a Shape from a Label
201 To get a shape from its Label from the top-level, use: 
202 ~~~~~
203 TDF_Label aLabel...
204 // A label must be present
205 if (aLabel.IsNull()) { 
206   // no such label : abandon
207 }
208 TopoDS_Shape aShape;
209 aShape = myAssembly->GetShape(aLabel);
210 if (aShape.IsNull()) {
211   // this label is not for a Shape
212 }
213 ~~~~~
214 **Note** that if the label corresponds to an assembly, the result is a compound. 
215
216 @subsubsection occt_xde_2_2_7 Getting a Label from a Shape
217 To get a Label, which is attached to a Shape from the top-level, use: 
218 ~~~~~
219 Standard_Boolean findInstance = Standard_False; 
220 // (this is default value)
221 aLabel = myAssembly->FindShape(aShape [,findInstance]);
222 if (aLabel.IsNull()) { 
223   // no label found for this shape
224 }
225 ~~~~~
226 If *findInstance* is True, a search is made for the shape with the same location. If it is False (default value), a search is made among original, non-located shapes. 
227
228 @subsubsection occt_xde_2_2_8 Other Queries on a Label
229
230 Various other queries can be made from a Label within the Main Item of XDE: 
231 #### Main Shapes
232
233 To determine if a Shape is recorded (or not), use: 
234 ~~~~~
235 if ( myAssembly->IsShape(aLabel) ) { .. yes .. } 
236 ~~~~~
237
238 To determine if the shape is top-level, i.e. was added by the *AddShape* method, use: 
239 ~~~~~
240 if ( myAssembly->IsTopLevel(aLabel) ) { .. yes .. } 
241 ~~~~~
242
243 To get a list of top-level shapes added by the *AddShape* method, use: 
244 ~~~~~
245 TDF_LabelSequence frshapes; 
246 myAssembly->GetShapes(frshapes); 
247 ~~~~~
248
249 To get all free shapes at once if the list above has only one item, use: 
250 ~~~~~
251 TopoDS_Shape result = myAssembly->GetShape(frshapes.Value(1)); 
252 ~~~~~
253
254 If there is more than one item, you must create and fill a compound, use: 
255
256 ~~~~~
257 TopoDS_Compound C; 
258 BRep_Builder B; 
259 B.MakeCompound(C); 
260 for(Standard_Integer i=1; i=frshapes.Length(); i++) { 
261   TopoDS_Shape S = myAssembly->GetShape(frshapes.Value(i)); 
262   B.Add(C,S); 
263
264 ~~~~~
265
266 In our example, the result is the compound C. 
267 To determine if a shape is a free shape (no reference or super-assembly), use: 
268
269 ~~~~~
270 if ( myAssembly->IsFree(aLabel) ) { .. yes .. } 
271 ~~~~~
272
273 To get a list of Free Shapes (roots), use: 
274
275 ~~~~~
276 TDF_LabelSequence frshapes; 
277 myAssembly->GetFreeShapes(frshapes); 
278 ~~~~~
279
280 To get the shapes, which use a given shape as a component, use: 
281 ~~~~~
282 TDF_LabelSequence users; 
283 Standard_Integer nbusers = myAssembly->GetUsers(aLabel,users); 
284 ~~~~~
285 The count of users is contained with *nbusers*. It contains 0 if there are no users. 
286
287 #### Assembly and Components
288 To determine if a label is attached to the main part or to a sub-part (component), use: 
289 ~~~~~
290 if (myAssembly->IsComponent(aLabel)) { .. yes .. } 
291 ~~~~~
292 To determine whether a label is a node of a (sub-) assembly or a simple shape, use: 
293 ~~~~~
294 if ( myAssembly->IsAssembly(aLabel) ) { .. yes .. } 
295 ~~~~~
296
297 If the label is a node of a (sub-) assembly, you can get the count of components, use: 
298 ~~~~~
299 Standard_Boolean subchilds = Standard_False; //default 
300 Standard_Integer nbc = myAssembly->NbComponents (aLabel [,subchilds]); 
301 ~~~~~
302
303 If *subchilds* is True, commands also consider sub-levels. By default, only level one is checked. 
304
305 To get component Labels themselves, use: 
306 ~~~~~
307 Standard_Boolean subchilds = Standard_False; //default 
308 TDF_LabelSequence comps; 
309 Standard_Boolean isassembly = myAssembly->GetComponents 
310 (aLabel,comps[,subchilds]); 
311 ~~~~~
312 @subsubsection occt_xde_2_2_9 Instances and References for Components
313 To determine if a label is a simple shape, use: 
314 ~~~~~
315 if ( myAssembly->IsSimpleShape(aLabel) ) { .. yes .. } 
316 ~~~~~
317 To determine if a label is a located reference to another one, use: 
318 ~~~~~
319 if ( myAssembly->IsReference(aLabel) ) { .. yes .. } 
320 ~~~~~
321 If the label is a located reference, you can get the location, use: 
322 ~~~~~
323 TopLoc_Location loc = myAssembly->GetLocation (aLabel); 
324 ~~~~~
325 To get the label of a referenced original shape (also tests if it is a reference), use: 
326 ~~~~~
327 Standard_Boolean isref = myAssembly->GetReferredShape 
328 (aLabel, refLabel); 
329 ~~~~~
330
331 **Note** *isref* returns False if *aLabel* is not for a reference. 
332
333 @subsection occt_xde_2_3 Editing Shapes
334 In addition to the previously described *AddShape* and *SetShape*, several shape edits are possible. 
335
336 To remove a Shape, and all its sub-labels, use: 
337 ~~~~~
338 Standard_Boolean remsh = myAssembly->RemoveShape(aLabel); 
339 // remsh is returned True if done 
340 ~~~~~
341 This operation will fail if the shape is neither free nor top level.
342
343 To add a Component to the Assembly, from a new shape, use: 
344 ~~~~~
345 Standard_Boolean expand = Standard_False; //default 
346 TDF_Label aLabel = myAssembly->AddComponent (aShape [,expand]); 
347 ~~~~~
348 If *expand* is True and *aShape* is a Compound, *aShape* is broken down to produce sub-components, one for each of its sub-shapes. 
349
350 To add a component to the assembly, from a previously recorded shape (the new component is defined by the label of the reference shape, and its location), use: 
351 ~~~~~
352 TDF_Label refLabel ...; // the label of reference shape 
353 TopLoc_Location loc ...; // the desired location 
354 TDF_Label aLabel = myAssembly->AddComponent (refLabel, loc); 
355 ~~~~~
356 To remove a component from the assembly, use: 
357 ~~~~~
358 myAssembly->RemoveComponent (aLabel); 
359 ~~~~~
360
361 @subsection occt_xde_2_4 Management of Sub-Shapes
362 In addition to components of a (sub-)assembly, it is possible to have individual identification of some sub-shapes inside any shape. Therefore, you can attach specific attributes such as Colors. Some additional actions can be performed on sub-shapes that are neither top-level, nor components: 
363 To add a sub-shape to a given Label, use: 
364 ~~~~~
365 TDF_Label subLabel = myAssembly->AddSubShape (aLabel, subShape); 
366 ~~~~~
367
368 To find the Label attached to a given sub-shape, use: 
369 ~~~~~
370 TDF_Label subLabel; // new label to be computed 
371 if ( myAssembly-> FindSubShape (aLabel, subShape, subLabel)) { .. yes .. } 
372 ~~~~~
373 If the sub-shape is found (yes), *subLabel* is filled by the correct value. 
374
375 To find the top-level simple shape (not a compound whether free or not), which contains a given sub-shape, use: 
376 ~~~~~
377 TDF_Label mainLabel = myAssembly->FindMainShape(subShape); 
378 ~~~~~
379 **Note** that there should be only one shape for a valid model. In any case, the search stops on the first one found. 
380
381 To get the sub-shapes of a shape, which are recorded under a label, use: 
382 ~~~~~
383 TDF_LabelSequence subs; 
384 Standard_Boolean hassubs = myAssembly->GetSubShapes (aLabel,subs); 
385 ~~~~~
386 @subsection occt_xde_2_5 Properties
387 Some properties can be attached directly to shapes. These properties are: 
388   * Name (standard definition from OCAF)
389   * Centroid (for validation of transfer)
390   * Volume (for validation of transfer)
391   * Area (for validation of transfer)
392 Some other properties can also be attached, and are also managed by distinct tools for Colors and Layers. Colors and Layers are managed as an alternative way of organizing data (by providing a way of identifying groups of shapes). 
393 Colors are put into a table of colors while shapes refer to this table. There are two ways of attaching a color to a shape: 
394   * By attaching an item from the table.
395   * Adding the color directly.
396 When the color is added directly, a search is performed in the table of contents to determine if it contains the requested color. Once this search and initialize operation is done, the first way of attaching a color to a shape is used. 
397 @subsubsection occt_xde_2_5_1 Name
398 Name is implemented and used as a *TDataStd_Name*, which can be attached to any label. Before proceeding, consider that: 
399   * In IGES, every entity can have a name with an optional numeric part called a Subscript Label. For example, *MYCURVE* is a name, and *MYCURVE(60)* is a name with a Subscript Label.
400   * In STEP, there are two levels: Part Names and Entity Names: 
401                 * Part Names are attached to ;main shapes; such as parts and assemblies. These Part Names are specifically supported by XDE. 
402                 * Entity Names can be attached to every Geometric Entity. This option is rarely used, as it tends to overload the exploitation of the data structure. Only some specific cases justify using this option: for example, when the sending system can really ensure the stability of an entity name after each STEP writing. If such stability is ensured, you can use this option to send an Identifier for external applications using a database. 
403 **Note** that both IGES or STEP files handle names as pure ASCII strings.
404  
405 These considerations are not specific to XDE. What is specific to data exchange is the way names are attached to entities. 
406
407 To get the name attached to a label (as a reminder using OCAF), use: 
408 ~~~~~
409 Handle(TDataStd_Name) N; 
410 if ( !aLabel.FindAttribute(TDataStd_Name::GetID(),N)) { 
411   // no name is attached 
412
413 TCollection_ExtendedString name = N->Get(); 
414 ~~~~~
415
416 Don't forget to consider Extended String as ASCII, for the exchange file. 
417
418 To set a name to a label (as a reminder using OCAF), use: 
419 ~~~~~
420 TCollection_ExtendedString aName ...; 
421 // contains the desired name for this Label (ASCII) 
422 TDataStd_Name::Set (aLabel, aName); 
423 ~~~~~
424
425 @subsubsection occt_xde_2_5_2 Centroid
426 A Centroid is defined by a Point to fix its position. It is handled as a property, item of the class *XCAFDoc_Centroid*, sub-class of *TDF_Attribute*. However, global methods give access to the position itself. 
427
428 This notion has been introduced in STEP, together with that of Volume, and Area, as defining the Validation Properties: this feature allows exchanging the geometries and some basic attached values, in order to perform a synthetic checking on how they are maintained after reading and converting the exchange file. This exchange depends on reliable exchanges of Geometry and Topology. Otherwise, these values can be considered irrelevant. 
429
430 A centroid can be determined at any level of an assembly, thereby allowing a check of both individual simple shapes and their combinations including locations. 
431
432 To get a Centroid attached to a Shape, use: 
433 ~~~~~
434 gp_Pnt pos; 
435 Handle(XCAFDoc_Centroid) C; 
436 aLabel.FindAttribute ( XCAFDoc_Centroid::GetID(), C ); 
437 if ( !C.IsNull() ) pos = C->Get(); 
438 ~~~~~
439
440 To set a Centroid to a Shape, use: 
441 ~~~~~
442 gp_Pnt pos (X,Y,Z); 
443 // the position previously computed for the centroid 
444 XCAFDoc_Centroid::Set ( aLabel, pos ); 
445 ~~~~~
446
447 @subsubsection occt_xde_2_5_3 Area
448 An Area is defined by a Real, it corresponds to the computed Area of a Shape, provided that it contains surfaces. It is handled as a property, item of the class *XCAFDoc_Area*, sub-class of *TDF_Attribute*. 
449 This notion has been introduced in STEP but it is usually disregarded for a Solid, as Volume is used instead. In addition, it is attached to simple shapes, not to assemblies. 
450
451 To get an area attached to a Shape, use: 
452 ~~~~~
453 Standard_Real area; 
454 Handle(XCAFDoc_Area) A; 
455 L.FindAttribute ( XCAFDoc_Area::GetID(), A ); 
456 if ( !A.IsNull() ) area = A->Get(); 
457
458 To set an area value to a Shape, use: 
459 Standard_Real area ...; 
460 // value previously computed for the area 
461 XCAFDoc_Area::Set ( aLabel, area ); 
462 ~~~~~
463 @subsubsection occt_xde_2_5_4 Volume
464 A Volume is defined by a Real and corresponds to the computed volume of a Shape, provided that it contains solids. It is handled as a property, an item of the class *XCAFDoc_Volume*, sub-class of *TDF_Attribute*. 
465 This notion has been introduced in STEP. It may be attached to simple shapes or their assemblies for computing cumulated volumes and centers of gravity. 
466
467 To get a Volume attached to a Shape, use: 
468 ~~~~~
469 Standard_Real volume; 
470 Handle(XCAFDoc_Volume) V; 
471 L.FindAttribute ( XCAFDoc_Volume::GetID(), V ); 
472 if ( !V.IsNull() ) volume = V->Get(); 
473 ~~~~~
474
475 To set a volume value to a Shape, use: 
476 ~~~~~
477 Standard_Real volume ...; 
478 // value previously computed for the volume 
479 XCAFDoc_Volume::Set ( aLabel, volume ); 
480 ~~~~~
481 @subsection occt_xde_2_6 Colors
482 In an XDE document, colors are managed by the class *XCAFDoc_ColorTool*. This is done with the same principles as for ShapeTool with Shapes, and with the same capability of having a tool on the Main Label, or on any sub-label. The Property itself is defined as an *XCAFDoc_Color*, sub-class of *TDF_Attribute*.
483  
484 Colors are stored in a child of the starting document label: it is the second level (0.1.2), while Shapes are at the first level. Each color then corresponds to a dedicated label, the property itself is a Quantity_Color, which has a name and value for Red, Green, Blue. A Color may be attached to Surfaces (flat colors) or to Curves (wireframe colors), or to both. A Color may be attached to a sub-shape. In such a case, the sub-shape (and its own sub-shapes) takes its own Color as a priority. 
485
486 Colors and Shapes are related to by Tree Nodes. 
487
488 These definitions are common to various exchange formats, at least for STEP and IGES. 
489
490 @subsubsection occt_xde_2_6_1 Initialization
491 To query, edit, or initialize a Document to handle Colors of XCAF, use: 
492 ~~~~~
493 Handle(XCAFDoc_ColorTool) myColors = 
494 XCAFDoc_DocumentTool::ColorTool(Doc->Main ()); 
495 ~~~~~
496 This call can be used at any time. The first time it is used, a relevant structure is added to the document. This definition is used for all the following color calls and will not be repeated for these. 
497
498 @subsubsection occt_xde_2_6_2 Adding a Color
499 There are two ways to add a color. You can: 
500   * add a new Color defined as *Quantity_Color* and then directly set it to a Shape (anonymous Color)
501   * define a new Property Color, add it to the list of Colors, and then set it to various shapes.
502 When the Color is added by its value *Quantity_Color*, it is added only if it has not yet been recorded (same RGB values) in the Document. 
503
504 To set a Color to a Shape using a label, use:
505 ~~~~~
506 Quantity_Color Col (red,green,blue); 
507 XCAFDoc_ColorType ctype ..; 
508 // can take one of these values : 
509 // XCAFDoc_ColorGen : all types of geometries 
510 // XCAFDoc_ColorSurf : surfaces only 
511 // XCAFDoc_ColorCurv : curves only 
512 myColors->SetColor ( aLabel, Col, ctype ); 
513 ~~~~~
514 Alternately, the Shape can be designated directly, without using its label, use: 
515 ~~~~~
516 myColors->SetColor ( aShape, Col, ctype ); 
517 // Creating and Adding a Color, explicitly 
518 Quantity_Color Col (red,green,blue); 
519 TDF_Label ColLabel = myColors->AddColor ( Col ); 
520 ~~~~~
521 **Note** that this Color can then be named, allowing later retrieval by its Name instead of its Value. 
522
523 To set a Color, identified by its Label and already recorded, to a Shape, use: 
524 ~~~~~
525 XCAFDoc_ColorType ctype ..; // see above
526 if ( myColors->SetColors ( aLabel, ColLabel, ctype) ) {.. it is done .. }
527 ~~~~~
528 In this example, *aLabel* can be replaced by *aShape* directly. 
529
530 @subsubsection occt_xde_2_6_3 Queries on Colors
531 Various queries can be performed on colors. However, only specific queries are included in this section, not general queries using names. 
532
533 To determine if a Color is attached to a Shape, for a given color type (ctype), use: 
534 ~~~~~
535 if ( myColors->IsSet (aLabel , ctype)) { 
536   // yes, there is one .. 
537
538 ~~~~~
539 In this example, *aLabel* can be replaced by *aShape* directly. 
540
541 To get the Color attached to a Shape (for any color type), use: 
542 ~~~~~
543 Quantity_Color col; 
544 // will receive the recorded value (if there is some)
545 if ( !myColors->GetColor(aLabel, col) ) { 
546 // sorry, no color .. 
547 }
548 ~~~~~
549
550 Color name can also be queried from *col.StringName* or *col.Name*. 
551 In this example, *aLabel* can be replaced by *aShape* directly. 
552
553 To get the Color attached to a Shape, with a specific color type, use: 
554 ~~~~~
555 XCAFDoc_ColorType ctype ..; 
556 Quantity_Color col; 
557 // will receive the recorded value (if there is some) 
558 if ( !myColors->GetColor(aLabel, ctype, col) ) { 
559 // sorry, no color .. 
560
561 ~~~~~
562
563
564 To get all the Colors recorded in the Document, use: 
565
566 ~~~~~
567 Quantity_Color col; // to receive the values 
568 TDF_LabelSequence ColLabels; 
569 myColors->GetColors(ColLabels); 
570 Standard_Integer i, nbc = ColLabels.Length(); 
571 for (i = 1; i = nbc; i ++) { 
572   aLabel = Labels.Value(i); 
573   if ( !myColors->GetColor(aLabel, col) ) continue; 
574   // col receives the color n0 i .. 
575
576 ~~~~~
577
578 To find a Color from its Value, use: 
579 ~~~~~
580 Quantity_Color Col (red,green,blue); 
581 TDF_Label ColLabel = myColors-FindColor (Col); 
582 if ( !ColLabel.IsNull() ) { .. found .. } 
583 ~~~~~
584
585 @subsubsection occt_xde_2_6_4 Editing Colors
586 Besides adding colors, the following attribute edits can be made: 
587
588 To unset a Color on a Shape, use: 
589 ~~~~~
590 XCAFDoc_ColorType ctype ...; 
591 // desired type (XCAFDoc_ColorGen for all ) 
592 myColors->UnSetColor (aLabel,ctype); 
593 ~~~~~
594 To remove a Color and all the references to it (so that the related shapes will become colorless), use: 
595 ~~~~~
596 myColors->RemoveColor(ColLabel); 
597 ~~~~~
598 @subsection occt_xde_2_7 Layers
599 Layers are handled using the same principles as for Colors. Simply replace **Color** with **Layer** when dealing with Layers. Layers are supported by the class *XCAFDoc_LayerTool*. 
600 The class of the property is *XCAFDoc_Layer*, sub-class of *TDF_Attribute* while its definition is a *TCollection_ExtendedString*. Integers are generally used when dealing with Layers. The general cases are: 
601   * IGES has *LevelList* as a list of Layer Numbers (not often used)
602   * STEP identifies a Layer (not by a Number, but by a String), to be more general.
603   
604 @subsection occt_xde_2_8 Reading and Writing STEP or IGES
605 Note that saving and restoring the document itself are standard OCAF operations. As the various previously described definitions enter into this frame, they will not be explained any further. 
606 The same can be said for Viewing: presentations can be defined from Shapes and Colors. 
607
608 There are several important points to consider: 
609   * Previously defined Readers and Writers for dealing with Shapes only, whether Standard or Advanced, remain unchanged in their form and in their dependencies. In addition, functions other than mapping are also unchanged.
610   * XDE provides mapping with data other than Shapes. Names, Colors, Layers, Validation Properties (Centroid, Volume, Area), and Assembly Structure are hierarchic with rigid motion.
611   * XDE mapping is relevant for use within the Advanced level of Data Exchanges, rather than Standard ones, because a higher level of information is better suited to a higher quality of shapes. In addition, this allows to avoid the multiplicity of combinations between various options. Note that this choice is not one of architecture but of practical usage and packaging.
612   * Reader and Writer classes for XDE are generally used like those for Shapes. However, their use is adapted to manage a Document rather than a Shape.
613   
614 The packages to manage this are *IGESCAFControl* for IGES, and *STEPCAFControl* for STEP. 
615 @subsubsection occt_xde_2_8_1 Reading a STEP file
616 To read a STEP file by itself, use: 
617
618 ~~~~~
619 STEPCAFControl_Reader reader; 
620 IFSelect_ReturnStatus readstat = reader.ReadFile(filename); 
621 // The various ways of reading a file are available here too : 
622 // to read it by the reader, to take it from a WorkSession ... 
623 Handle(TDocStd_Document) doc... 
624 // the document referred to is already defined and 
625 // properly initialized. 
626 // Now, the transfer itself 
627 if ( !reader.Transfer ( doc ) ) { 
628   cout;Cannot read any relevant data from the STEP file;endl; 
629   // abandon .. 
630
631 // Here, the Document has been filled from a STEP file, 
632 // it is ready to use 
633 ~~~~~
634
635 In addition, the reader provides methods that are applicable to document transfers and for directly querying of the data produced. 
636 @subsubsection occt_xde_2_8_2 Writing a STEP file
637 To write a STEP file by itself, use: 
638
639 ~~~~~
640 STEPControl_StepModelType mode = 
641 STEPControl_AsIs; 
642 // Asis is the recommended value, others are available 
643 // Firstly, perform the conversion to STEP entities 
644 STEPCAFControl_Writer writer; 
645 //(the user can work with an already prepared WorkSession or create a //new one) 
646 Standard_Boolean scratch = Standard_False; 
647 STEPCAFControl_Writer writer ( WS, scratch ); 
648 // Translating document (conversion) to STEP 
649 if ( ! writer.Transfer ( Doc, mode ) ) { 
650   cout;The document cannot be translated or gives no result;endl; 
651   // abandon .. 
652
653 // Writing the File 
654 IFSelect_ReturnStatus stat = writer.Write(file-name); 
655 ~~~~~
656
657 @subsubsection occt_xde_2_8_3 Reading an IGES File
658 Use the same procedure as for a STEP file but with IGESCAFControl instead of STEPCAFControl. 
659 @subsubsection occt_xde_2_8_4 Writing an IGES File
660 Use the same procedure as for a STEP file but with IGESCAFControl instead of STEPCAFControl.
661  
662 @subsection occt_xde_2_9 Using an XDE Document
663 There are several ways of exploiting XDE data from an application, you can: 
664  1. Get the data relevant for the application by mapping XDE/Appli, then discard the XDE data once it has been used.
665  2. Create a reference from the Application Document to the XDE Document, to have its data available as external data.
666  3. Embed XDE data inside the Application Document (see the following section for details).
667  4. Directly exploit XDE data such as when using file checkers.
668 @subsubsection occt_xde_2_91 XDE Data inside an Application Document
669 To have XCAF data elsewhere than under label 0.1, you use the DocLabel of XDE. The method DocLabel from XCAFDoc_DocumentTool determines the relevant Label for XCAF. However, note that the default is 0.1. 
670
671 In addition, as XDE data is defined and managed in a modular way, you can consider exclusively Assembly Structure, only Colors, and so on. 
672
673 As XDE provides an extension of the data structure, for relevant data in standardized exchanges, note the following: 
674   * This data structure is fitted for data exchange, rather than for use by the final application.
675   * The provided definitions are general, for common use and therefore do not bring strongly specific semantics.
676   
677 As a result, if an application works on Assemblies, on Colors or Layers, on Validation Properties (as defined in STEP), it can rely on all or a part of the XDE definitions, and include them in its own data structure. 
678
679 In addition, if an application has a data structure far from these notions, it can get data (such as Colors and Names on Shapes) according to its needs, but without having to consider the whole.