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