0031002: Documentation - update Overview for 7.4.0
[occt.git] / dox / user_guides / xde / xde.md
CommitLineData
ba06f8bb 1 Extended Data Exchange (XDE) {#occt_user_guides__xde}
72b7576f 2============================
e5bd0d98 3
4@tableofcontents
5
e2b55410 6@section occt_xde_1 Introduction
7
7863dabb 8This 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 <a href="https://www.opencascade.com/content/tutorial-learning">E-learning & Training</a> offerings.
dba69de2 9
e2b55410 10The 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.
dba69de2 11
e2b55410 12Data 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
14Finally, the XDE provides reader and writer tools for reading and writing the data supported by XCAF to and from IGES and STEP files.
15
d6b4d3d0 16@figure{/user_guides/xde/images/646_xde_11_400.png,"Shape imported using XDE",240}
e2b55410 17
18The XDE component requires @ref occt_user_guides__shape_healing "Shape Healing" toolkit for operation.
19
20@subsection occt_xde_1_1 Basic terms
dba69de2 21
72b7576f 22For better understanding of XDE, certain key terms are defined:
3f812249 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.
e2b55410 26
27@subsection occt_xde_1_2 XDE Organization
28
72b7576f 29The 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.
dba69de2 30
72b7576f 31XDE 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.
dba69de2 32
33The 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
72b7576f 35Basic 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.
dba69de2 36The Document used by XDE usually starts as a *TDocStd_Document*.
37
e2b55410 38@subsection occt_xde_1_3 Assemblies
72b7576f 39XDE 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.
dba69de2 40
72b7576f 41For example, a mechanical assembly can be defined as follows:
d6b4d3d0 42@figure{/user_guides/xde/images/xde_image003.png,"Assembly Description",240}
dba69de2 43
44
d6b4d3d0 45@figure{/user_guides/xde/images/xde_image004.png,"Assembly View",240}
dba69de2 46
72b7576f 47
48XDE 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).
dba69de2 49
e2b55410 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.
dba69de2 51
e2b55410 52@subsection occt_xde_1_4 Validation Properties
72b7576f 53Validation 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.
dba69de2 54
72b7576f 55Advanced Data Exchange supports both reading and writing of validation properties, and provides a tool to check them.
dba69de2 56
d6b4d3d0 57@figure{/user_guides/xde/images/xde_image005.png,"Validation Property Descriptions",240}
dba69de2 58
72b7576f 59Check logs contain deviations of computed values from the values stored in a STEP file. A typical example appears as follows:
60
4ee1bdf4 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" |
dba69de2 76
77
72b7576f 78In our example, it can be seen that no errors were detected for either area, volume or positioning data.
dba69de2 79
e2b55410 80@subsection occt_xde_1_5 Names
81
72b7576f 82XDE 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.
e2b55410 83
d6b4d3d0 84@figure{/user_guides/xde/images/614_xde_04_400.png,"Instance Names",360}
e2b55410 85
86@subsection occt_xde_1_6 Colors and Layers
dba69de2 87XDE 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*:
4ee1bdf4 88 * generic color <i>(XCAFDoc_ColorGen)</i>
89 * surface color <i>(XCAFDoc_ColorSurf)</i>
90 * curve color <i>(XCAFDoc_ColorCurv)</i>
e2b55410 91
d6b4d3d0 92 @figure{/user_guides/xde/images/xde_image006.png,"Colors and Layers",240}
dba69de2 93
cf0786da 94@subsection occt_xde_1_7 Geometric Dimensions & Tolerances (GD\&T)
a8a3b37c 95
cf0786da 96GD\&T are a type of Product and Manufacturing Information (PMI) that can be either computed automatically by a CAD system,
a8a3b37c 97or 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
98for the Representation and Presentation of Product Manufacturing Information (PMI) (AP242)</a>
99
cf0786da 100XDE can read and write GD\&T data of the following types:
a8a3b37c 101* dimensions, such as distance, length, radius and so on;
102* geometric tolerances;
14deaf42 103* datums, i.e theoretically exact geometric references, such as point, line or plane, to which toleranced features are related.
a8a3b37c 104
cf0786da 105XDE supports two presentations of GD\&T data:
a8a3b37c 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
112XDE supports reading from STEP and storing named planes used for clipping.
113Currently, XDE supports saving of clipping planes in XBF format only.
114
115XDE provides capabilities for adding, editing and removing clipping planes.
116
117@subsection occt_xde_1_9 Saved views
118
14deaf42 119XDE supports reading from STEP views. Views allow saving information about camera parameters (position, direction, zoom factor, etc.)
a8a3b37c 120and visible shapes, PMIs, used clipping planes and notes. Currently, XDE supports saving of clipping planes in XBF format only.
121
122XDE 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
024d6f77 128
a8a3b37c 129Custom 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.
024d6f77 130
131Notes API provides the following functionality:
a8a3b37c 132 * Returns the total number of notes and annotated items;
133 * Returns labels for all notes and annotated items;
024d6f77 134 * Creates notes:
a8a3b37c 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.
dba69de2 147
e2b55410 148@section occt_xde_2 Working with XDE
dba69de2 149
e2b55410 150@subsection occt_xde_2_1 Getting started
dba69de2 151
dba69de2 152As explained in the last chapter, XDE uses *TDocStd_Documents* as a starting point. The general purpose of XDE is:
e2b55410 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
160The Document used by XDE usually starts as a *TDocStd_Document*.
161
162@subsubsection occt_xde_2_1_1 Environment variables
163To 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
72b7576f 168Before 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.
dba69de2 169
170To find out if an existing *TDocStd_Document* is suitable for XDE, use:
171~~~~~
72b7576f 172Handle(TDocStd_Document) doc...
173if ( XCAFDoc_DocumentTool::IsXCAFDocument (doc) ) { .. yes .. }
dba69de2 174~~~~~
175If 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
e2b55410 177@subsubsection occt_xde_2_1_3 Get an Application or an Initialized Document
72b7576f 178If you want to retrieve an existing application or an existing document (known to be correctly structured for XDE), use:
dba69de2 179~~~~~
72b7576f 180Handle(TDocStd_Document) aDoc;
4ee1bdf4 181Handle(XCAFApp_Application) anApp = XCAFApp_Application::GetApplication();
dba69de2 182anApp->NewDocument(;MDTV-XCAF;,aDoc);
183~~~~~
e2b55410 184
dba69de2 185@subsection occt_xde_2_2 Shapes and Assemblies
4ee1bdf4 186
187@subsubsection occt_xde_2_2_1 Initialize an XDE Document (Shapes)
dba69de2 188An 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~~~~~
72b7576f 190Handle(TDocStd_Document) doc...
191Handle (XCAFDoc_ShapeTool) myAssembly =
4ee1bdf4 192XCAFDoc_DocumentTool::ShapeTool (Doc->Main());
dba69de2 193TDF_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
4ee1bdf4 197@subsubsection occt_xde_2_2_2 Get a Node considered as an Assembly
dba69de2 198To 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~~~~~
72b7576f 200Handle(TDocStd_Document) doc...
4ee1bdf4 201Handle(XCAFDoc_ShapeTool) myAssembly = XCAFDoc_DocumentTool::ShapeTool (aLabel);
dba69de2 202~~~~~
4ee1bdf4 203In 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)*.
dba69de2 204
205You 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
acc909a8 209@subsubsection occt_xde_2_2_3 Updating the Assemblies after Filling or Editing
72b7576f 210Some 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).
dba69de2 211
72b7576f 212To update the representations, use:
dba69de2 213~~~~~
acc909a8 214myAssembly->UpdateAssemblies();
dba69de2 215~~~~~
acc909a8 216This 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.
dba69de2 219
220@subsubsection occt_xde_2_2_4 Adding or Setting Top Level Shapes
221
72b7576f 222Shapes 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
dba69de2 225
226**Note** that several top-level shapes can be added to the same component.
227
72b7576f 228A shape to be added can be defined as a compound (if required), with the following interpretations:
dba69de2 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
72b7576f 232To break down a Compound in the assembly structure, use:
dba69de2 233~~~~~
72b7576f 234Standard_Boolean makeAssembly;
235// True to interpret a Compound as an Assembly,
236// False to take it as a whole
4ee1bdf4 237aLabel = myAssembly->AddShape(aShape, makeAssembly);
dba69de2 238~~~~~
72b7576f 239Each node of the assembly therefore refers to its sub-shapes.
dba69de2 240
72b7576f 241Concerning 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.
dba69de2 242
243@subsubsection occt_xde_2_2_5 Setting a given Shape at a given Label
72b7576f 244A top-level shape can be changed. In this example, no interpretation of compound is performed:
dba69de2 245~~~~~
72b7576f 246Standard_CString LabelString ...;
247// identifies the Label (form ;0:i:j...;)
248TDF_Label aLabel...;
249// A label must be present
4ee1bdf4 250myAssembly->SetShape(aLabel, aShape);
dba69de2 251~~~~~
252
253@subsubsection occt_xde_2_2_6 Getting a Shape from a Label
72b7576f 254To get a shape from its Label from the top-level, use:
dba69de2 255~~~~~
256TDF_Label aLabel...
257// A label must be present
72b7576f 258if (aLabel.IsNull()) {
dba69de2 259 // no such label : abandon
260}
261TopoDS_Shape aShape;
262aShape = myAssembly->GetShape(aLabel);
263if (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
270To get a Label, which is attached to a Shape from the top-level, use:
271~~~~~
72b7576f 272Standard_Boolean findInstance = Standard_False;
dba69de2 273// (this is default value)
274aLabel = myAssembly->FindShape(aShape [,findInstance]);
72b7576f 275if (aLabel.IsNull()) {
dba69de2 276 // no label found for this shape
277}
278~~~~~
279If *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
72b7576f 283Various other queries can be made from a Label within the Main Item of XDE:
dba69de2 284#### Main Shapes
285
72b7576f 286To determine if a Shape is recorded (or not), use:
dba69de2 287~~~~~
4ee1bdf4 288if ( myAssembly->IsShape(aLabel) ) { .. yes .. }
dba69de2 289~~~~~
72b7576f 290
dba69de2 291To determine if the shape is top-level, i.e. was added by the *AddShape* method, use:
292~~~~~
293if ( myAssembly->IsTopLevel(aLabel) ) { .. yes .. }
294~~~~~
72b7576f 295
dba69de2 296To get a list of top-level shapes added by the *AddShape* method, use:
297~~~~~
72b7576f 298TDF_LabelSequence frshapes;
4ee1bdf4 299myAssembly->GetShapes(frshapes);
dba69de2 300~~~~~
72b7576f 301
302To get all free shapes at once if the list above has only one item, use:
dba69de2 303~~~~~
4ee1bdf4 304TopoDS_Shape result = myAssembly->GetShape(frshapes.Value(1));
dba69de2 305~~~~~
72b7576f 306
307If there is more than one item, you must create and fill a compound, use:
dba69de2 308
309~~~~~
72b7576f 310TopoDS_Compound C;
311BRep_Builder B;
312B.MakeCompound(C);
313for(Standard_Integer i=1; i=frshapes.Length(); i++) {
dba69de2 314 TopoDS_Shape S = myAssembly->GetShape(frshapes.Value(i));
315 B.Add(C,S);
72b7576f 316}
dba69de2 317~~~~~
72b7576f 318
319In our example, the result is the compound C.
320To determine if a shape is a free shape (no reference or super-assembly), use:
dba69de2 321
322~~~~~
4ee1bdf4 323if ( myAssembly->IsFree(aLabel) ) { .. yes .. }
dba69de2 324~~~~~
72b7576f 325
326To get a list of Free Shapes (roots), use:
dba69de2 327
328~~~~~
72b7576f 329TDF_LabelSequence frshapes;
dba69de2 330myAssembly->GetFreeShapes(frshapes);
331~~~~~
72b7576f 332
333To get the shapes, which use a given shape as a component, use:
dba69de2 334~~~~~
72b7576f 335TDF_LabelSequence users;
4ee1bdf4 336Standard_Integer nbusers = myAssembly->GetUsers(aLabel,users);
dba69de2 337~~~~~
338The count of users is contained with *nbusers*. It contains 0 if there are no users.
339
340#### Assembly and Components
72b7576f 341To determine if a label is attached to the main part or to a sub-part (component), use:
dba69de2 342~~~~~
4ee1bdf4 343if (myAssembly->IsComponent(aLabel)) { .. yes .. }
dba69de2 344~~~~~
72b7576f 345To determine whether a label is a node of a (sub-) assembly or a simple shape, use:
dba69de2 346~~~~~
4ee1bdf4 347if ( myAssembly->IsAssembly(aLabel) ) { .. yes .. }
dba69de2 348~~~~~
72b7576f 349
350If the label is a node of a (sub-) assembly, you can get the count of components, use:
dba69de2 351~~~~~
72b7576f 352Standard_Boolean subchilds = Standard_False; //default
4ee1bdf4 353Standard_Integer nbc = myAssembly->NbComponents (aLabel [,subchilds]);
dba69de2 354~~~~~
355
356If *subchilds* is True, commands also consider sub-levels. By default, only level one is checked.
72b7576f 357
358To get component Labels themselves, use:
dba69de2 359~~~~~
72b7576f 360Standard_Boolean subchilds = Standard_False; //default
361TDF_LabelSequence comps;
4ee1bdf4 362Standard_Boolean isassembly = myAssembly->GetComponents
72b7576f 363(aLabel,comps[,subchilds]);
dba69de2 364~~~~~
365@subsubsection occt_xde_2_2_9 Instances and References for Components
72b7576f 366To determine if a label is a simple shape, use:
dba69de2 367~~~~~
368if ( myAssembly->IsSimpleShape(aLabel) ) { .. yes .. }
369~~~~~
72b7576f 370To determine if a label is a located reference to another one, use:
dba69de2 371~~~~~
4ee1bdf4 372if ( myAssembly->IsReference(aLabel) ) { .. yes .. }
dba69de2 373~~~~~
72b7576f 374If the label is a located reference, you can get the location, use:
dba69de2 375~~~~~
4ee1bdf4 376TopLoc_Location loc = myAssembly->GetLocation (aLabel);
dba69de2 377~~~~~
72b7576f 378To get the label of a referenced original shape (also tests if it is a reference), use:
dba69de2 379~~~~~
4ee1bdf4 380Standard_Boolean isref = myAssembly->GetReferredShape
72b7576f 381(aLabel, refLabel);
dba69de2 382~~~~~
383
384**Note** *isref* returns False if *aLabel* is not for a reference.
385
386@subsection occt_xde_2_3 Editing Shapes
387In addition to the previously described *AddShape* and *SetShape*, several shape edits are possible.
72b7576f 388
389To remove a Shape, and all its sub-labels, use:
dba69de2 390~~~~~
4ee1bdf4 391Standard_Boolean remsh = myAssembly->RemoveShape(aLabel);
72b7576f 392// remsh is returned True if done
dba69de2 393~~~~~
394This operation will fail if the shape is neither free nor top level.
72b7576f 395
396To add a Component to the Assembly, from a new shape, use:
dba69de2 397~~~~~
72b7576f 398Standard_Boolean expand = Standard_False; //default
dba69de2 399TDF_Label aLabel = myAssembly->AddComponent (aShape [,expand]);
400~~~~~
401If *expand* is True and *aShape* is a Compound, *aShape* is broken down to produce sub-components, one for each of its sub-shapes.
72b7576f 402
403To 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:
dba69de2 404~~~~~
72b7576f 405TDF_Label refLabel ...; // the label of reference shape
406TopLoc_Location loc ...; // the desired location
dba69de2 407TDF_Label aLabel = myAssembly->AddComponent (refLabel, loc);
408~~~~~
72b7576f 409To remove a component from the assembly, use:
dba69de2 410~~~~~
411myAssembly->RemoveComponent (aLabel);
412~~~~~
72b7576f 413
dba69de2 414@subsection occt_xde_2_4 Management of Sub-Shapes
415In 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:
72b7576f 416To add a sub-shape to a given Label, use:
dba69de2 417~~~~~
418TDF_Label subLabel = myAssembly->AddSubShape (aLabel, subShape);
419~~~~~
72b7576f 420
421To find the Label attached to a given sub-shape, use:
dba69de2 422~~~~~
72b7576f 423TDF_Label subLabel; // new label to be computed
4ee1bdf4 424if ( myAssembly-> FindSubShape (aLabel, subShape, subLabel)) { .. yes .. }
dba69de2 425~~~~~
426If the sub-shape is found (yes), *subLabel* is filled by the correct value.
72b7576f 427
428To find the top-level simple shape (not a compound whether free or not), which contains a given sub-shape, use:
dba69de2 429~~~~~
430TDF_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.
72b7576f 433
434To get the sub-shapes of a shape, which are recorded under a label, use:
dba69de2 435~~~~~
72b7576f 436TDF_LabelSequence subs;
dba69de2 437Standard_Boolean hassubs = myAssembly->GetSubShapes (aLabel,subs);
438~~~~~
439@subsection occt_xde_2_5 Properties
72b7576f 440Some 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)
445Some 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).
446Colors 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.
449When 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.
dba69de2 450@subsubsection occt_xde_2_5_1 Name
451Name 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.
72b7576f 453 * In STEP, there are two levels: Part Names and Entity Names:
dba69de2 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
72b7576f 458These considerations are not specific to XDE. What is specific to data exchange is the way names are attached to entities.
459
460To get the name attached to a label (as a reminder using OCAF), use:
dba69de2 461~~~~~
72b7576f 462Handle(TDataStd_Name) N;
463if ( !aLabel.FindAttribute(TDataStd_Name::GetID(),N)) {
dba69de2 464 // no name is attached
72b7576f 465}
dba69de2 466TCollection_ExtendedString name = N->Get();
467~~~~~
468
72b7576f 469Don't forget to consider Extended String as ASCII, for the exchange file.
470
471To set a name to a label (as a reminder using OCAF), use:
dba69de2 472~~~~~
72b7576f 473TCollection_ExtendedString aName ...;
474// contains the desired name for this Label (ASCII)
475TDataStd_Name::Set (aLabel, aName);
dba69de2 476~~~~~
477
478@subsubsection occt_xde_2_5_2 Centroid
479A 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
481This 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
483A 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
72b7576f 485To get a Centroid attached to a Shape, use:
dba69de2 486~~~~~
72b7576f 487gp_Pnt pos;
488Handle(XCAFDoc_Centroid) C;
489aLabel.FindAttribute ( XCAFDoc_Centroid::GetID(), C );
dba69de2 490if ( !C.IsNull() ) pos = C->Get();
491~~~~~
72b7576f 492
493To set a Centroid to a Shape, use:
dba69de2 494~~~~~
72b7576f 495gp_Pnt pos (X,Y,Z);
496// the position previously computed for the centroid
497XCAFDoc_Centroid::Set ( aLabel, pos );
dba69de2 498~~~~~
499
500@subsubsection occt_xde_2_5_3 Area
501An 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*.
72b7576f 502This 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
504To get an area attached to a Shape, use:
dba69de2 505~~~~~
72b7576f 506Standard_Real area;
507Handle(XCAFDoc_Area) A;
508L.FindAttribute ( XCAFDoc_Area::GetID(), A );
dba69de2 509if ( !A.IsNull() ) area = A->Get();
72b7576f 510
511To set an area value to a Shape, use:
512Standard_Real area ...;
513// value previously computed for the area
514XCAFDoc_Area::Set ( aLabel, area );
dba69de2 515~~~~~
516@subsubsection occt_xde_2_5_4 Volume
517A 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*.
518This notion has been introduced in STEP. It may be attached to simple shapes or their assemblies for computing cumulated volumes and centers of gravity.
72b7576f 519
520To get a Volume attached to a Shape, use:
dba69de2 521~~~~~
72b7576f 522Standard_Real volume;
523Handle(XCAFDoc_Volume) V;
524L.FindAttribute ( XCAFDoc_Volume::GetID(), V );
dba69de2 525if ( !V.IsNull() ) volume = V->Get();
526~~~~~
72b7576f 527
528To set a volume value to a Shape, use:
dba69de2 529~~~~~
72b7576f 530Standard_Real volume ...;
531// value previously computed for the volume
532XCAFDoc_Volume::Set ( aLabel, volume );
dba69de2 533~~~~~
e2b55410 534@subsection occt_xde_2_6 Colors and Layers
535
536XDE 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
d6b4d3d0 538@figure{/user_guides/xde/images/239_xde_12_400.png,"Motor Head",240}
e2b55410 539
a8a3b37c 540In 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*.
dba69de2 541
e2b55410 542Colors 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
544Layers 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
546The 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.
dba69de2 549
72b7576f 550Colors and Shapes are related to by Tree Nodes.
dba69de2 551
72b7576f 552These definitions are common to various exchange formats, at least for STEP and IGES.
dba69de2 553
554@subsubsection occt_xde_2_6_1 Initialization
72b7576f 555To query, edit, or initialize a Document to handle Colors of XCAF, use:
dba69de2 556~~~~~
72b7576f 557Handle(XCAFDoc_ColorTool) myColors =
4ee1bdf4 558XCAFDoc_DocumentTool::ColorTool(Doc->Main ());
dba69de2 559~~~~~
72b7576f 560This 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.
dba69de2 561
562@subsubsection occt_xde_2_6_2 Adding a Color
72b7576f 563There are two ways to add a color. You can:
dba69de2 564 * add a new Color defined as *Quantity_Color* and then directly set it to a Shape (anonymous Color)
72b7576f 565 * define a new Property Color, add it to the list of Colors, and then set it to various shapes.
dba69de2 566When 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.
72b7576f 567
dba69de2 568To set a Color to a Shape using a label, use:
569~~~~~
72b7576f 570Quantity_Color Col (red,green,blue);
571XCAFDoc_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
4ee1bdf4 576myColors->SetColor ( aLabel, Col, ctype );
dba69de2 577~~~~~
72b7576f 578Alternately, the Shape can be designated directly, without using its label, use:
dba69de2 579~~~~~
580myColors->SetColor ( aShape, Col, ctype );
72b7576f 581// Creating and Adding a Color, explicitly
582Quantity_Color Col (red,green,blue);
dba69de2 583TDF_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.
72b7576f 586
587To set a Color, identified by its Label and already recorded, to a Shape, use:
dba69de2 588~~~~~
589XCAFDoc_ColorType ctype ..; // see above
590if ( myColors->SetColors ( aLabel, ColLabel, ctype) ) {.. it is done .. }
591~~~~~
592In this example, *aLabel* can be replaced by *aShape* directly.
593
594@subsubsection occt_xde_2_6_3 Queries on Colors
72b7576f 595Various queries can be performed on colors. However, only specific queries are included in this section, not general queries using names.
596
597To determine if a Color is attached to a Shape, for a given color type (ctype), use:
dba69de2 598~~~~~
599if ( myColors->IsSet (aLabel , ctype)) {
600 // yes, there is one ..
72b7576f 601}
dba69de2 602~~~~~
603In this example, *aLabel* can be replaced by *aShape* directly.
72b7576f 604
605To get the Color attached to a Shape (for any color type), use:
dba69de2 606~~~~~
72b7576f 607Quantity_Color col;
dba69de2 608// will receive the recorded value (if there is some)
609if ( !myColors->GetColor(aLabel, col) ) {
72b7576f 610// sorry, no color ..
dba69de2 611}
612~~~~~
613
614Color name can also be queried from *col.StringName* or *col.Name*.
615In this example, *aLabel* can be replaced by *aShape* directly.
72b7576f 616
617To get the Color attached to a Shape, with a specific color type, use:
dba69de2 618~~~~~
72b7576f 619XCAFDoc_ColorType ctype ..;
72b7576f 620Quantity_Color col;
621// will receive the recorded value (if there is some)
dba69de2 622if ( !myColors->GetColor(aLabel, ctype, col) ) {
72b7576f 623// sorry, no color ..
624}
dba69de2 625~~~~~
626
72b7576f 627
628To get all the Colors recorded in the Document, use:
dba69de2 629
630~~~~~
72b7576f 631Quantity_Color col; // to receive the values
632TDF_LabelSequence ColLabels;
dba69de2 633myColors->GetColors(ColLabels);
72b7576f 634Standard_Integer i, nbc = ColLabels.Length();
635for (i = 1; i = nbc; i ++) {
dba69de2 636 aLabel = Labels.Value(i);
637 if ( !myColors->GetColor(aLabel, col) ) continue;
638 // col receives the color n0 i ..
72b7576f 639}
dba69de2 640~~~~~
72b7576f 641
642To find a Color from its Value, use:
dba69de2 643~~~~~
72b7576f 644Quantity_Color Col (red,green,blue);
645TDF_Label ColLabel = myColors-FindColor (Col);
646if ( !ColLabel.IsNull() ) { .. found .. }
dba69de2 647~~~~~
648
4ee1bdf4 649@subsubsection occt_xde_2_6_4 Editing Colors
72b7576f 650Besides adding colors, the following attribute edits can be made:
651
652To unset a Color on a Shape, use:
dba69de2 653~~~~~
72b7576f 654XCAFDoc_ColorType ctype ...;
655// desired type (XCAFDoc_ColorGen for all )
dba69de2 656myColors->UnSetColor (aLabel,ctype);
657~~~~~
72b7576f 658To remove a Color and all the references to it (so that the related shapes will become colorless), use:
dba69de2 659~~~~~
660myColors->RemoveColor(ColLabel);
661~~~~~
e2b55410 662
cf0786da 663@subsection occt_xde_2_7 Geometric Dimensions & Tolerances (GD\&T)
a8a3b37c 664
cf0786da 665XDE 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.
a8a3b37c 666
cf0786da 667In 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*:
a8a3b37c 668 * *XCAFDoc_Dimension* - for dimensions;
669 * *XCAFDoc_GeomTolerance* - for geometric tolerances;
670 * *XCAFDoc_Datum* - for geometric tolerance Datums.
cf0786da 671A GD\&T type is identified by the attributes listed above, i.e. *XCAFDoc_DimTolTool* methods working with particular entity types check
a8a3b37c 672for presence of the corresponding attributes in passed labels. One can use methods of *XCAFDoc_DimTolTool* beginning with 'Is' for this purpose.
673
cf0786da 674GD\&T entities are stored in a child of the starting document label 0.1.4.
675Each GD\&T entity then corresponds to the dedicated label, the property itself is one of access classes:
a8a3b37c 676 * *XCAFDimTolObject_DimensionObject* - for dimensions;
677 * *XCAFDimTolObject_GeomToleranceObject* - for geometric tolerances;
678 * *XCAFDimTolObject_DatumObject* - for geometric tolerance Datums.
679
14deaf42 680GD\&Ts and Shapes are related by Graph Nodes.
a8a3b37c 681
682These definitions are common to various exchange formats, at least for STEP.
683
684@subsubsection occt_xde_2_7_1 Initialization
cf0786da 685To query, edit, or initialize a Document to handle GD\&Ts of XCAF, use:
a8a3b37c 686~~~~~
687Handle(XCAFDoc_DimTolTool) myDimTolTool =
688XCAFDoc_DocumentTool::DimTolTool(Doc->Main());
689~~~~~
cf0786da 690This 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.
a8a3b37c 691
cf0786da 692@subsubsection occt_xde_2_7_2 Adding a GD\&T
693*XCAFDoc_DimTolTool* provides methods to create GD\&T 'empty' entities:
a8a3b37c 694 * *AddDimension* - for a new dimension;
695 * *AddGeomTolerance* - for a new geometric tolerance;
696 * *AddDatum* - for a new geometric tolerance datum.
697
cf0786da 698All methods create a sub-label for the corresponding GD\&T entity of the tool master label and attach an attribute specific for the
a8a3b37c 699created entity.
700
701Here is an example of adding a new dimension:
702~~~~~
703TDF_Label aDimLabel = myDimTolTool->AddDimension();
704if (!aDimLabel.IsNull())
705{
706 // error processing
707}
708~~~~~
cf0786da 709A similar approach can be used for other GD\&T types.
a8a3b37c 710
cf0786da 711@subsubsection occt_xde_2_7_3 Editing a GD\&T
712A newly added GD\&T entity is empty. To set its data a corresponding access object should be used as it is demonstrated
14deaf42 713below, where the dimension becomes a linear distance between two points.
a8a3b37c 714~~~~~
715Handle(XCAFDoc_Dimension) aDimAttr;
716aDimLabel.FindAttribute(XCAFDoc_Dimension::GetID(), aDimAttr);
717if (!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~~~~~
cf0786da 729A similar approach can be used for other GD\&T types.
a8a3b37c 730
cf0786da 731@subsubsection occt_xde_2_7_4 Linking GD\&Ts
732To link a GD\&T entity with other OCAF labels (e.g. representing shapes) one should use the following methods:
a8a3b37c 733 * *SetDimension* - for dimensions;
734 * *SetGeomTolerance* - for geometric tolerances;
14deaf42 735 * *SetDatum* - for geometric tolerance datums.
a8a3b37c 736
737These methods can take a single label or a sequence of labels. All previous links will be removed.
738
739The example below demonstrates linking of a dimension to sequences of shape labels:
740~~~~~
741TDF_LabelSequence aShapes1, aShapes2;
742aShapes1.Append(aShape11);
743//...
744aShapes2.Append(aShape21);
745//...
746aDGTTool->SetDimension(aShapes1, aShapes2, aDimLabel);
747~~~~~
024d6f77 748
a8a3b37c 749In addition, a special method *SetDatumToGeomTol* should be used to link a datum with a geometric tolerance.
750
cf0786da 751@subsubsection occt_xde_2_7_5 Finding GD\&Ts and reference shapes
a8a3b37c 752
cf0786da 753*XCAFDimTolObjects_Tool* class provides basic capabilities for searching GD\&Ts linked to shapes.
14deaf42 754The tool provides sequences of dimensions, geometric tolerances and datums linked with a shape. A series of related datums is also returned for geometric tolerances.
a8a3b37c 755
cf0786da 756To get reference shapes for a GD\&T entity one can use *GetRefShapeLabel* from *XCAFDoc_DimTolTool*.
a8a3b37c 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
cf0786da 761Every GD\&T entity in XDE is represented as a label with attached attribute identifying entity type. All specific data is
a8a3b37c 762stored in sub-labels in standard OCAF attributes, such as *TDataStd_Integer*, *TDataStd_IntegerArray*, *TDataStd_RealArray* and so on.
763Sub-label tags are reserved for internal use and cannot be used for storing custom data. The following tag ranges are reserved for
cf0786da 764GD\&T entities:
a8a3b37c 765 * 1 - 17 - for dimensions;
766 * 1 - 17 - for geometric tolerances;
767 * 1 - 19 - for datums.
768Custom data can be stored in labels with tags beyond the ranges listed above.
769
770@subsection occt_xde_2_8 Clipping planes
771
772In 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
774To query, edit, or initialize a Document to handle clipping planes of XCAF, use:
775~~~~~
776Handle(XCAFDoc_ClippingPlaneTool) myClipPlaneTool =
777XCAFDoc_DocumentTool::ClippingPlaneTool(Doc->Main());
778~~~~~
779This call can be used at any time. When it is used for the first time, a relevant structure is added to the document.
024d6f77 780
a8a3b37c 781To add a clipping plane use one of overloaded methods *AddClippingPlane*, e.g.:
782~~~~~
783gp_Pln aPln = ...
784Standard_Boolean aCapping = ...
785TDF_Label aClipPlnLbl = myClipPlaneTool->AddClippingPlane(aPln, "Name of plane", aCapping);
786if (aClipPlnLbl.IsNull())
787{
788 // error processing
789}
790~~~~~
791
792To remove a plane use *RemoveClippingPlane* method, e.g.:
793~~~~~
794if (!myClipPlaneTool->RemoveClippingPlane(aClipPlnLbl))
795{
796 // not removed
797}
798~~~~~
799The plane will not be removed if it is referenced in at least one view.
800
14deaf42 801To change the clipping plane and its name use *UpdateClippingPlane* method, e.g.:
a8a3b37c 802~~~~~
803gp_Pln aPln = ...
804myClipPlaneTool->UpdateClippingPlane(aClipPlnLbl, aPln, "New name of plane");
805~~~~~
806
807Capping property can be changed using *SetCapping* method, e.g.:
808~~~~~
809Standard_Boolean aCapping = ...
810myClipPlaneTool->SetCapping(aClipPlnLbl, aCapping);
811~~~~~
812
14deaf42 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.:
a8a3b37c 814~~~~~
815TDF_LabelSequence aClipPlaneLbls;
816myClipPlaneTool->GetClippingPlanes(aClipPlaneLbls);
817...
818for (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
14deaf42 837In 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.
a8a3b37c 838
839To query, edit, or initialize a Document to handle views of XCAF, use:
840~~~~~
841Handle(XCAFDoc_ViewTool) myViewTool =
842XCAFDoc_DocumentTool::ViewTool(Doc->Main());
843~~~~~
844This call can be used at any time. When it is used for the first time, a relevant structure is added to the document.
845
846To add a view use *AddView* method and an access *XCAFView_Object* object to set camera parameters, e.g.:
847~~~~~
848TDF_Label aViewLbl = myViewTool->AddView();
849if (aViewLbl.IsNull())
850{
851 // error processing
852}
853Handle(XCAFDoc_View) aViewAttr;
854aViewLbl.FindAttribute(XCAFDoc_View::GetID(), aViewAttr);
855if (!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
cf0786da 867To set shapes, clipping planes, GD\&Ts and notes selected for the view use one of overloaded *SetView* methods of *XCAFDoc_ViewTool*.
a8a3b37c 868To set only clipping planes one should use *SetClippingPlanes* method.
869~~~~~
870TDF_LabelSequence aShapes; ...
871TDF_LabelSequence aGDTs; ...
872myViewTool->SetView(aShapes, aGDTs, aViewLbl);
873TDF_LabelSequence aClippingPlanes; ...
874myViewTool->SetClippingPlanes(aClippingPlanes, aViewLbl);
875~~~~~
876
877To remove a view use *RemoveView* method.
878
879To get all view labels and check if a label belongs to the View table use:
880~~~~~
881TDF_LabelSequence aViewLbls;
882myViewTool->GetViewLabels(aViewLbls);
883...
884for (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
cf0786da 894To get shapes, clipping planes, GD\&Ts or notes associated with a particular view use the following methods:
a8a3b37c 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
cf0786da 901And vice versa, to get views that display a particular clipping plane, GD\&T or note use the following methods:
14deaf42 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.
a8a3b37c 907
908@subsection occt_xde_2_10 Custom notes
909
cf0786da 910In an XDE document, custom notes are managed by the class *XCAFDoc_NotesTool*.
911It works basing on the same principles as ShapeTool works with Shapes.
912This tool can be provided on the Main Label or on any sub-label.
913The Property itself is defined as sub-class of *XCAFDoc_Note* abstract class, which is a sub-class of *TDF_Attribute* one.
a8a3b37c 914
915Custom 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.
024d6f77 916Notes 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
a8a3b37c 920@subsubsection occt_xde_2_10_1 Initialization
024d6f77 921
922To query, edit, or initialize a Document to handle custom notes of XCAF, use:
923~~~~~
924Handle(XCAFDoc_NotesTool) myNotes =
925XCAFDoc_DocumentTool::NotesTool(Doc->Main ());
926~~~~~
a8a3b37c 927This 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.
024d6f77 928
a8a3b37c 929@subsubsection occt_xde_2_10_2 Creating Notes
024d6f77 930
931Before annotating a Document item a note must be created using one of the following methods of *XCAFDoc_NotesTool* class:
a8a3b37c 932- *CreateComment* : creates a note with a textual comment;
933- *CreateBinData* : creates a note with arbitrary binary data, e.g. contents of a file.
024d6f77 934
935Both methods return an instance of *XCAFDoc_Note* class.
936~~~~~
937Handle(XCAFDoc_NotesTool) myNotes = ...
938Handle(XCAFDoc_Note) myNote = myNotes->CreateComment("User", "Timestamp", "Hello, World!");
939~~~~~
940This code adds a child label to label 0.1.9.1 with *XCAFDoc_NoteComment* attribute.
941
a8a3b37c 942@subsubsection occt_xde_2_10_3 Editing a Note
024d6f77 943An instance of *XCAFDoc_Note* class can be used for note editing.
944One may change common note data.
945~~~~~
946myNote->Set("New User", "New Timestamp");
947~~~~~
a8a3b37c 948To change specific data one needs to down cast *myNote* handle to the appropriate sub-class:
024d6f77 949~~~~~
950Handle(XCAFDoc_NoteComment) myCommentNote = Handle(XCAFDoc_NoteComment)::DownCast(myNote);
951if (!myCommentNote.IsNull()) {
952 myCommentNote->Set("New comment");
953}
954~~~~~
8c7fab9b 955In order to edit auxiliary note data such as text and attachment position, plane for rendering and tesselated presentation,
956one 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 tesselated presentation
962
963After getting, the transfer object can be edited and set back to the note:
964~~~~~
965Handle(XCAFNoteObjects_NoteObject) aNoteObj = myNote->GetObject();
966if (!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~~~~~
024d6f77 975
a8a3b37c 976@subsubsection occt_xde_2_10_4 Adding Notes
024d6f77 977
978Once a note has been created it can be bound to a Document item using the following *XCAFDoc_NotesTool* methods:
a8a3b37c 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.
024d6f77 982
983All methods return a pointer to *XCAFDoc_AssemblyItemRef* attribute identifying the annotated item.
984~~~~~
985Handle(XCAFDoc_NotesTool) myNotes = ...
986Handle(XCAFDoc_Note) myNote = ...
987TDF_Label theLabel; ...
988Handle(XCAFDoc_AssemblyItemRef) myRef = myNotes->AddNote(myNote->Label(), theLabel);
989Standard_GUID theAttrGUID; ...
990Handle(XCAFDoc_AssemblyItemRef) myRefAttr = myNotes->AddNoteToAttr(myNote->Label(), theAttrGUID);
991Standard_Integer theSubshape = 1;
992Handle(XCAFDoc_AssemblyItemRef) myRefSubshape = myNotes->AddNoteToSubshape(myNote->Label(), theSubshape);
993~~~~~
a8a3b37c 994This 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.
024d6f77 995
a8a3b37c 996@subsubsection occt_xde_2_10_5 Finding Notes
024d6f77 997
998To find annotation labels under label 0.1.9.2 use the following *XCAFDoc_NotesTool* methods:
a8a3b37c 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.
024d6f77 1002
1003~~~~~
1004Handle(XCAFDoc_NotesTool) myNotes = ...
1005TDF_Label theLabel; ...
1006TDF_Label myLabel = myNotes->FindAnnotatedItem(theLabel);
1007Standard_GUID theAttrGUID; ...
1008TDF_Label myLabelAttr = myNotes->FindAnnotatedItemAttr(theLabel, theAttrGUID);
1009Standard_Integer theSubshape = 1;
1010TDF_Label myLabelSubshape = myNotes->FindAnnotatedItemSubshape(theLabel, theSubshape);
1011~~~~~
1012Null label will be returned if there is no corresponding annotation.
1013
1014To get all notes of the Document item use the following *XCAFDoc_NotesTool* methods:
a8a3b37c 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.
024d6f77 1018
1019All these methods return the number of notes.
1020~~~~~
1021Handle(XCAFDoc_NotesTool) myNotes = ...
1022TDF_Label theLabel; ...
1023TDF_LabelSequence theNotes;
1024myNotes->GetNotes(theLabel, theNotes);
1025Standard_GUID theAttrGUID; ...
1026TDF_LabelSequence theNotesAttr;
1027myNotes->GetAttrNotes(theLabel, theAttrGUID, theNotesAttr);
1028Standard_Integer theSubshape = 1;
1029TDF_LabelSequence theNotesSubshape;
1030myNotes->GetAttrSubshape(theLabel, theSubshape, theNotesSubshape);
1031~~~~~
1032
a8a3b37c 1033@subsubsection occt_xde_2_10_6 Removing Notes
024d6f77 1034
1035To remove a note use one of the following *XCAFDoc_NotesTool* methods:
a8a3b37c 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.
024d6f77 1039
1040~~~~~
1041Handle(XCAFDoc_Note) myNote = ...
1042TDF_Label theLabel; ...
1043myNotes->RemoveNote(myNote->Label(), theLabel);
1044Standard_GUID theAttrGUID; ...
1045myRefAttr = myNotes->RemoveAttrNote(myNote->Label(), theAttrGUID);
1046Standard_Integer theSubshape = 1;
1047myNotes->RemoveSubshapeNote(myNote->Label(), theSubshape);
1048~~~~~
1049A note will not be deleted automatically.
a8a3b37c 1050Counterpart methods to remove all notes are available, too.
024d6f77 1051
a8a3b37c 1052@subsubsection occt_xde_2_10_7 Deleting Notes
024d6f77 1053
1054To delete note(s) use the following *XCAFDoc_NotesTool* methods:
a8a3b37c 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.
024d6f77 1059
a8a3b37c 1060All these methods except for the last one break all links with Document items as well.
dba69de2 1061
a8a3b37c 1062@subsection occt_xde_2_11 Reading and Writing STEP or IGES
72b7576f 1063Note 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.
1064The same can be said for Viewing: presentations can be defined from Shapes and Colors.
dba69de2 1065
72b7576f 1066There 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.
cf0786da 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.
72b7576f 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.
dba69de2 1071
1072The packages to manage this are *IGESCAFControl* for IGES, and *STEPCAFControl* for STEP.
a8a3b37c 1073
1074@subsubsection occt_xde_2_11_1 Reading a STEP file
72b7576f 1075To read a STEP file by itself, use:
dba69de2 1076
1077~~~~~
72b7576f 1078STEPCAFControl_Reader reader;
1079IFSelect_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 ...
1082Handle(TDocStd_Document) doc...
1083// the document referred to is already defined and
1084// properly initialized.
1085// Now, the transfer itself
1086if ( !reader.Transfer ( doc ) ) {
dba69de2 1087 cout;Cannot read any relevant data from the STEP file;endl;
1088 // abandon ..
72b7576f 1089}
1090// Here, the Document has been filled from a STEP file,
1091// it is ready to use
dba69de2 1092~~~~~
1093
72b7576f 1094In addition, the reader provides methods that are applicable to document transfers and for directly querying of the data produced.
a8a3b37c 1095@subsubsection occt_xde_2_11_2 Writing a STEP file
72b7576f 1096To write a STEP file by itself, use:
dba69de2 1097
1098~~~~~
72b7576f 1099STEPControl_StepModelType mode =
1100STEPControl_AsIs;
1101// Asis is the recommended value, others are available
1102// Firstly, perform the conversion to STEP entities
1103STEPCAFControl_Writer writer;
1104//(the user can work with an already prepared WorkSession or create a //new one)
1105Standard_Boolean scratch = Standard_False;
1106STEPCAFControl_Writer writer ( WS, scratch );
1107// Translating document (conversion) to STEP
1108if ( ! writer.Transfer ( Doc, mode ) ) {
dba69de2 1109 cout;The document cannot be translated or gives no result;endl;
1110 // abandon ..
72b7576f 1111}
1112// Writing the File
1113IFSelect_ReturnStatus stat = writer.Write(file-name);
dba69de2 1114~~~~~
1115
a8a3b37c 1116@subsubsection occt_xde_2_11_3 Reading an IGES File
72b7576f 1117Use the same procedure as for a STEP file but with IGESCAFControl instead of STEPCAFControl.
a8a3b37c 1118@subsubsection occt_xde_2_11_4 Writing an IGES File
dba69de2 1119Use the same procedure as for a STEP file but with IGESCAFControl instead of STEPCAFControl.
1120
a8a3b37c 1121@subsection occt_xde_2_12 Using an XDE Document
72b7576f 1122There are several ways of exploiting XDE data from an application, you can:
dba69de2 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.
a8a3b37c 1127
1128@subsubsection occt_xde_2_12_1 XDE Data inside an Application Document
72b7576f 1129To 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.
dba69de2 1130
72b7576f 1131In addition, as XDE data is defined and managed in a modular way, you can consider exclusively Assembly Structure, only Colors, and so on.
dba69de2 1132
72b7576f 1133As 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.
dba69de2 1136
72b7576f 1137As 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.
72b7576f 1138
dba69de2 1139In 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.
d6b4d3d0 1140