0031939: Coding - correction of spelling errors in comments [part 3]
[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
8 This manual explains how to use the Extended Data Exchange (XDE). It provides basic documentation on setting up and using XDE.
9
10 The Extended Data Exchange (XDE) module allows extending the scope of exchange by translating  additional data attached to geometric BREP data, thereby improving the interoperability with external software. 
11
12 Data types such as colors, layers, assembly descriptions and validation properties (i.e. center of gravity, etc.) are supported. These data are stored together with shapes in an XCAF document. It is also possible to add a new types of data taking the existing tools as prototypes.
13
14 Finally, the XDE provides reader and writer tools for reading and writing the data supported by XCAF to and from IGES and STEP files. 
15
16 @figure{/user_guides/xde/images/646_xde_11_400.png,"Shape imported using XDE",240}
17
18 The XDE component requires @ref occt_user_guides__shape_healing "Shape Healing" toolkit for operation. 
19
20 @subsection occt_xde_1_1 Basic terms
21
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
27 @subsection occt_xde_1_2 XDE Organization
28
29 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. 
30
31 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. 
32
33 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. 
34
35 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. 
36 The Document used by XDE usually starts as a *TDocStd_Document*. 
37
38 @subsection occt_xde_1_3 Assemblies
39 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. 
40
41 For example, a mechanical assembly can be defined as follows: 
42 @figure{/user_guides/xde/images/xde_image003.png,"Assembly Description",240}
43
44
45 @figure{/user_guides/xde/images/xde_image004.png,"Assembly View",240}
46
47
48 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). 
49
50 *XCAFDoc_ShapeTool* is a tool that allows managing the Shape section of the XCAF document. This tool is implemented as an attribute and located at the root label of the shape section. 
51
52 @subsection occt_xde_1_4 Validation Properties
53 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. 
54
55 Advanced Data Exchange supports both reading and writing of validation properties, and provides a tool to check them. 
56
57 @figure{/user_guides/xde/images/xde_image005.png,"Validation Property Descriptions",240}
58
59 Check logs contain deviations of computed values from the values stored in a STEP file. A typical example appears as follows: 
60
61 | Label | Area defect   | Volume defect | dX    | dY    | DZ    | Name |
62 | :---- | :----- | :----- | :----- | :---- | :---- | :---- |
63 | 0:1:1:1 | 312.6 (0%) | -181.7 (0%) | 0.00 | 0.00 | 0.00       | "S1" |
64 | 0:1:1:2 |  -4.6 (0%) | -191.2 (0%)    | -0.00  | 0.00 | -0.00 | "MAINBODY" |
65 | 0:1:1:3 | -2.3 (0%) | -52.5 (0%)      | -0.00 | 0.00  | 0.00 | "MAIN_BODY_BACK" |
66 | 0:1:1:4 | -2.3 (0%) | -51.6 (0%) | 0.00 |     0.00 | -0.00 | "MAIN_BODY_FRONT" |
67 | 0:1:1:5 | 2.0 (0%) | 10.0 (0%) | -0.00 |      0.00 |  -0.00 | "HEAD" |
68 | 0:1:1:6 | 0.4 (0%) | 0.0 (0%) |       0.00    | -0.00 | -0.00 | "HEAD_FRONT" |
69 | 0:1:1:7 |  0.4 (0%) | 0.0 (0%) | 0.00 | -0.00 | -0.00 | "HEAD_BACK" |
70 | 0:1:1:8 | -320.6 (0%) | 10.9 (0%)     | -0.00 | 0.00 | 0.00 | "TAIL" |
71 | 0:1:1:9 | 0.0 (0%) | 0.0 (0%) | -0.00 | -0.00 | 0.00 | "TAIL_MIDDLE" |
72 | 0:1:1:10 | -186.2 (0%) |      4.8 (0%) |      -0.00 | 0.00 | -0.00 | "TAIL_TURBINE" |
73 | 0:1:1:11 | 0.3 (0%) | -0.0 (0%) |     -0.00 | -0.00 | 0.00 |  "FOOT" |
74 | 0:1:1:12      | 0.0 (0%) | -0.0 (0%) | 0.00 | -0.00 | -0.00 |"FOOT_FRONT" |
75 | 0:1:1:13 | 0.0 (0%) | 0.0 (0%) | -0.00 | 0.00 | 0.00 | "FOOT_BACK" |
76
77
78 In our example, it can be seen that no errors were detected for either area, volume or positioning data. 
79
80 @subsection occt_xde_1_5 Names
81
82 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. 
83
84 @figure{/user_guides/xde/images/614_xde_04_400.png,"Instance Names",360}
85
86 @subsection occt_xde_1_6 Colors and Layers
87 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*: 
88   * generic color <i>(XCAFDoc_ColorGen)</i>
89   * surface color <i>(XCAFDoc_ColorSurf)</i>
90   * curve color <i>(XCAFDoc_ColorCurv)</i>
91   
92  @figure{/user_guides/xde/images/xde_image006.png,"Colors and Layers",240}
93
94 @subsection occt_xde_1_7 Geometric Dimensions & Tolerances (GD\&T)
95
96 GD\&T are a type of Product and Manufacturing Information (PMI) that can be either computed automatically by a CAD system,
97 or entered manually by the user. For detailed information use <a href="https://www.cax-if.org/documents/rec_pracs_pmi_v40.pdf">CAx-IF Recommended Practices
98 for the Representation and Presentation of Product Manufacturing Information (PMI) (AP242)</a>
99
100 XDE can read and write GD\&T data of the following types:
101 * dimensions, such as distance, length, radius and so on;
102 * geometric tolerances;
103 * datums, i.e theoretically exact geometric references, such as point, line or plane, to which toleranced features are related.
104
105 XDE supports two presentations of GD\&T data:
106 * semantic presentation, i.e. data is stored in a machine-consumable way and includes all information required to understand the
107   specification without the aid of any presentation elements;
108 * tessellated presentation, i.e. data is displayed in a human-readable way.
109
110 @subsection occt_xde_1_8 Clipping planes
111
112 XDE supports reading from STEP and storing named planes used for clipping. 
113 Currently, XDE supports saving of clipping planes in XBF format only.
114
115 XDE provides capabilities for adding, editing and removing clipping planes.
116
117 @subsection occt_xde_1_9 Saved views
118
119 XDE supports reading from STEP views. Views allow saving information about camera parameters (position, direction, zoom factor, etc.)
120 and visible shapes, PMIs, used clipping planes and notes. Currently, XDE supports saving of clipping planes in XBF format only.
121
122 XDE provides the following view management capabilities:
123   * add/remove views;
124   * set view camera parameters;
125   * set visible shapes, PMIs, used clipping planes and notes.
126
127 @subsection occt_xde_1_10 Custom notes
128  
129 Custom notes is a kind of application-specific data attached to assembly items, their attributes and sub-shapes. Basically, there are simple textual comments, binary data and other application-specific data. Each note is provided with a timestamp and the user who created it.
130
131 Notes API provides the following functionality:
132   * Returns the total number of notes and annotated items;
133   * Returns labels for all notes and annotated items;
134   * Creates notes:
135     - Comment note from a text string;
136     - Binary data note from a file or byte array;
137   * Checks if an assembly item is annotated;
138   * Finds a label for the annotated item;
139   * Returns all note labels for the annotated item;
140   * Adds a note to item(s):
141     - Assembly item;
142     - Assembly item attribute;
143     - Assembly item subshape index;
144   * Removes note(s) from an annotated assembly item; orphan note(s) might be deleted optionally (items without linked notes will be deleted automatically);
145   * Deletes note(s) and removes them from annotated items;
146   * Gets / deletes orphan notes.
147
148 @section occt_xde_2 Working with XDE
149
150 @subsection occt_xde_2_1 Getting started
151
152 As explained in the last chapter, XDE uses *TDocStd_Documents* as a starting point. The general purpose of XDE is: 
153   * Checking if an existing document is fit for XDE;
154   * Getting an application and initialized document;
155   * Initializing a document to fit it for XDE;
156   * Adding, setting and finding data;
157   * Querying and managing shapes;
158   * Attaching properties to shapes.
159   
160 The Document used by XDE usually starts as a *TDocStd_Document*. 
161
162 @subsubsection occt_xde_2_1_1 Environment variables
163 To use XDE you have to set the environment variables properly. Make sure that two important environment variables are set as follows: 
164   * *CSF_PluginDefaults* points to sources of  <i>\%CASROOT%/src/XCAFResources ($CASROOT/src/XCAFResources)</i>.
165   * *CSF_XCAFDefaults* points to sources of <i>\%CASROOT%/src/XCAFResources ($CASROOT/src/XCAFResources)</i>.
166
167 @subsubsection occt_xde_2_1_2 General Check
168 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. 
169
170 To find out if an existing *TDocStd_Document* is suitable for XDE, use: 
171 ~~~~~
172 Handle(TDocStd_Document) doc... 
173 if ( XCAFDoc_DocumentTool::IsXCAFDocument (doc) ) { .. yes .. } 
174 ~~~~~
175 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. 
176
177 @subsubsection occt_xde_2_1_3 Get an Application or an Initialized Document
178 If you want to retrieve an existing application or an existing document (known to be correctly structured for XDE), use: 
179 ~~~~~
180 Handle(TDocStd_Document) aDoc; 
181 Handle(XCAFApp_Application) anApp = XCAFApp_Application::GetApplication(); 
182 anApp->NewDocument(;MDTV-XCAF;,aDoc); 
183 ~~~~~
184
185 @subsection occt_xde_2_2 Shapes and Assemblies
186
187 @subsubsection occt_xde_2_2_1 Initialize an XDE Document (Shapes)
188 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: 
189 ~~~~~
190 Handle(TDocStd_Document) doc... 
191 Handle (XCAFDoc_ShapeTool) myAssembly = 
192 XCAFDoc_DocumentTool::ShapeTool (Doc->Main()); 
193 TDF_Label aLabel = myAssembly->NewShape() 
194 ~~~~~
195 **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*.
196
197 @subsubsection occt_xde_2_2_2 Get a Node considered as an Assembly
198 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: 
199 ~~~~~
200 Handle(TDocStd_Document) doc... 
201 Handle(XCAFDoc_ShapeTool) myAssembly = XCAFDoc_DocumentTool::ShapeTool (aLabel); 
202 ~~~~~
203 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)*. 
204
205 You can then query or edit this Assembly node, the Main Item or another one (*myAssembly* in our examples). 
206
207 **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.
208
209 @subsubsection occt_xde_2_2_3 Updating the Assemblies after Filling or Editing
210 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). 
211
212 To update the representations, use: 
213 ~~~~~
214 myAssembly->UpdateAssemblies(); 
215 ~~~~~
216 This call performs a top-down update of the Assembly compounds stored in the document.
217
218 **Note** that you have to run this method manually to actualize your Assemblies after any low-level modifications on shapes.
219
220 @subsubsection occt_xde_2_2_4 Adding or Setting Top Level Shapes
221
222 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: 
223   * shapes with upper level references
224   * free shapes (that correspond to roots) without any upper reference
225
226 **Note** that several top-level shapes can be added to the same component.
227  
228 A shape to be added can be defined as a compound (if required), with the following interpretations: 
229   * 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. 
230   * If the Shape is not a compound, it is taken as a whole, without breaking it down. 
231   
232 To break down a Compound in the assembly structure, use: 
233 ~~~~~
234 Standard_Boolean makeAssembly; 
235 // True to interpret a Compound as an Assembly, 
236 // False to take it as a whole 
237 aLabel = myAssembly->AddShape(aShape, makeAssembly); 
238 ~~~~~
239 Each node of the assembly therefore refers to its sub-shapes. 
240
241 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. 
242
243 @subsubsection occt_xde_2_2_5 Setting a given Shape at a given Label
244 A top-level shape can be changed. In this example, no interpretation of compound is performed: 
245 ~~~~~
246 Standard_CString LabelString ...; 
247 // identifies the Label (form ;0:i:j...;) 
248 TDF_Label aLabel...; 
249 // A label must be present 
250 myAssembly->SetShape(aLabel, aShape); 
251 ~~~~~
252
253 @subsubsection occt_xde_2_2_6 Getting a Shape from a Label
254 To get a shape from its Label from the top-level, use: 
255 ~~~~~
256 TDF_Label aLabel...
257 // A label must be present
258 if (aLabel.IsNull()) { 
259   // no such label : abandon
260 }
261 TopoDS_Shape aShape;
262 aShape = myAssembly->GetShape(aLabel);
263 if (aShape.IsNull()) {
264   // this label is not for a Shape
265 }
266 ~~~~~
267 **Note** that if the label corresponds to an assembly, the result is a compound. 
268
269 @subsubsection occt_xde_2_2_7 Getting a Label from a Shape
270 To get a Label, which is attached to a Shape from the top-level, use: 
271 ~~~~~
272 Standard_Boolean findInstance = Standard_False; 
273 // (this is default value)
274 aLabel = myAssembly->FindShape(aShape [,findInstance]);
275 if (aLabel.IsNull()) { 
276   // no label found for this shape
277 }
278 ~~~~~
279 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. 
280
281 @subsubsection occt_xde_2_2_8 Other Queries on a Label
282
283 Various other queries can be made from a Label within the Main Item of XDE: 
284 #### Main Shapes
285
286 To determine if a Shape is recorded (or not), use: 
287 ~~~~~
288 if ( myAssembly->IsShape(aLabel) ) { .. yes .. } 
289 ~~~~~
290
291 To determine if the shape is top-level, i.e. was added by the *AddShape* method, use: 
292 ~~~~~
293 if ( myAssembly->IsTopLevel(aLabel) ) { .. yes .. } 
294 ~~~~~
295
296 To get a list of top-level shapes added by the *AddShape* method, use: 
297 ~~~~~
298 TDF_LabelSequence frshapes; 
299 myAssembly->GetShapes(frshapes); 
300 ~~~~~
301
302 To get all free shapes at once if the list above has only one item, use: 
303 ~~~~~
304 TopoDS_Shape result = myAssembly->GetShape(frshapes.Value(1)); 
305 ~~~~~
306
307 If there is more than one item, you must create and fill a compound, use: 
308
309 ~~~~~
310 TopoDS_Compound C; 
311 BRep_Builder B; 
312 B.MakeCompound(C); 
313 for(Standard_Integer i=1; i=frshapes.Length(); i++) { 
314   TopoDS_Shape S = myAssembly->GetShape(frshapes.Value(i)); 
315   B.Add(C,S); 
316
317 ~~~~~
318
319 In our example, the result is the compound C. 
320 To determine if a shape is a free shape (no reference or super-assembly), use: 
321
322 ~~~~~
323 if ( myAssembly->IsFree(aLabel) ) { .. yes .. } 
324 ~~~~~
325
326 To get a list of Free Shapes (roots), use: 
327
328 ~~~~~
329 TDF_LabelSequence frshapes; 
330 myAssembly->GetFreeShapes(frshapes); 
331 ~~~~~
332
333 To get the shapes, which use a given shape as a component, use: 
334 ~~~~~
335 TDF_LabelSequence users; 
336 Standard_Integer nbusers = myAssembly->GetUsers(aLabel,users); 
337 ~~~~~
338 The count of users is contained with *nbusers*. It contains 0 if there are no users. 
339
340 #### Assembly and Components
341 To determine if a label is attached to the main part or to a sub-part (component), use: 
342 ~~~~~
343 if (myAssembly->IsComponent(aLabel)) { .. yes .. } 
344 ~~~~~
345 To determine whether a label is a node of a (sub-) assembly or a simple shape, use: 
346 ~~~~~
347 if ( myAssembly->IsAssembly(aLabel) ) { .. yes .. } 
348 ~~~~~
349
350 If the label is a node of a (sub-) assembly, you can get the count of components, use: 
351 ~~~~~
352 Standard_Boolean subchilds = Standard_False; //default 
353 Standard_Integer nbc = myAssembly->NbComponents (aLabel [,subchilds]); 
354 ~~~~~
355
356 If *subchilds* is True, commands also consider sub-levels. By default, only level one is checked. 
357
358 To get component Labels themselves, use: 
359 ~~~~~
360 Standard_Boolean subchilds = Standard_False; //default 
361 TDF_LabelSequence comps; 
362 Standard_Boolean isassembly = myAssembly->GetComponents 
363 (aLabel,comps[,subchilds]); 
364 ~~~~~
365 @subsubsection occt_xde_2_2_9 Instances and References for Components
366 To determine if a label is a simple shape, use: 
367 ~~~~~
368 if ( myAssembly->IsSimpleShape(aLabel) ) { .. yes .. } 
369 ~~~~~
370 To determine if a label is a located reference to another one, use: 
371 ~~~~~
372 if ( myAssembly->IsReference(aLabel) ) { .. yes .. } 
373 ~~~~~
374 If the label is a located reference, you can get the location, use: 
375 ~~~~~
376 TopLoc_Location loc = myAssembly->GetLocation (aLabel); 
377 ~~~~~
378 To get the label of a referenced original shape (also tests if it is a reference), use: 
379 ~~~~~
380 Standard_Boolean isref = myAssembly->GetReferredShape 
381 (aLabel, refLabel); 
382 ~~~~~
383
384 **Note** *isref* returns False if *aLabel* is not for a reference. 
385
386 @subsection occt_xde_2_3 Editing Shapes
387 In addition to the previously described *AddShape* and *SetShape*, several shape edits are possible. 
388
389 To remove a Shape, and all its sub-labels, use: 
390 ~~~~~
391 Standard_Boolean remsh = myAssembly->RemoveShape(aLabel); 
392 // remsh is returned True if done 
393 ~~~~~
394 This operation will fail if the shape is neither free nor top level.
395
396 To add a Component to the Assembly, from a new shape, use: 
397 ~~~~~
398 Standard_Boolean expand = Standard_False; //default 
399 TDF_Label aLabel = myAssembly->AddComponent (aShape [,expand]); 
400 ~~~~~
401 If *expand* is True and *aShape* is a Compound, *aShape* is broken down to produce sub-components, one for each of its sub-shapes. 
402
403 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: 
404 ~~~~~
405 TDF_Label refLabel ...; // the label of reference shape 
406 TopLoc_Location loc ...; // the desired location 
407 TDF_Label aLabel = myAssembly->AddComponent (refLabel, loc); 
408 ~~~~~
409 To remove a component from the assembly, use: 
410 ~~~~~
411 myAssembly->RemoveComponent (aLabel); 
412 ~~~~~
413
414 @subsection occt_xde_2_4 Management of Sub-Shapes
415 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: 
416 To add a sub-shape to a given Label, use: 
417 ~~~~~
418 TDF_Label subLabel = myAssembly->AddSubShape (aLabel, subShape); 
419 ~~~~~
420
421 To find the Label attached to a given sub-shape, use: 
422 ~~~~~
423 TDF_Label subLabel; // new label to be computed 
424 if ( myAssembly-> FindSubShape (aLabel, subShape, subLabel)) { .. yes .. } 
425 ~~~~~
426 If the sub-shape is found (yes), *subLabel* is filled by the correct value. 
427
428 To find the top-level simple shape (not a compound whether free or not), which contains a given sub-shape, use: 
429 ~~~~~
430 TDF_Label mainLabel = myAssembly->FindMainShape(subShape); 
431 ~~~~~
432 **Note** that there should be only one shape for a valid model. In any case, the search stops on the first one found. 
433
434 To get the sub-shapes of a shape, which are recorded under a label, use: 
435 ~~~~~
436 TDF_LabelSequence subs; 
437 Standard_Boolean hassubs = myAssembly->GetSubShapes (aLabel,subs); 
438 ~~~~~
439 @subsection occt_xde_2_5 Properties
440 Some properties can be attached directly to shapes. These properties are: 
441   * Name (standard definition from OCAF)
442   * Centroid (for validation of transfer)
443   * Volume (for validation of transfer)
444   * Area (for validation of transfer)
445 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). 
446 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: 
447   * By attaching an item from the table.
448   * Adding the color directly.
449 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. 
450 @subsubsection occt_xde_2_5_1 Name
451 Name is implemented and used as a *TDataStd_Name*, which can be attached to any label. Before proceeding, consider that: 
452   * 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.
453   * In STEP, there are two levels: Part Names and Entity Names: 
454                 * Part Names are attached to ;main shapes; such as parts and assemblies. These Part Names are specifically supported by XDE. 
455                 * 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. 
456 **Note** that both IGES or STEP files handle names as pure ASCII strings.
457  
458 These considerations are not specific to XDE. What is specific to data exchange is the way names are attached to entities. 
459
460 To get the name attached to a label (as a reminder using OCAF), use: 
461 ~~~~~
462 Handle(TDataStd_Name) N; 
463 if ( !aLabel.FindAttribute(TDataStd_Name::GetID(),N)) { 
464   // no name is attached 
465
466 TCollection_ExtendedString name = N->Get(); 
467 ~~~~~
468
469 Don't forget to consider Extended String as ASCII, for the exchange file. 
470
471 To set a name to a label (as a reminder using OCAF), use: 
472 ~~~~~
473 TCollection_ExtendedString aName ...; 
474 // contains the desired name for this Label (ASCII) 
475 TDataStd_Name::Set (aLabel, aName); 
476 ~~~~~
477
478 @subsubsection occt_xde_2_5_2 Centroid
479 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. 
480
481 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. 
482
483 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. 
484
485 To get a Centroid attached to a Shape, use: 
486 ~~~~~
487 gp_Pnt pos; 
488 Handle(XCAFDoc_Centroid) C; 
489 aLabel.FindAttribute ( XCAFDoc_Centroid::GetID(), C ); 
490 if ( !C.IsNull() ) pos = C->Get(); 
491 ~~~~~
492
493 To set a Centroid to a Shape, use: 
494 ~~~~~
495 gp_Pnt pos (X,Y,Z); 
496 // the position previously computed for the centroid 
497 XCAFDoc_Centroid::Set ( aLabel, pos ); 
498 ~~~~~
499
500 @subsubsection occt_xde_2_5_3 Area
501 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*. 
502 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. 
503
504 To get an area attached to a Shape, use: 
505 ~~~~~
506 Standard_Real area; 
507 Handle(XCAFDoc_Area) A; 
508 L.FindAttribute ( XCAFDoc_Area::GetID(), A ); 
509 if ( !A.IsNull() ) area = A->Get(); 
510
511 To set an area value to a Shape, use: 
512 Standard_Real area ...; 
513 // value previously computed for the area 
514 XCAFDoc_Area::Set ( aLabel, area ); 
515 ~~~~~
516 @subsubsection occt_xde_2_5_4 Volume
517 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*. 
518 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. 
519
520 To get a Volume attached to a Shape, use: 
521 ~~~~~
522 Standard_Real volume; 
523 Handle(XCAFDoc_Volume) V; 
524 L.FindAttribute ( XCAFDoc_Volume::GetID(), V ); 
525 if ( !V.IsNull() ) volume = V->Get(); 
526 ~~~~~
527
528 To set a volume value to a Shape, use: 
529 ~~~~~
530 Standard_Real volume ...; 
531 // value previously computed for the volume 
532 XCAFDoc_Volume::Set ( aLabel, volume ); 
533 ~~~~~
534 @subsection occt_xde_2_6 Colors and Layers
535
536 XDE can read and write colors and layers assigned to shapes or their subparts (down to level of faces and edges) to and from both IGES and STEP formats. 
537
538 @figure{/user_guides/xde/images/239_xde_12_400.png,"Motor Head",240}
539
540 In an XDE document, colors are managed by the class *XCAFDoc_ColorTool*. It works basing on the same principles as ShapeTool works with Shapes. This tool can be provided on the Main Label or on any sub-label. The Property itself is defined as an *XCAFDoc_Color*, sub-class of *TDF_Attribute*.
541  
542 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.
543
544 Layers are handled using the same principles as Colors. In all operations described below you can simply replace **Color** with **Layer** when dealing with Layers. Layers are supported by the class *XCAFDoc_LayerTool*. 
545
546 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: 
547   * IGES has *LevelList* as a list of Layer Numbers (not often used)
548   * STEP identifies a Layer (not by a Number, but by a String), to be more general.
549
550 Colors and Shapes are related to by Tree Nodes. 
551
552 These definitions are common to various exchange formats, at least for STEP and IGES. 
553
554 @subsubsection occt_xde_2_6_1 Initialization
555 To query, edit, or initialize a Document to handle Colors of XCAF, use: 
556 ~~~~~
557 Handle(XCAFDoc_ColorTool) myColors = 
558 XCAFDoc_DocumentTool::ColorTool(Doc->Main ()); 
559 ~~~~~
560 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. 
561
562 @subsubsection occt_xde_2_6_2 Adding a Color
563 There are two ways to add a color. You can: 
564   * add a new Color defined as *Quantity_Color* and then directly set it to a Shape (anonymous Color)
565   * define a new Property Color, add it to the list of Colors, and then set it to various shapes.
566 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. 
567
568 To set a Color to a Shape using a label, use:
569 ~~~~~
570 Quantity_Color Col (red,green,blue); 
571 XCAFDoc_ColorType ctype ..; 
572 // can take one of these values : 
573 // XCAFDoc_ColorGen : all types of geometries 
574 // XCAFDoc_ColorSurf : surfaces only 
575 // XCAFDoc_ColorCurv : curves only 
576 myColors->SetColor ( aLabel, Col, ctype ); 
577 ~~~~~
578 Alternately, the Shape can be designated directly, without using its label, use: 
579 ~~~~~
580 myColors->SetColor ( aShape, Col, ctype ); 
581 // Creating and Adding a Color, explicitly 
582 Quantity_Color Col (red,green,blue); 
583 TDF_Label ColLabel = myColors->AddColor ( Col ); 
584 ~~~~~
585 **Note** that this Color can then be named, allowing later retrieval by its Name instead of its Value. 
586
587 To set a Color, identified by its Label and already recorded, to a Shape, use: 
588 ~~~~~
589 XCAFDoc_ColorType ctype ..; // see above
590 if ( myColors->SetColors ( aLabel, ColLabel, ctype) ) {.. it is done .. }
591 ~~~~~
592 In this example, *aLabel* can be replaced by *aShape* directly. 
593
594 @subsubsection occt_xde_2_6_3 Queries on Colors
595 Various queries can be performed on colors. However, only specific queries are included in this section, not general queries using names. 
596
597 To determine if a Color is attached to a Shape, for a given color type (ctype), use: 
598 ~~~~~
599 if ( myColors->IsSet (aLabel , ctype)) { 
600   // yes, there is one .. 
601
602 ~~~~~
603 In this example, *aLabel* can be replaced by *aShape* directly. 
604
605 To get the Color attached to a Shape (for any color type), use: 
606 ~~~~~
607 Quantity_Color col; 
608 // will receive the recorded value (if there is some)
609 if ( !myColors->GetColor(aLabel, col) ) { 
610 // sorry, no color .. 
611 }
612 ~~~~~
613
614 Color name can also be queried from *col.StringName* or *col.Name*. 
615 In this example, *aLabel* can be replaced by *aShape* directly. 
616
617 To get the Color attached to a Shape, with a specific color type, use: 
618 ~~~~~
619 XCAFDoc_ColorType ctype ..; 
620 Quantity_Color col; 
621 // will receive the recorded value (if there is some) 
622 if ( !myColors->GetColor(aLabel, ctype, col) ) { 
623 // sorry, no color .. 
624
625 ~~~~~
626
627
628 To get all the Colors recorded in the Document, use: 
629
630 ~~~~~
631 Quantity_Color col; // to receive the values 
632 TDF_LabelSequence ColLabels; 
633 myColors->GetColors(ColLabels); 
634 Standard_Integer i, nbc = ColLabels.Length(); 
635 for (i = 1; i = nbc; i ++) { 
636   aLabel = Labels.Value(i); 
637   if ( !myColors->GetColor(aLabel, col) ) continue; 
638   // col receives the color n0 i .. 
639
640 ~~~~~
641
642 To find a Color from its Value, use: 
643 ~~~~~
644 Quantity_Color Col (red,green,blue); 
645 TDF_Label ColLabel = myColors-FindColor (Col); 
646 if ( !ColLabel.IsNull() ) { .. found .. } 
647 ~~~~~
648
649 @subsubsection occt_xde_2_6_4 Editing Colors
650 Besides adding colors, the following attribute edits can be made: 
651
652 To unset a Color on a Shape, use: 
653 ~~~~~
654 XCAFDoc_ColorType ctype ...; 
655 // desired type (XCAFDoc_ColorGen for all ) 
656 myColors->UnSetColor (aLabel,ctype); 
657 ~~~~~
658 To remove a Color and all the references to it (so that the related shapes will become colorless), use: 
659 ~~~~~
660 myColors->RemoveColor(ColLabel); 
661 ~~~~~
662
663 @subsection occt_xde_2_7 Geometric Dimensions & Tolerances (GD\&T)
664
665 XDE can read and write GD\&T assigned to shapes or their subparts (down to the level of faces and edges) to and from STEP formats. 
666
667 In an XDE document, GD\&T are managed by the class *XCAFDoc_DimTolTool*. It works basing on the same principles as ShapeTool works with Shapes. This tool can be provided on the Main Label or on any sub-label. The GD\&T entities themselves are defined as the following sub-classes of *TDF_Attribute*:
668   * *XCAFDoc_Dimension* - for dimensions;
669   * *XCAFDoc_GeomTolerance* - for geometric tolerances;
670   * *XCAFDoc_Datum* - for geometric tolerance Datums.
671 A GD\&T type is identified by the attributes listed above, i.e. *XCAFDoc_DimTolTool* methods working with particular entity types check 
672 for presence of the corresponding attributes in passed labels. One can use methods of *XCAFDoc_DimTolTool* beginning with 'Is' for this purpose.
673  
674 GD\&T entities are stored in a child of the starting document label 0.1.4. 
675 Each GD\&T entity then corresponds to the dedicated label, the property itself is one of access classes:
676   * *XCAFDimTolObject_DimensionObject* - for dimensions;
677   * *XCAFDimTolObject_GeomToleranceObject* - for geometric tolerances;
678   * *XCAFDimTolObject_DatumObject* - for geometric tolerance Datums.
679
680 GD\&Ts and Shapes are related by Graph Nodes. 
681
682 These definitions are common to various exchange formats, at least for STEP. 
683
684 @subsubsection occt_xde_2_7_1 Initialization
685 To query, edit, or initialize a Document to handle GD\&Ts of XCAF, use: 
686 ~~~~~
687 Handle(XCAFDoc_DimTolTool) myDimTolTool = 
688 XCAFDoc_DocumentTool::DimTolTool(Doc->Main()); 
689 ~~~~~
690 This call can be used at any time. When it is used for the first time, a relevant structure is added to the document. This definition is used for all later GD\&T calls and is not repeated for them. 
691
692 @subsubsection occt_xde_2_7_2 Adding a GD\&T
693 *XCAFDoc_DimTolTool* provides methods to create GD\&T 'empty' entities:
694   * *AddDimension* - for a new dimension;
695   * *AddGeomTolerance* - for a new geometric tolerance;
696   * *AddDatum* - for a new geometric tolerance datum.
697
698 All methods create a sub-label for the corresponding GD\&T entity of the tool master label and attach an attribute specific for the
699 created entity.
700
701 Here is an example of adding a new dimension:
702 ~~~~~
703 TDF_Label aDimLabel = myDimTolTool->AddDimension();
704 if (!aDimLabel.IsNull())
705 {
706   // error processing
707 }
708 ~~~~~
709 A similar approach can be used for other GD\&T types.
710
711 @subsubsection occt_xde_2_7_3 Editing a GD\&T
712 A newly added GD\&T entity is empty. To set its data a corresponding access object should be used as it is demonstrated
713 below, where the dimension becomes a linear distance between two points.
714 ~~~~~
715 Handle(XCAFDoc_Dimension) aDimAttr;
716 aDimLabel.FindAttribute(XCAFDoc_Dimension::GetID(), aDimAttr);
717 if (!aDimAttr.IsNull())
718 {
719   Handle(XCAFDimTolObjects_DimensionObject) aDimObject = aDimAttr->GetObject();
720   // set dimension data
721   aDimObject->SetType(XCAFDimTolObjects_DimensionType_Location_LinearDistance);
722   aDimObject->SetPoint(thePnt1);  // the first reference point
723   aDimObject->SetPoint2(thePnt2); // the second reference point
724   aDimObject->SetValue(theValue); // the distance value
725   //...
726   aDimAttr->SetObject(aDimObject);
727 }
728 ~~~~~
729 A similar approach can be used for other GD\&T types.
730
731 @subsubsection occt_xde_2_7_4 Linking GD\&Ts
732 To link a GD\&T entity with other OCAF labels (e.g. representing shapes) one should use the following methods:
733   * *SetDimension* - for dimensions;
734   * *SetGeomTolerance* - for geometric tolerances;
735   * *SetDatum* - for geometric tolerance datums.
736
737 These methods can take a single label or a sequence of labels. All previous links will be removed.
738
739 The example below demonstrates linking of a dimension to sequences of shape labels:
740 ~~~~~
741 TDF_LabelSequence aShapes1, aShapes2;
742 aShapes1.Append(aShape11);
743 //...
744 aShapes2.Append(aShape21);
745 //...
746 aDGTTool->SetDimension(aShapes1, aShapes2, aDimLabel);
747 ~~~~~
748
749 In addition, a special method *SetDatumToGeomTol* should be used to link a datum with a geometric tolerance.
750
751 @subsubsection occt_xde_2_7_5 Finding GD\&Ts and reference shapes
752
753 *XCAFDimTolObjects_Tool* class provides basic capabilities for searching GD\&Ts linked to shapes.
754 The tool provides sequences of dimensions, geometric tolerances and datums linked with a shape. A series of related datums is also returned for geometric tolerances.
755
756 To get reference shapes for a GD\&T entity one can use *GetRefShapeLabel* from *XCAFDoc_DimTolTool*.
757
758 *XCAFDoc_DimTolTool* provides methods to get lists of all dimensions, geometric tolerances and datums.
759
760 @subsubsection occt_xde_2_7_6 Storing custom data
761 Every GD\&T entity in XDE is represented as a label with attached attribute identifying entity type. All specific data is
762 stored in sub-labels in standard OCAF attributes, such as *TDataStd_Integer*, *TDataStd_IntegerArray*, *TDataStd_RealArray* and so on.
763 Sub-label tags are reserved for internal use and cannot be used for storing custom data. The following tag ranges are reserved for
764 GD\&T entities:
765   * 1 - 17 - for dimensions;
766   * 1 - 17 - for geometric tolerances;
767   * 1 - 19 - for datums.
768 Custom data can be stored in labels with tags beyond the ranges listed above.
769
770 @subsection occt_xde_2_8 Clipping planes
771
772 In an XDE document, Clipping planes are managed by the class *XCAFDoc_ClippingPlaneTool*. It works basing on the same principles as ShapeTool works with Shapes. This tool can be provided on the Main Label or on any sub-label. Clipping planes are stored in a child of the starting document label 0.1.8, where planes themselves are defined as *TDataXtd_Plane* attribute. *TDataStd_Name* attribute is used for naming.
773
774 To query, edit, or initialize a Document to handle clipping planes of XCAF, use: 
775 ~~~~~
776 Handle(XCAFDoc_ClippingPlaneTool) myClipPlaneTool = 
777 XCAFDoc_DocumentTool::ClippingPlaneTool(Doc->Main()); 
778 ~~~~~
779 This call can be used at any time. When it is used for the first time, a relevant structure is added to the document. 
780
781 To add a clipping plane use one of overloaded methods *AddClippingPlane*, e.g.:
782 ~~~~~
783 gp_Pln aPln = ...
784 Standard_Boolean aCapping = ...
785 TDF_Label aClipPlnLbl = myClipPlaneTool->AddClippingPlane(aPln, "Name of plane", aCapping);
786 if (aClipPlnLbl.IsNull())
787 {
788   // error processing
789 }
790 ~~~~~ 
791
792 To remove a plane use *RemoveClippingPlane* method, e.g.:
793 ~~~~~
794 if (!myClipPlaneTool->RemoveClippingPlane(aClipPlnLbl))
795 {
796   // not removed
797 }
798 ~~~~~
799 The plane will not be removed if it is referenced in at least one view.
800
801 To change the clipping plane and its name use *UpdateClippingPlane* method, e.g.:
802 ~~~~~
803 gp_Pln aPln = ...
804 myClipPlaneTool->UpdateClippingPlane(aClipPlnLbl, aPln, "New name of plane");
805 ~~~~~
806
807 Capping property can be changed using *SetCapping* method, e.g.:
808 ~~~~~
809 Standard_Boolean aCapping = ...
810 myClipPlaneTool->SetCapping(aClipPlnLbl, aCapping);
811 ~~~~~
812
813 *XCAFDoc_ClippingPlaneTool* can be used to get all clipping plane labels and to check if a label belongs to the *ClippingPlane table*, e.g.:
814 ~~~~~
815 TDF_LabelSequence aClipPlaneLbls;
816 myClipPlaneTool->GetClippingPlanes(aClipPlaneLbls);
817 ...
818 for (TDF_LabelSequence::Iterator anIt(aClipPlaneLbls); anIt.More(); anIt.Next())
819 {
820   if (myClipPlaneTool->IsClippingPlane(anIt.Value()))
821   {
822     // the label is a clipping plane
823     gp_Pln aPln;
824     TCollection_ExtendedString aName;
825     Standard_Boolean aCapping;
826     if (!myClipPlaneTool->GetClippingPlane(anIt.Value(), aPln, aName, aCapping))
827     {
828       // error processing
829     }
830     ...
831   }
832 }
833 ~~~~~
834
835 @subsection occt_xde_2_9 Saved views
836
837 In an XDE document, Views are managed by the class *XCAFDoc_ViewTool*. It works basing on the same principles as ShapeTool works with Shapes. This tool can be provided on the Main Label or on any sub-label. Views are stored in a child of the starting document label 0.1.7, where a view itself is defined as *XCAFDoc_View* sub-class of *TDF_Attribute*. Views and selected shapes, clipping planes, GD\&Ts and notes are related by Graph Nodes.
838
839 To query, edit, or initialize a Document to handle views of XCAF, use: 
840 ~~~~~
841 Handle(XCAFDoc_ViewTool) myViewTool = 
842 XCAFDoc_DocumentTool::ViewTool(Doc->Main()); 
843 ~~~~~
844 This call can be used at any time. When it is used for the first time, a relevant structure is added to the document. 
845
846 To add a view use *AddView* method and an access *XCAFView_Object* object to set camera parameters, e.g.:
847 ~~~~~
848 TDF_Label aViewLbl = myViewTool->AddView();
849 if (aViewLbl.IsNull())
850 {
851   // error processing
852 }
853 Handle(XCAFDoc_View) aViewAttr;
854 aViewLbl.FindAttribute(XCAFDoc_View::GetID(), aViewAttr);
855 if (!aViewAttr.IsNull())
856 {
857   Handle(XCAFView_Object) aViewObject = aViewAttr->GetObject();
858   // set view data
859   aViewObject->SetType(XCAFView_ProjectionType_Parallel);
860   aViewObject->SetViewDirection(theViewDir);
861   aViewObject->SetZoomFactor(2.0);
862   ...
863   aViewAttr->SetObject(aViewObject);
864 }
865 ~~~~~ 
866
867 To set shapes, clipping planes, GD\&Ts and notes selected for the view use one of overloaded *SetView* methods of *XCAFDoc_ViewTool*. 
868 To set only clipping planes one should use *SetClippingPlanes* method.
869 ~~~~~
870 TDF_LabelSequence aShapes; ...
871 TDF_LabelSequence aGDTs; ...
872 myViewTool->SetView(aShapes, aGDTs, aViewLbl);
873 TDF_LabelSequence aClippingPlanes; ...
874 myViewTool->SetClippingPlanes(aClippingPlanes, aViewLbl);
875 ~~~~~
876
877 To remove a view use *RemoveView* method.
878
879 To get all view labels and check if a label belongs to the View table use:
880 ~~~~~
881 TDF_LabelSequence aViewLbls;
882 myViewTool->GetViewLabels(aViewLbls);
883 ...
884 for (TDF_LabelSequence::Iterator anIt(aViewLbls); anIt.More(); anIt.Next())
885 {
886   if (myViewTool->IsView(anIt.Value()))
887   {
888     // the label is a view
889     ...
890   }
891 }
892 ~~~~~
893
894 To get shapes, clipping planes, GD\&Ts or notes associated with a particular view use the following methods:
895   * *GetRefShapeLabel* - returns a sequence of associated shape labels;
896   * *GetRefGDTLabel* - returns a sequence of associated GDT labels;
897   * *GetRefClippingPlaneLabel* - returns a sequence of associated clipping plane labels;
898   * *GetRefNoteLabel* - returns a sequence of associated note labels;
899   * *GetRefAnnotationLabel* - returns a sequence of associated annotated labels.
900
901 And vice versa, to get views that display a particular clipping plane, GD\&T or note use the following methods:
902   * *GetViewLabelsForShape* - returns a sequence of view labels associated with a shape;
903   * *GetViewLabelsForGDT* - returns a sequence of view labels associated with a GD\&T;
904   * *GetViewLabelsForClippingPlane* - returns a sequence of view labels associated with a clipping plane;
905   * *GetViewLabelsForNote* - returns a sequence of view labels associated with a note;
906   * *GetViewLabelsForAnnotation* - returns a sequence of view labels associated with an annotated label.
907
908 @subsection occt_xde_2_10 Custom notes
909
910 In an XDE document, custom notes are managed by the class *XCAFDoc_NotesTool*. 
911 It works basing on the same principles as ShapeTool works with Shapes. 
912 This tool can be provided on the Main Label or on any sub-label. 
913 The Property itself is defined as sub-class of *XCAFDoc_Note* abstract class, which is a sub-class of *TDF_Attribute* one. 
914
915 Custom notes are stored in a child of the *XCAFDoc_NotesTool* label, at label 0.1.9.1. Each note then corresponds to a dedicated label. A note may be attached to a document item identified by a label, a sub-shape identified by integer index or an attribute identified by GUID. Annotations are stored in a child of the *XCAFDoc_NotesTool* label, at label 0.1.9.2.
916 Notes binding is done through *XCAFDoc_GraphNode* attribute.
917
918   @figure{/user_guides/xde/images/xde_notes001.png,"Structure of notes part of XCAF document",240}
919   
920 @subsubsection occt_xde_2_10_1 Initialization
921
922 To query, edit, or initialize a Document to handle custom notes of XCAF, use: 
923 ~~~~~
924 Handle(XCAFDoc_NotesTool) myNotes = 
925 XCAFDoc_DocumentTool::NotesTool(Doc->Main ()); 
926 ~~~~~
927 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 later notes calls and will not be repeated for them. 
928   
929 @subsubsection occt_xde_2_10_2 Creating Notes
930
931 Before annotating a Document item a note must be created using one of the following methods of *XCAFDoc_NotesTool* class:
932 - *CreateComment* : creates a note with a textual comment;
933 - *CreateBinData* : creates a note with arbitrary binary data, e.g. contents of a file.
934
935 Both methods return an instance of *XCAFDoc_Note* class.
936 ~~~~~
937 Handle(XCAFDoc_NotesTool) myNotes = ...
938 Handle(XCAFDoc_Note) myNote = myNotes->CreateComment("User", "Timestamp", "Hello, World!");
939 ~~~~~
940 This code adds a child label to label 0.1.9.1 with *XCAFDoc_NoteComment* attribute.
941
942 @subsubsection occt_xde_2_10_3 Editing a Note
943 An instance of *XCAFDoc_Note* class can be used for note editing.
944 One may change common note data.
945 ~~~~~
946 myNote->Set("New User", "New Timestamp");
947 ~~~~~
948 To change specific data one needs to down cast *myNote* handle to the appropriate sub-class:
949 ~~~~~
950 Handle(XCAFDoc_NoteComment) myCommentNote = Handle(XCAFDoc_NoteComment)::DownCast(myNote);
951 if (!myCommentNote.IsNull()) {
952   myCommentNote->Set("New comment");
953 }
954 ~~~~~
955 In order to edit auxiliary note data such as text and attachment position, plane for rendering and tessellated presentation,
956 one should use a transfer object *XCAFNoteObjects_NoteObject* by GetObject and SetObject methods of *XCAFDoc_Note* class.
957 *XCAFNoteObjects_NoteObject* class provides the following functionality:
958 - HasPlane, GetPlane and SetPlane methods test, get and set plane for note rendering
959 - HasPoint, GetPoint and SetPoint methods test, get and set note attachment position on the annotated object
960 - HasPointText, GetPointText, SetPointText methods test, get and set test position
961 - GetPresentation and SetPresentation methods allow to test for and specify tessellated presentation
962
963 After getting, the transfer object can be edited and set back to the note:
964 ~~~~~
965 Handle(XCAFNoteObjects_NoteObject) aNoteObj = myNote->GetObject();
966 if (!aNoteObj.IsNull())
967 {
968   gp_Pnt aPntTxt (...);
969   aNoteObj->SetPointText (aPntTxt);
970   TopoDS_Shape aS = ...;
971   aNoteObj->SetPresentation (aS);
972   myNote->SetObject (aNoteObj);
973 }
974 ~~~~~
975
976 @subsubsection occt_xde_2_10_4 Adding Notes
977
978 Once a note has been created it can be bound to a Document item using the following *XCAFDoc_NotesTool* methods:
979 - *AddNote* : binds a note to a label;
980 - *AddNoteToAttr* : binds a note to a label's attribute;
981 - *AddNoteToSubshape* : binds a note to a sub-shape.
982
983 All methods return a pointer to *XCAFDoc_AssemblyItemRef* attribute identifying the annotated item.
984 ~~~~~
985 Handle(XCAFDoc_NotesTool) myNotes = ...
986 Handle(XCAFDoc_Note) myNote = ...
987 TDF_Label theLabel; ...
988 Handle(XCAFDoc_AssemblyItemRef) myRef = myNotes->AddNote(myNote->Label(), theLabel);
989 Standard_GUID theAttrGUID; ...
990 Handle(XCAFDoc_AssemblyItemRef) myRefAttr = myNotes->AddNoteToAttr(myNote->Label(), theAttrGUID);
991 Standard_Integer theSubshape = 1;
992 Handle(XCAFDoc_AssemblyItemRef) myRefSubshape = myNotes->AddNoteToSubshape(myNote->Label(), theSubshape);
993 ~~~~~
994 This code adds three child labels with *XCAFDoc_AssemblyItemRef* attribute to label 0.1.9.2. *XCAFDoc_GraphNode* attributes are added to the child labels and note labels.
995
996 @subsubsection occt_xde_2_10_5 Finding Notes
997
998 To find annotation labels under label 0.1.9.2 use the following *XCAFDoc_NotesTool* methods:
999 - *FindAnnotatedItem* : returns an annotation label for a label;
1000 - *FindAnnotatedItemAttr* : returns an annotation label for a label's attribute;
1001 - *FindAnnotatedItemSubshape* : returns an annotation label for a sub-shape.
1002
1003 ~~~~~
1004 Handle(XCAFDoc_NotesTool) myNotes = ...
1005 TDF_Label theLabel; ...
1006 TDF_Label myLabel = myNotes->FindAnnotatedItem(theLabel);
1007 Standard_GUID theAttrGUID; ...
1008 TDF_Label myLabelAttr = myNotes->FindAnnotatedItemAttr(theLabel, theAttrGUID);
1009 Standard_Integer theSubshape = 1;
1010 TDF_Label myLabelSubshape = myNotes->FindAnnotatedItemSubshape(theLabel, theSubshape);
1011 ~~~~~
1012 Null label will be returned if there is no corresponding annotation.
1013
1014 To get all notes of the Document item use the following *XCAFDoc_NotesTool* methods:
1015 - *GetNotes* : outputs a sequence of note labels bound to a label;
1016 - *GetAttrNotes* : outputs a sequence of note labels bound to a label's attribute;
1017 - *GetAttrSubshape* : outputs a sequence of note labels bound to a sub-shape.
1018
1019 All these methods return the number of notes.
1020 ~~~~~
1021 Handle(XCAFDoc_NotesTool) myNotes = ...
1022 TDF_Label theLabel; ...
1023 TDF_LabelSequence theNotes;
1024 myNotes->GetNotes(theLabel, theNotes);
1025 Standard_GUID theAttrGUID; ...
1026 TDF_LabelSequence theNotesAttr;
1027 myNotes->GetAttrNotes(theLabel, theAttrGUID, theNotesAttr);
1028 Standard_Integer theSubshape = 1;
1029 TDF_LabelSequence theNotesSubshape;
1030 myNotes->GetAttrSubshape(theLabel, theSubshape, theNotesSubshape);
1031 ~~~~~
1032
1033 @subsubsection occt_xde_2_10_6 Removing Notes
1034
1035 To remove a note use one of the following *XCAFDoc_NotesTool* methods:
1036 - *RemoveNote* : unbinds a note from a label;
1037 - *RemoveAttrNote* : unbinds a note from a label's attribute;
1038 - *RemoveSubshapeNote* : unbinds a note from a sub-shape.
1039
1040 ~~~~~
1041 Handle(XCAFDoc_Note) myNote = ...
1042 TDF_Label theLabel; ...
1043 myNotes->RemoveNote(myNote->Label(), theLabel);
1044 Standard_GUID theAttrGUID; ...
1045 myRefAttr = myNotes->RemoveAttrNote(myNote->Label(), theAttrGUID);
1046 Standard_Integer theSubshape = 1;
1047 myNotes->RemoveSubshapeNote(myNote->Label(), theSubshape);
1048 ~~~~~
1049 A note will not be deleted automatically.
1050 Counterpart methods to remove all notes are available, too.
1051   
1052 @subsubsection occt_xde_2_10_7 Deleting Notes
1053
1054 To delete note(s) use the following *XCAFDoc_NotesTool* methods:
1055 - *DeleteNote* : deletes a single note;
1056 - *DeleteNotes* : deletes a sequence of notes;
1057 - *DeleteAllNotes* : deletes all Document notes;
1058 - *DeleteOrphanNotes* : deletes notes not bound to Document items.
1059
1060 All these methods except for the last one break all links with Document items as well.
1061   
1062 @subsection occt_xde_2_11 Reading and Writing STEP or IGES
1063 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. 
1064 The same can be said for Viewing: presentations can be defined from Shapes and Colors. 
1065
1066 There are several important points to consider: 
1067   * 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.
1068   * XDE provides mapping with data other than Shapes. Names, Colors, Layers, GD\&T, Clipping planes, Views, Validation Properties (Centroid, Volume, Area), and Assembly Structure are hierarchic with rigid motion. Currently, Clipping planes and Views writing supported for XBF format only.
1069   * 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.
1070   * 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.
1071   
1072 The packages to manage this are *IGESCAFControl* for IGES, and *STEPCAFControl* for STEP. 
1073
1074 @subsubsection occt_xde_2_11_1 Reading a STEP file
1075 To read a STEP file by itself, use: 
1076
1077 ~~~~~
1078 STEPCAFControl_Reader reader; 
1079 IFSelect_ReturnStatus readstat = reader.ReadFile(filename); 
1080 // The various ways of reading a file are available here too : 
1081 // to read it by the reader, to take it from a WorkSession ... 
1082 Handle(TDocStd_Document) doc... 
1083 // the document referred to is already defined and 
1084 // properly initialized. 
1085 // Now, the transfer itself 
1086 if ( !reader.Transfer ( doc ) ) { 
1087   cout;Cannot read any relevant data from the STEP file;endl; 
1088   // abandon .. 
1089
1090 // Here, the Document has been filled from a STEP file, 
1091 // it is ready to use 
1092 ~~~~~
1093
1094 In addition, the reader provides methods that are applicable to document transfers and for directly querying of the data produced. 
1095 @subsubsection occt_xde_2_11_2 Writing a STEP file
1096 To write a STEP file by itself, use: 
1097
1098 ~~~~~
1099 STEPControl_StepModelType mode = 
1100 STEPControl_AsIs; 
1101 // Asis is the recommended value, others are available 
1102 // Firstly, perform the conversion to STEP entities 
1103 STEPCAFControl_Writer writer; 
1104 //(the user can work with an already prepared WorkSession or create a //new one) 
1105 Standard_Boolean scratch = Standard_False; 
1106 STEPCAFControl_Writer writer ( WS, scratch ); 
1107 // Translating document (conversion) to STEP 
1108 if ( ! writer.Transfer ( Doc, mode ) ) { 
1109   cout;The document cannot be translated or gives no result;endl; 
1110   // abandon .. 
1111
1112 // Writing the File 
1113 IFSelect_ReturnStatus stat = writer.Write(file-name); 
1114 ~~~~~
1115
1116 @subsubsection occt_xde_2_11_3 Reading an IGES File
1117 Use the same procedure as for a STEP file but with IGESCAFControl instead of STEPCAFControl. 
1118 @subsubsection occt_xde_2_11_4 Writing an IGES File
1119 Use the same procedure as for a STEP file but with IGESCAFControl instead of STEPCAFControl.
1120  
1121 @subsection occt_xde_2_12 Using an XDE Document
1122 There are several ways of exploiting XDE data from an application, you can: 
1123  1. Get the data relevant for the application by mapping XDE/Appli, then discard the XDE data once it has been used.
1124  2. Create a reference from the Application Document to the XDE Document, to have its data available as external data.
1125  3. Embed XDE data inside the Application Document (see the following section for details).
1126  4. Directly exploit XDE data such as when using file checkers.
1127
1128 @subsubsection occt_xde_2_12_1 XDE Data inside an Application Document
1129 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. 
1130
1131 In addition, as XDE data is defined and managed in a modular way, you can consider exclusively Assembly Structure, only Colors, and so on. 
1132
1133 As XDE provides an extension of the data structure, for relevant data in standardized exchanges, note the following: 
1134   * This data structure is fitted for data exchange, rather than for use by the final application.
1135   * The provided definitions are general, for common use and therefore do not bring strongly specific semantics.
1136   
1137 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. 
1138
1139 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. 
1140