0026707: Remove references to "opencascade.org" in documentation
[occt.git] / dox / user_guides / step / step.md
ba06f8bb 1STEP processor {#occt_user_guides__step}
72b7576f 2========================
e5bd0d98 4@tableofcontents
e2b55410 6@section occt_step_1 Introduction
72b7576f 7
e2b55410 8STEP is more and more widely used to exchange data between various software, involved in CAD, PDM, Analysis, etc... STEP is far more than an "exchange standard" : it provides a technology and a set of methodologies to describe the data to exchange in a modular and upgradeable way. Regarding OCCT, this mostly applies to CAD data but it is not a limitation, other kinds of data for specific applications can be addressed too.
10@figure{/user_guides/step/images/step_image002.png, "Image imported from STEP"}
12Open Cascade allows its users to employ STEP in the following domains:
13* Exchange of data for technical applications, following the state-of-the-art definitions and rules;
14* Extension of case coverage, according to specific needs or to the evolution of general business uses;
15* Expertise in data architecture of an application, to get experience from STEP definitions and make easier the mapping to them, for a better interoperability with outer world.
17This manual is intended to provide technical documentation on the Open CASCADE Technology (**OCCT**) STEP processor and to help Open CASCADE Technology users with the use of the STEP processor (to read and write STEP files).
dba69de2 18
19Only geometrical, topological STEP entities (shapes) and assembly structures are translated by the basic translator described in sections 2 to 6. Data that cannot be translated on this level are also loaded from a STEP file and can be translated later. XDE STEP translator (see section 7 <a href="#occt_step_7">Reading from and writing to XDE</a>) translates names, colors, layers, validation properties and other data associated with shapes and assemblies into XDE document.
72b7576f 21File translation is performed in the programming mode, via C++ calls.
72b7576f 22
e2b55410 23@ref occt_user_guides__shape_healing "Shape Healing" toolkit provides tools to heal various problems, which may be encountered in translated shapes, and to make them valid in Open CASCADE. The Shape Healing is smoothly connected to STEP translator using the same API, only the names of API packages change.
dba69de2 25For testing the STEP component in DRAW Test Harness, a set of commands for reading and writing STEP files and analysis of relevant data are provided by the *TKXSDRAW* plugin.
e2ba9cb1 27See also our <a href="http://www.opencascade.com/content/tutorial-learning">E-learning & Training</a> offerings.
e2b55410 28
29@subsection occt_step_1_1 STEP Exchanges in Open Cascade technology
31Beyond the upper level API, which is fitted for an easy end-use, the STEP exchange functions enter in the general frame of Exchanges in Open Cascade, adapted for STEP:
33* Specific packages for Data definition and checking;
34* Physical Access supported by Drivers (Part 21 file access is embedded);
35* Conversion to/from Open Cascade or applicative data supported by drivers (OCC-BREP and XDE ard basically provided);
36* Tools for analysis, filtering, etc... including DRAW commands.
38These modules share common architecture and capabilities with other exchange modules of Open Cascade, like Shape Healing. Also, built-in Viewer and Converter (as Plugin for Netscape, Internet Explorer ..), are based on the same technology.
40In addition, Open Cascade provides tools to process models described using STEP: to reflect EXPRESS descriptions, to read, write and check data, to analyze the whole models ... Their key features are:
42* Modularity by sets of data types, which can be hierarchized to reflect the original modularity describing the resources and application protocols;
43* Implementation as CDL/C++ classes, providing comprehensive access to their members;
44* Early binding is basically used, providing good performance, easy installation and use as well as the capability to support non-compiled descriptions.
46This provides a natural way to deal with non-supported protocols when they share common definitions, as for geometry, which can then be exploited. The common frame, as the already supported data types, give a good foundation to go towards new uses of STEP, either on data definition (protocols from ISO or from industrial consortia) or on mapping with applicative data.
49@subsection occt_step_1_2 STEP Interface
51The STEP interface reads STEP files produced in accordance with STEP Application Protocol 214 (Conformance Class 2 both CD and DIS versions of schema) and translates them to Open CASCADE Technology models. STEP Application Protocol 203 is also supported.
53The STEP interface also translates OCCT models to STEP files. STEP files that are produced by this interface conform to STEP AP 203 or AP 214 (Conformance Class 2, either CD or DIS version of the schema) depending on the user's option.
55Basic interface reads and writes geometrical, topological STEP data and assembly structures.
57The interface is able to translate one entity, a group of entities or a whole file.
59Other kinds of data such as colors, validation properties, layers, names and the structure of assemblies can be read or written with the help of XDE tools - <i> STEPCAFControl_Reader</i> and <i> STEPCAFControl_Writer</i>.
61To choose a translation mode when exporting to a STEP format, use <i> STEPControl_STEPModelType</i>.
63There is a set of parameters that concern the translation and can be set before the beginning of the translation.
65Please, note:
66* a STEP model is a STEP file that has been loaded into memory;
67* all references to shapes indicate OCCT shapes unless otherwise explicitly stated;
68* a root entity is the highest level entity of any given type, i.e. an entity that is not referenced by any other one.
dba69de2 70@section occt_step_2 Reading STEP
71@subsection occt_step_2_1 Procedure
72b7576f 72You can translate a STEP file into an OCCT shape in the following steps:
731. load the file,
742. check file consistency,
753. set the translation parameters,
764. perform the translation,
775. fetch the results.
dba69de2 78@subsection occt_step_2_2 Domain covered
79@subsubsection occt_step_2_2_1 Assemblies
668c2575 80The **ProSTEP Round Table Agreement Log** (version July 1998), item 21, defines two alternatives for the implementation of assembly structure representations: using *mapped_item entities* and using *representation_relationship_with_transformation* entities. Both these alternative representations are recognized and processed at reading. On writing, the second alternative is always employed.
dba69de2 81
72b7576f 82Handling of assemblies is implemented in two separate levels: firstly STEP assembly structures are translated into OCCT shapes, and secondly the OCCT shape representing the assembly is converted into any data structure intended for representing assemblies (for example, OCAF).
dba69de2 83
668c2575 84The first part of this document describes the basic STEP translator implementing translation of the first level, i.e. translation to OCCT Shapes. On this level, the acyclic graph representing the assembly structure in a STEP file is mapped into the structure of nested *TopoDS_Compounds* in Open CASCADE Technology. The (sub)assemblies become (sub)compounds containing shapes which are the results of translating components of that (sub)assembly. The sharing of components of assemblies is preserved as Open CASCADE Technology sharing of subshapes in compounds.
dba69de2 85
72b7576f 86The attributive information attached to assembly components in a STEP file (such as names and descriptions of products, colors, layers etc.) can be translatd after the translation of the shape itself by parsing the STEP model (loaded in memory). Several tools from the package STEPConstruct provide functionalities to read styles (colors), validation properties, product information etc.
dba69de2 87Implementation of the second level of translation (conversion to XDE data structure) is provided by XDE STEP translator.
89@subsubsection occt_step_2_2_2 Shape representations
668c2575 90Length units, plane angle units and the uncertainty value are taken from *shape_representation* entities. This data is used in the translation process.
dba69de2 91
72b7576f 92The types of STEP representation entities that are recognized are:
93 * advanced_brep_shape_representation
94 * faceted_brep_shape_representation
95 * manifold_surface_shape_representation
96 * geometrically_bounded_wireframe_shape_representation
97 * geometrically_bounded_surface_shape_representation
98 * hybrid representations (shape_representation containing models of different type)
dba69de2 99
100@subsubsection occt_step_2_2_3 Topological entities
72b7576f 101The types of STEP topological entities that can be translated are:
102 * vertices
103 * edges
104 * loops
105 * faces
106 * shells
107 * solids
dba69de2 108For further information see <a href="#occt_step_2_4">Mapping STEP entities to Open CASCADE Technology shapes</a>.
110@subsubsection occt_step_2_2_4 Geometrical entities
72b7576f 111The types of STEP geometrical entities that can be translated are:
112 * points
113 * vectors
114 * directions
115 * curves
116 * surfaces
dba69de2 117
72b7576f 118For further information see 2.4 Mapping STEP entities to Open CASCADE Technology shapes.
dba69de2 119
120@subsection occt_step_2_3 Description of the process
121@subsubsection occt_step_2_3_1 Loading the STEP file
72b7576f 123Before performing any other operation you have to load the file with:
dba69de2 124~~~~~
72b7576f 125STEPControl_Reader reader;
126IFSelect_ReturnStatus stat = reader.ReadFile(;filename.stp;);
dba69de2 127~~~~~
72b7576f 128Loading the file only memorizes the data, it does not translate it.
dba69de2 129
130@subsubsection occt_step_2_3_2 Checking the STEP file
72b7576f 131This step is not obligatory. Check the loaded file with:
dba69de2 132~~~~~
72b7576f 133reader.PrintCheckLoad(failsonly,mode);
dba69de2 134~~~~~
72b7576f 135Error messages are displayed if there are invalid or incomplete STEP entities, giving you the information on the cause of error.
dba69de2 136
137If *failsonly* is true only fail messages are displayed. All messages are displayed if *failsonly* is false. Your analysis of the file can be either message-oriented or entity-oriented. Choose your preference with:
72b7576f 139IFSelect_PrintCount mode = IFSelect_xxx
dba69de2 140~~~~~
72b7576f 141Where xxx can be one of the following:
dba69de2 142* *ItemsByEntity* - gives a sequential list of all messages per STEP entity,
143* *CountByItem* - gives the number of STEP entities with their types per message
144* *ListByItem* - gives the number of STEP entities with their types and rank numbers per message
146@subsubsection occt_step_2_3_3 Setting the translation parameters
72b7576f 147The following parameters can be used to translate a STEP file into an OCCT shape.
dba69de2 148
72b7576f 149If you give a value that is not within the range of possible values it will simply be ignored.
dba69de2 150
72b7576f 151<h4>read.precision.mode</h4>
152Defines which precision value will be used during translation (see section 2.5 below for details on precision and tolerances).
dba69de2 153* *File (0)* - the precision value is set to length_measure in uncertainty_measure_with_unit from STEP file.
154* *User (1)* - the precision value is that of the *read.precision.val* parameter.
72b7576f 156Read this parameter with:
dba69de2 157
159Standard_Integer ic = Interface_Static::IVal("read.precision.mode");
72b7576f 161Modify this parameter with:
dba69de2 162~~~~~
72b7576f 164.. error ..
dba69de2 165~~~~~
166Default value is File (0).
72b7576f 168<h4>read.precision.val:</h4>
dba69de2 169User defined precision value. This parameter gives the precision for shape construction when the read.precision.mode parameter value is 1. By default it is 0.0001, but can be any real positive (non null) value.
72b7576f 171This value is a basic value of tolerance in the processor. The value is in millimeters, independently of the length unit defined in the STEP file.
dba69de2 172
72b7576f 173Read this parameter with:
dba69de2 174~~~~~
175Standard_Real rp = Interface_Static::RVal("read.precision.val");
72b7576f 177Modify this parameter with:
dba69de2 178~~~~~
72b7576f 180.. error ..
dba69de2 181~~~~~
182By default this value is 0.0001.
72b7576f 184The value given to this parameter is a basic value for ShapeHealing algorithms and the processor. It does its best to reach it. Under certain circumstances, the value you give may not be attached to all of the entities concerned at the end of processing. STEP-to-OpenCASCADE translation does not improve the quality of the geometry in the original STEP file. This means that the value you enter may be impossible to attach to all shapes with the given quality of the geometry in the STEP file.
dba69de2 185
72b7576f 186<h4>read.maxprecision.val</h4>
dba69de2 187Defines the maximum allowed tolerance (in mm) of the shape. It should be not less than the basic value of tolerance set in the processor (either the uncertainty from the file or *read.precision.val*). Actually, the maximum between *read.maxprecision.val* and the basis tolerance is used to define the maximum allowed tolerance.
72b7576f 189Read this parameter with:
dba69de2 190~~~~~
191Standard_Real rp = Interface_Static::RVal("read.maxprecision.val");
72b7576f 193Modify this parameter with:
dba69de2 194~~~~~
72b7576f 196.. error ..
dba69de2 197~~~~~
72b7576f 199Default value is 1.
200Note that maximum tolerance even explicitly defined by the user may be insufficient to ensure the validity of the shape (if real geometry is of bad quality). Therefore the user is provided with an additional parameter, which allows him to choose: either he prefers to ensure the shape validity or he rigidly sets the value of maximum tolerance. In the first case there is a possibility that the tolerance will not have any upper limit, in the second case the shape may be invalid.
dba69de2 201
72b7576f 202<h4>read.maxprecision.mode:</h4>
203Defines the mode of applying the maximum allowed tolerance. Its possible values are:
dba69de2 204* 0 (Preferred) - maximum tolerance is used as a limit but sometimes it can be exceeded (currently, only for deviation of a 3D curve and pcurves of an edge, and vertices of such edge) to ensure the shape validity,
205* 1 (Forced) - maximum tolerance is used as a rigid limit, i.e. no tolerance can exceed it and if it is the case, the tolerance is trimmed by the maximum tolerance.
72b7576f 207Read this parameter with:
dba69de2 208~~~~~
209Standard_Integer ic = Interface_Static::IVal("read.maxprecision.mode");
72b7576f 211Modify this parameter with:
dba69de2 212~~~~~
72b7576f 214.. error ..
dba69de2 215~~~~~
216Default value is 0 ("Preferred").
72b7576f 218<h4>read.stdsameparameter.mode</h4>
dba69de2 219defines the use of *BRepLib::SameParameter*. Its possible values are:
221* 0 (Off) - *BRepLib::SameParameter* is not called,
222* 1 (On) - *BRepLib::SameParameter* is called.
223The functionality of *BRepLib::SameParameter* is used through *ShapeFix_Edge::SameParameter*. It ensures that the resulting edge will have the lowest tolerance taking pcurves either unmodified from the STEP file or modified by *BRepLib::SameParameter*.
72b7576f 225Read this parameter with:
dba69de2 226~~~~~
227Standard_Integer mv = Interface_Static::IVal("read.stdsameparameter.mode");
72b7576f 229Modify this parameter with:
dba69de2 230~~~~~
231if (!Interface_Static::SetIVal ("read.stdsameparameter.mode",1))
72b7576f 232.. error ..;
dba69de2 233~~~~~
234Default value is 0 (;Off;).
72b7576f 236<h4>read.surfacecurve.mode:</h4>
237a preference for the computation of curves in an entity which has both 2D and 3D representation.
dba69de2 238Each *TopoDS_Edge* in *TopoDS_Face* must have a 3D and 2D curve that references the surface.
72b7576f 240If both 2D and 3D representation of the entity are present, the computation of these curves depends on the following values of parameter:
dba69de2 241* *Default (0)* : no preference, both curves are taken (default value),
242* *3DUse_Preferred (3)* : 3D curves are used to rebuild 2D ones.
72b7576f 244Read this parameter with:
dba69de2 245~~~~~
246Standard_Integer rp = Interface_Static::IVal("read.surfacecurve.mode");
72b7576f 248Modify this parameter with:
dba69de2 249~~~~~
72b7576f 251.. error ..
dba69de2 252~~~~~
72b7576f 253Default value is (0).
dba69de2 254
72b7576f 255<h4>read.encoderegularity.angle</h4>
dba69de2 256
257This parameter is used for call to *BRepLib::EncodeRegularity()* function which is called for the shape read from an IGES or a STEP file at the end of translation process. This function sets the regularity flag of the edge in the shell when this edge is shared by two faces. This flag shows the continuity these two faces are connected with at that edge.
72b7576f 258Read this parameter with:
dba69de2 259~~~~~
260Standard_Real era = Interface_Static::RVal("read.encoderegularity.angle");
72b7576f 262Modify this parameter with:
dba69de2 263~~~~~
264if (!Interface_Static::SetRVal ("read.encoderegularity.angle",0.1))
72b7576f 265.. error ..;
dba69de2 266~~~~~
72b7576f 267Default value is 0.01.
dba69de2 268
72b7576f 269<h4>step.angleunit.mode</h4>
270This parameter is obsolete (it was required in the past for STEP files with a badly encoded angle unit). It indicates what angle units should be used when a STEP file is read: the units from file (default), or forced RADIANS or DEGREES.
dba69de2 271
72b7576f 272Default value is File
dba69de2 273
274<h4>read.step.resource.name and read.step.sequence</h4>
72b7576f 276These two parameters define the name of the resource file and the name of the sequence of operators (defined in that file) for Shape Processing, which is automatically performed by the STEP translator. Shape Processing is a user-configurable step, which is performed after translation and consists in applying a set of operators to a resulting shape. This is a very powerful tool allowing customizing the shape and adapting it to the needs of a receiving application. By default the sequence consists of a single operator ShapeFix - that is how Shape Healing is called from the STEP translator.
dba69de2 277
278Please find an example of the resource file for STEP (which defines parameters corresponding to the sequence applied by default, i.e. if the resource file is not found) in the Open CASCADE Technology installation, by the path <i>%CASROOT%/src/XSTEPResource/STEP</i>.
280In order for the STEP translator to use that file, you have to define the *CSF_STEPDefaults* environment variable, which should point to the directory where the resource file resides. Note that if you change parameter *read.step.resource.name*, you will change the name of the resource file and the environment variable correspondingly.
282Default values:
283* read.step.resource.name - STEP,
284* read.step.sequence - FromSTEP.
72b7576f 286<h4>read.scale.unit</h4>
dba69de2 287This parameter is obsolete (the parameter *xstep.cascade.unit* should be used instead when necessary). If it is set to 'M', the shape is scaled 0.001 times (as if it were in meters) after translation from IGES or STEP.
72b7576f 288Default value is MM.
dba69de2 289
72b7576f 290<h4>xstep.cascade.unit</h4>
291This parameter defines units to which a shape should be converted when translated from IGES or STEP to CASCADE. Normally it is MM; only those applications that work internally in units other than MM should use this parameter.
dba69de2 292
72b7576f 293Default value is MM.
dba69de2 294
72b7576f 295<h4>read.step.product.mode:</h4>
296Defines the approach used for selection of top-level STEP entities for translation, and for recognition of assembly structures
dba69de2 297* 1 (ON) - *PRODUCT_DEFINITION* entities are taken as top-level ones; assembly structure is recognized by *NEXT_ASSEMBLY_USAGE_OCCURRENCE* entities. This is regular mode for reading valid STEP files conforming to AP 214, AP203 or AP 209.
298* 0 (OFF) - *SHAPE_DEFINITION_REPRESENTATION* entities are taken as top-level ones; assembly is recognized by *CONTEXT_DEPENDENT_SHAPE_REPRESENTATION* entities. This is compatibility mode, which can be used for reading legacy STEP files produced by older versions of STEP translators and having incorrect or incomplete product information.
72b7576f 300Read this parameter with:
dba69de2 301~~~~~
302Standard_Integer ic = Interface_Static::IVal("read.step.product.mode");
72b7576f 305Modify this parameter with:
dba69de2 306~~~~~
72b7576f 308.. error ..
dba69de2 309~~~~~
310Default value is 1 (ON).
312Note that the following parameters have effect only if *read.step.product.mode* is ON.
72b7576f 314<h4>read.step.product.context:</h4>
dba69de2 315
72b7576f 316When reading AP 209 STEP files, allows selecting either only ‘design’ or ‘analysis’, or both types of products for translation
dba69de2 317* 1 (all) - translates all products;
318* 2 (design) - translates only products that have *PRODUCT_DEFINITION_CONTEXT* with field *life_cycle_stage* set to ‘design’;
319* 3 (analysis) - translates only products associated with *PRODUCT_DEFINITION_CONTEXT* entity whose field *life_cycle_stage* set to ‘analysis’.
72b7576f 321Note that in AP 203 and AP214 files all products should be marked as ‘design’, so if this mode is set to ‘analysis’, nothing will be read.
dba69de2 322
72b7576f 323Read this parameter with:
dba69de2 324~~~~~
325Standard_Integer ic = Interface_Static::IVal("read.step.product.context");
72b7576f 328Modify this parameter with:
dba69de2 329~~~~~
72b7576f 330if(!Interface_Static::SetIVal(;read.step.product.context;,1))
331.. error ..
dba69de2 332~~~~~
333Default value is 1 (all).
72b7576f 335<h4>read.step.shape.repr:</h4>
dba69de2 336
72b7576f 337Specifies preferred type of representation of the shape of the product, in case if a STEP file contains more than one representation (i.e. multiple PRODUCT_DEFINITION_SHAPE entities) for a single product
dba69de2 338* 1 (All) - Translate all representations (if more than one, put in compound).
72b7576f 346When this option is not equal to 1, for products with multiple representations the representation having a type closest to the selected one in this list will be translated.
dba69de2 347
72b7576f 348Read this parameter with:
dba69de2 349~~~~~
350Standard_Integer ic = Interface_Static::IVal("read.step.shape.repr");
72b7576f 352Modify this parameter with:
dba69de2 353~~~~~
72b7576f 355.. error ..
dba69de2 356~~~~~
357Default value is 1 (All).
72b7576f 359<h4>read.step.assembly.level:</h4>
dba69de2 360
72b7576f 361Specifies which data should be read for the products found in the STEP file:
dba69de2 362* 1 (All) - Translate both the assembly structure and all associated shapes. If both shape and sub-assemblies are associated with the same product, all of them are read and put in a single compound. Note that this situation is confusing, as semantics of such configuration is not defined clearly by the STEP standard (whether this shape is an alternative representation of the assembly or is an addition to it), therefore warning will be issued in such case.
363* 2 (assembly) - Translate the assembly structure and shapes associated with parts only (not with sub-assemblies).
364* 3 (structure) - Translate only the assembly structure without shapes (a structure of empty compounds). This mode can be useful as an intermediate step in applications requiring specialized processing of assembly parts.
365* 4 (shape) - Translate only shapes associated with the product, ignoring the assembly structure (if any). This can be useful to translate only a shape associated with specific product, as a complement to *assembly* mode.
72b7576f 367Read this parameter with:
dba69de2 368~~~~~
369Standard_Integer ic = Interface_Static::IVal("read.step.assembly.level");
72b7576f 371Modify this parameter with:
dba69de2 372~~~~~
72b7576f 374.. error ..
dba69de2 375~~~~~
377Default value is 1 (All).
72b7576f 379<h4>read.step.shape.relationship:</h4>
dba69de2 380Defines whether shapes associated with the main *SHAPE_DEFINITION_REPRESENTATION* entity of the product via *SHAPE_REPRESENTATIONSHIP_RELATION* should be translated. This kind of association is used for the representation of hybrid models (i.e. models whose shape is composed of different types of representations) in AP 203 files since 1998, but it can be also used to associate auxiliary data with the product. This parameter allows to avoid translation of such auxiliary data.
381* 1 (ON) - translate
382* 0 (OFF) - do not translate
72b7576f 384Read this parameter with:
dba69de2 385~~~~~
386Standard_Integer ic = Interface_Static::IVal("read.step.shape.relationship");
72b7576f 388Modify this parameter with:
dba69de2 389~~~~~
72b7576f 390if(!Interface_Static::SetIVal(;read.step.shape.relationship;,1))
391.. error ..
dba69de2 392~~~~~
393Default value is 1 (ON).
72b7576f 395<h4>read.step.shape.aspect:</h4>
dba69de2 396Defines whether shapes associated with the *PRODUCT_DEFINITION_SHAPE* entity of the product via *SHAPE_ASPECT* should be translated. This kind of association was used for the representation of hybrid models (i.e. models whose shape is composed of different types of representations) in AP 203 files before 1998, but it is also used to associate auxiliary information with the sub-shapes of the part. Though STEP translator tries to recognize such cases correctly, this parameter may be useful to avoid unconditionally translation of shapes associated via *SHAPE_ASPECT* entities.
398* 1 (ON) - translate
399* 0 (OFF) - do not translate
72b7576f 401Read this parameter with:
dba69de2 402~~~~~
403Standard_Integer ic = Interface_Static::IVal("read.step.shape.aspect");
72b7576f 406Modify this parameter with:
dba69de2 407~~~~~
72b7576f 408if(!Interface_Static::SetIVal(;read.step.shape.aspect;,1))
409.. error ..
dba69de2 410~~~~~
411Default value is 1 (ON).
413@subsubsection occt_step_2_3_4 Performing the STEP file translation
72b7576f 415Perform the translation according to what you want to translate. You can choose either root entities (all or selected by the number of root), or select any entity by its number in the STEP file. There is a limited set of types of entities that can be used as starting entities for translation. Only the following entities are recognized as transferable:
416 * product_definition
417 * next_assembly_usage_occurrence
418 * shape_definition_representation
419 * subtypes of shape_representation (only if referred representation is transferable)
420 * manifold_solid_brep
421 * brep_with_voids
422 * faceted_brep
423 * faceted_brep_and_brep_with_voids
424 * shell_based_surface_model
425 * geometric_set and geometric_curve_set
426 * mapped_item
427 * subtypes of face_surface (including advanced_face)
428 * subtypes of shape_representation_relationship
429 * context_dependent_shape_representation
dba69de2 430
431The following methods are used for translation:
433* *Standard_Boolean ok = reader.TransferRoot(rank)* - translates a root entity identified by its rank;
434* *Standard_Boolean ok = reader.TransferOne(rank)* - translates an entity identified by its rank;
435* *Standard_Integer num = reader.TransferList(list)* - translates a list of entities in one operation (this method returns the number of successful translations);
436* *Standard_Integer NbRoots = reader.NbRootsForTransfer()* and *Standard_Integer num = reader.TransferRoots()* - translate all transferable roots.
438@subsubsection occt_step_2_3_5 Getting the translation results
72b7576f 439Each successful translation operation outputs one shape. A series of translations gives a set of shapes.
dba69de2 440
441Each time you invoke *TransferOne(), TransferRoot()* or *TransferList()*, their results are accumulated and the counter of results increases. You can clear the results with:
72b7576f 443reader.ClearShapes();
dba69de2 444~~~~~
72b7576f 445between two translation operations, if you do not, the results from the next translation will be added to the accumulation.
dba69de2 446
447*TransferRoots()* operations automatically clear all existing results before they start.
448* *Standard_Integer num = reader.NbShapes()* - gets the number of shapes recorded in the result;
449* *TopoDS_Shape shape = reader.Shape(rank)* gets the result identified by its rank, where rank is an integer between 1 and NbShapes;
450* *TopoDS_Shape shape = reader.Shape()* gets the first result of translation;
451* *TopoDS_Shape shape = reader.OneShape()* - gets all results in a single shape which is:
ba06f8bb 452 * a null shape if there are no results,
453 * in case of a single result, a shape that is specific to that result,
454 * a compound that lists the results if there are several results.
dba69de2 455
72b7576f 456<h5>Clearing the accumulation of results</h5>
dba69de2 457
458If several individual translations follow each other, the results give a list that can be purged with *reader.ClearShapes()*, which erases the existing results.
72b7576f 460<h5>Checking that translation was correctly performed</h5>
dba69de2 461Each time you invoke *Transfer* or *TransferRoots()*, you can display the related messages with the help of:
72b7576f 463reader.PrintCheckTransfer(failsonly,mode);
dba69de2 464~~~~~
466This check concerns the last invocation of *Transfer* or *TransferRoots()* only.
468@subsubsection occt_step_2_3_6 Selecting STEP entities for translation
72b7576f 470<h4>Selection possibilities</h4>
dba69de2 471
72b7576f 472There are three selection possibilities. You can select:
473 * the whole file,
474 * a list of entities,
475 * one entity.
dba69de2 476
668c2575 477<h5>The whole file</h5>
dba69de2 478
72b7576f 479Transferring the whole file means transferring all root entities. The number of roots can be evaluated when the file is loaded:
dba69de2 480~~~~~
72b7576f 481Standard_Integer NbRoots = reader.NbRootsForTransfer();
482Standard_Integer num = reader.TransferRoots();
dba69de2 483~~~~~
668c2575 485<h5>List of entities</h5>
dba69de2 486A list of entities can be formed by invoking *STEP214Control_Reader::GiveList* (this is a method of the parent class).
72b7576f 488Here is a simple example of how a list is translated:
dba69de2 489~~~~~
72b7576f 490Handle(TColStd_HSequenceOfTransient) list = reader.GiveList();
dba69de2 491~~~~~
492The result is a *TColStd_HSequenceOfTransient*.
72b7576f 493You can either translate a list entity by entity or all at once. An entity-by-entity operation lets you check each individual entity translated.
dba69de2 494
72b7576f 495<h5>Translating a whole list in one operation</h5>
dba69de2 496~~~~~
72b7576f 497Standard_Integer nbtrans = reader.TransferList (list);
dba69de2 498~~~~~
499*nbtrans* gives the number of items in the list that produced a shape.
72b7576f 501<h5>Translating a list entity by entity:</h5>
dba69de2 502~~~~~
503Standard_Integer i,nb = list->Length();
504for (i = 1; i <= nb; i ++) {
ba06f8bb 505 Handle(Standard_Transient) ent = list->Value(i);
506 Standard_Boolean OK = reader.TransferEntity (ent);
dba69de2 507}
72b7576f 510<h4>Selections</h4>
511There is a number of predefined operators that can be used. They are:
dba69de2 512 * *step214-placed-items* - selects all mapped_items or context_depended_shape_representations.
513 * *step214-shape-def-repr* - selects all shape_definition_representations.
514 * *step214-shape-repr* - selects all shape_representations.
e5bd0d98 515 * *step214-type(\<entity_type\>)* - selects all entities of a given type
dba69de2 516 * *step214-faces* - selects all faces_surface, advanced_face entities and the surface entity or any sub type if these entities are not shared by any face entity or shared by geometric_set entity.
e5bd0d98 517 * *step214-derived(\<entity_type\>)* - selects entities of a given type or any subtype.
dba69de2 518 * *step214-GS-curves* - selects all curve entities or any subtype except the composite_curve if these entities are shared by the geometric_set entity.
519 * *step214-assembly* - selects all mapped_items or context_depended_shape_representations involved into the assembly structure.
520 * *xst-model-all* - selects all entities.
521 * *xst-model-roots* - selects all roots.
e5bd0d98 522 * *xst-shared + \<selection\>* - selects all entities shared by at least one entity selected by selection.
523 * *xst-sharing + \<selection\>* - selects all entities sharing at least one entity selected by selection.
dba69de2 524 * *xst-transferrable-all* - selects all transferable entities.
525 * *xst-transferrable-roots* selects all translatable roots.
526Cumulative lists can be used as well.
528<h5>Single entities</h5>
529You can select an entity either by its rank or by its handle (an entity’s handle can be obtained by invoking the *StepData_StepModel::Entity* function).
72b7576f 531<h5>Selection by rank</h5>
dba69de2 532Use method *StepData_StepModel::NextNumberForLabel* to find its rank with the following:
72b7576f 534Standard_CString label = ‘#...’;
535StepData_StepModel model = reader.StepModel();
dba69de2 536rank = model->NextNumberForLabe(label, 0, Standard_False);
72b7576f 538Translate an entity specified by its rank:
dba69de2 539~~~~~
72b7576f 540Standard_Boolean ok = reader.Transfer (rank);
dba69de2 541~~~~~
72b7576f 543<h5>Direct selection of an entity</h5>
dba69de2 544*ent* is the entity. The argument is a *Handle(Standard_Transient)*.
72b7576f 546Standard_Boolean ok = reader.TransferEntity (ent);
dba69de2 547~~~~~
549@subsection occt_step_2_4 Mapping STEP entities to Open CASCADE Technology shapes
72b7576f 550Tables given in this paragraph show the mapping of STEP entities to OCCT objects. Only topological and geometrical STEP entities and entities defining assembly structures are described in this paragraph. For a full list of STEP entities please refer to Appendix A.
dba69de2 551
552@subsubsection occt_step_2_4_1 Assembly structure representation entities
72b7576f 553Not all entities defining the assembly structure in the STEP file are translated to OCCT shapes, but they are used to identify the relationships between assemblies and their components. Since the graph of ‘natural’ dependencies of entities based on direct references between them does not include the references from assemblies to their components, these dependencies are introduced in addition to the former ones. This is made basing on the analysis of the following entities describing the structure of the assembly.
ba06f8bb 555| STEP entity type | CASCADE shape | Comments |
668c2575 556| :--------------- | :-------------- | :------ |
ba06f8bb 557| product_definition | A *TopoDS_Compound* for assemblies, a CASCADE shape corresponding to the component type of for components, | Each assembly or component has its own *product_definition*. It is used as a starting point for translation when *read.step.product.mode* is ON. |
558| product_definition_shape | | This entity provides a link between *product_definition* and corresponding *shape_definition_representation*, or between *next_assembly_usage_occurence* and corresponding *context_dependent_shape_representation*. |
668c2575 559| shape_definition_representation | A TopoDS_Compound for assemblies, a CASCADE shape corresponding to the component type for components. | Each assembly or component has its own *shape_definition_representation*. The graph of dependencies is modified in such a way that *shape_definition_representations* of all components of the assembly are referred by the *shape_definition_representation* of the assembly. |
ba06f8bb 560| next_assembly_usage_occurence | | This entity defines a relationship between the assembly and its component. It is used to introduce (in the dependencies graph) the links between *shape_definition_representation* of the assembly and *shape_definition_representations* and *context_dependent_shape_representations* of all its components. |
561| mapped_item | TopoDS_Shape | This entity defines a mapping of the assembly component into the *shape_representation* of the assembly. The result of translation is a CASCADE shape translated from the component, to which transformation defined by the *mapped_item* is applied. |
4ee1bdf4 562| context_dependent_shape_representation | TopoDS_Shape | This entity is associated with the *next_assembly_usage_occurence* entity and defines a placement of the component in the assembly. The graph of dependencies is modified so that each *context_dependent_shape_representation* is referred by shape_definition_representation of the corresponding assembly. |
ba06f8bb 563| shape_representation_relationship_with_transformation | | This entity is associated with *context_dependent_shape_representation* and defines a transformation necessary to apply to the component in order to locate it in its place in the assembly. |
564| item_defined_transformation | | This entity defines a transformation operator used by *shape_representation_relationship_with_transformation* or *mapped_item* entity |
565| cartesian_transformation_operator | | This entity defines a transformation operator used by *shape_representation_relationship_with_transformation* or *mapped_item* entity |
dba69de2 566
567@subsubsection occt_step_2_4_2 Models
ba06f8bb 568| STEP entity type | CASCADE shape | Comments |
668c2575 569| :-------------- | :----------- | :---------- |
ba06f8bb 570| Solid Models | | |
571| brep_with_voids | TopoDS_Solid | |
572| faceted_brep | TopoDS_Solid | |
573| manifold_solid_brep | TopoDS_Solid | |
574| Surface Models | | |
575| shell_based_surface_model | TopoDS_Compound | *shell_based_surface_model* is translated into one or more *TopoDS_Shell* grouped in a *TopoDS_Compound* |
576| geometric_set | TopoDS_Compound | *TopoDS_Compound* contains only *TopoDS_Faces*, *TopoDS_Wires*, *TopoDS_Edges* and/or *TopoDS_Vertices*.
577| Wireframe Models | | |
578| geometric_curve_set | TopoDS_Compound | *TopoDS_Compound* contains only *TopoDS_Wires*, *TopoDS_Edges* and/or *TopoDS_Vertices*.
72b7576f 579
dba69de2 580@subsubsection occt_step_2_4_3 Topological entities
72b7576f 581
ba06f8bb 582| Topology | STEP entity type | CASCADE shape | Comments |
668c2575 583| :------- | :--------- | :-------- | :----- |
ba06f8bb 584| Vertices | vertex_point | TopoDS_Vertex | |
585| Edges | oriented_edge | TopoDS_Edge | |
586| | edge_curve | TopoDS_Edge | |
587| Loops | face_bound | TopoDS_Wire | |
588| | face_outer_bound | TopoDS_Wire | |
589| | edge_loop | TopoDS_Wire | |
590| | poly_loop | TopoDS_Wire | Each segment of *poly_loop* is translated into *TopoDS_Edge* with support of *Geom_Line* |
668c2575 591| | vertex_loop | TopoDS_Wire | Resulting *TopoDS_Wire* contains only one degenerated *TopoDS_Edge* |
ba06f8bb 592| Faces | face_surface | TopoDS_Face | |
593| | advanced_face | TopoDS_Face | |
668c2575 594| Shells | connected_face_set | TopoDS_Shell | |
ba06f8bb 595| | oriented_closed_shell | TopoDS_Shell | |
596| | closed_shell | TopoDS_Shell | |
668c2575 597| | open_shell | TopoDS_Shell | |
72b7576f 598
dba69de2 599@subsubsection occt_step_2_4_4 Geometrical entities
668c2575 6003D STEP entities are translated into geometrical objects from the *Geom* package while 2D entities are translated into objects from the *Geom2d* package.
ba06f8bb 601| Geometry | STEP entity type | CASCADE object | Comments |
668c2575 602| :------ | :-------- | :------ | :-------- |
ba06f8bb 603| Points | cartesian_point | Geom_CartesianPoint, Geom2d_CartesianPoint | |
604| Directions | direction | Geom_Direction, Geom2d_Direction | |
605| Vectors | vector | Geom_VectorWithMagnitude, Geom2d_VectorWithMagnitude | |
606| Placements | axis1_placement | Geom_Axis1Placement | |
668c2575 607| | axis2_placement_2d | Geom2d_AxisPlacement | |
ba06f8bb 608| | axis2_placement_3d | Geom_Axis2Placement | |
609| Curves | circle | Geom_Circle, Geom2d_Circle, Geom2d_BsplineCurve | Circle is translated into *Geom2d_BSplineCurve* when it references the surface of revolution (spherical surface, conical surface, etc.) |
610| | ellipse | Geom_Ellipse, Geom2d_Ellipse, Geom2d_BsplineCurve | Ellipse is translated into *Geom2d_BSplineCurve* when it references the surface of revolution (spherical surface, conical surface, etc.) |
611| | hyperbola | Geom_Hyperbola, Geom2d_Hyperbola | |
612| | line | Geom_Line, Geom2d_Line | |
613| | parabola | Geom_Parabola, Geom2d_Parabola | |
614| | pcurve | Geom2d_Curve | Pcurve in edge |
615| | curve_replica | Geom_Curve or Geom2d_Curve | Depending on the type of the base curve |
616| | offset_curve_3d | Geom_OffsetCurve | |
617| | trimmed_curve | Geom_TrimmedCurve or Geom2d_BsplineCurve | Only trimmed_curves trimmed by parameters are translated. All *trimmed_curves* are converted to *Geom2d_BSplineCurve*. |
618| | b_spline_curve | Geom_BsplineCurve or Geom2d_BsplineCurve | |
619| | b_spline_curve_with_knots | Geom_BsplineCurve or Geom2d_BsplineCurve | |
620| | bezier_curve | Geom_BsplineCurve or Geom2d_BsplineCurve | |
621| | rational_b_spline_curve | Geom_BsplineCurve or Geom2d_BsplineCurve | |
622| | uniform_curve | Geom_BsplineCurve or Geom2d_BsplineCurve | |
623| | quasi_ uniform_curve | Geom_BsplineCurve or Geom2d_BsplineCurve | |
624| | surface_curve | TopoDS_Edge | *surface_curve* defines geometrical support of an edge and its pcurves. |
625| | seam_curve | TopoDS_Edge | The same as *surface_curve* |
626| | composite_curve_segment | TopoDS_Edge | as a segment of *composite_curve* |
627| | composite_curve | TopoDS_Wire | |
628| | composite_curve_on_surface | TopoDS_Wire | |
629| | boundary_curve | TopoDS_Wire | |
630| Surfaces | b_spline_surface | Geom_BsplineSurface | |
631| | b_spline_surface_with_knots | Geom_BsplineSurface | |
632| | bezier_surface | Geom_BSplineSurface | |
633| | conical_surface | Geom_ConicalSurface | |
634| | cylindrical_surface | Geom_CylindricalSurface | |
635| | offset_surface | Geom_OffsetSurface | |
636| | surface_replica | Geom_Surface | Depending on the type of basis surface |
637| | plane | Geom_Plane | |
638| | rational_b_spline_surface | Geom_BSplineSurface | |
639| | rectangular_trimmed_surface | Geom_RectangularTrimmedSurface | |
668c2575 640| | spherical_surface | Geom_SphericalSurface | |
ba06f8bb 641| | surface_of_linear_extrusion | Geom_SurfaceOfLinearExtrusion | |
642| | surface_of_revolution | Geom_SurfaceOfRevolution | |
643| | toroidal_surface | Geom_ToroidalSurface | |
644| | degenerate_toroidal_surface | Geom_ToroidalSurface | |
645| | uniform_surface | Geom_BSplineSurface | |
646| | quasi_uniform_surface | Geom_BSplineSurface | |
647| | rectangular_composite_surface | TopoDS_Compound | Contains *TopoDS_Faces* |
648| | curve_bounded_surface | TopoDS_Face | |
dba69de2 649
651@subsection occt_step_2_5 Tolerance management
652@subsubsection occt_step_2_5_1 Values used for tolerances during reading STEP
72b7576f 653
4ee1bdf4 654During the STEP to OCCT translation several parameters are used as tolerances and precisions for different algorithms. Some of them are computed from other tolerances using specific functions.
dba69de2 655
72b7576f 656<h4>3D (spatial) tolerance</h4>
dba69de2 657* Package method *Precision::Confusion()* Value is 10-7. It is used as the minimal distance between points, which are considered to be distinct.
658* Uncertainty parameter is attached to each shape_representation entity in a STEP file and defined as *length_measure* in *uncertainty_measure_with_unit*. It is used as a fundamental value of precision during translation.
659* User - defined variable *read.precision.val* is used instead of uncertainty from a STEP file when parameter *read.precision.mode* is 1 (User).
72b7576f 661<h4>2D (parametric) tolerances</h4>
ba06f8bb 662* Package method *Precision\::PConfusion()* is a value of *0.01\*Precision\::Confusion()*. It is used to compare parametric bounds of curves.
dba69de2 663* Methods *UResolution* and *VResolution (tolerance3d)* of the class *GeomAdaptor_Surface* or *BRepAdaptor_Surface* - return tolerance in parametric space of a surface computed from 3d tolerance. When one tolerance value is to be used for both U and V parametric directions, the maximum or the minimum value of *UResolution* and *VResolution* is used.
664* Methods *Resolution (tolerance3d)* of the class *GeomAdaptor_Curve* or *BRepAdaptor_Curve* return tolerance in parametric space of a curve computed from 3d tolerance.
666@subsubsection occt_step_2_5_2 Initial setting of tolerances in translating objects
667In the STEP processor, the basic value of tolerance is set in method *STEPControl_ActorRead::Transfer()* to either value of uncertainty in shape_representation in STEP file (if parameter *read.precision.mode* is 0), or to a value of parameter *read.precision.val* (if *read.precision.mode* is 1 or if the uncertainty is not attached to the current entity in the STEP file).
669Translation starts from one entity translated as a root. *STEPControl_ActorRead::Transfer()*, function which performs the translation creates an object of the type *StepToTopoDS_Builder*, which is intended to translate topology.
671This object gets the initial tolerance value that is equal to *read.precision.val* or the uncertainty from shape_representation. During the translation of the entity, new objects of types *StepToTopoDS_Translate*... are created for translating sub-entities. All of them use the same tolerances as a *StepToTopoDS_Builder* object.
673@subsubsection occt_step_2_5_3 Transfer process
72b7576f 675<h4>Evolution of shape tolerances during transfer</h4>
676Let us follow the evolution of tolerances during the translation of STEP entities into an OCCT shape.
dba69de2 677
678If the starting STEP entity is a geometric_curve_set all the edges and vertices are constructed with *Precision::Confusion()*.
72b7576f 680If the starting STEP entity is not a geometric_curve_set the sub-shapes of the resulting shape have the following tolerance:
dba69de2 681 * all the faces are constructed with *Precision::Confusion()*,
682 * edges are constructed with *Precision::Confusion()*. It can be modified later by:
ba06f8bb 683 * *ShapeFix::SameParameter()* - the tolerance of edge shows real deviation of the 3D curve and pcurves.
684 * *ShapeFix_Wire::FixSelfIntersection()* if a pcurve of a self-intersecting edge is modified.
72b7576f 685 * vertices are constructed with Precision::Confusion(). It can be modified later by:
ba06f8bb 686 *StepToTopoDS_TranslateEdge*
687 *ShapeFix::SameParameter()*
688 *ShapeFix_Wire::FixSelfIntersection()*
689 *ShapeFix_Wire::FixLacking()*
690 *ShapeFix_Wire::Connected()*
72b7576f 692So, the final tolerance of sub-shapes shows the real local geometry of shapes (distance between vertices of adjacent edges, deviation of a 3D curve of an edge and its parametric curves and so on) and may be less or greater than the basic value of tolerance in the STEP processor.
dba69de2 693
72b7576f 694<h4>Translating into Geometry</h4>
dba69de2 695
696Geometrical entities are translated by classes *StepToGeom_Make...* Methods of these classes translate STEP geometrical entities into OCCT geometrical objects. Since these objects are not BRep objects, they do not have tolerances. Tolerance is used only as precision for detecting bad cases (such as points coincidence).
72b7576f 698<h4>Translating into Topology</h4>
dba69de2 699STEP topological entities are translated into OCCT shapes by use of classes from package *StepToTopoDS*.
72b7576f 701Although in a STEP file the uncertainty value is assigned to shape_representation entities and this value is applied to all entities in this shape_representation, OCCT shapes are produced with different tolerances. As a rule, updating the tolerance is fulfilled according to the local geometry of shapes (distance between vertices of adjacent edges, deviation of edge's 3D curve and its parametric curves and so on) and may be either less or greater than the uncertainty value assigned to the entity.
dba69de2 702
703The following default tolerances are used when creating shapes and how they are updated during translation.
704* *StepToTopoDS_TranslateVertex* constructs *TopoDS_Vertex* from a STEP *vertex_point* entity with *Precision::Confusion()*.
705* *StepToTopoDS_TranslateVertexLoop* creates degenerated *TopoDS_Edge* in *TopoDS_Wire* with tolerance *Precision::Confusion()*. *TopoDS_Vertex* of a degenerated edge is constructed with the initial value of tolerance.
706* *StepToTopoDS_TranslateEdge* constructs *TopoDS_Edge* only on the basis of 3D curve with *Precision::Confusion()*. Tolerance of the vertices can be increased up to a distance between their positions and ends of 3D curve.
707* *StepToTopoDS_TranslateEdgeLoop* constructs *TopoDS_Edges* in *TopoDS_Wire* with help of class *StepToTopoDS_TranslateEdge*. Pcurves from a STEP file are translated if they are present and *read.surfacecurve.mode* is 0. For each edge method *ShapeFix_Edge::FixSameParameter()* is called. If the resulting tolerance of the edge is greater than the maximum value between 1.0 and 2*Value of basis precision, then the pcurve is recomputed. The best of the original and the recomputed pcurve is put into *TopoDS_Edge*. The resulting tolerance of *TopoDS_Edge* is a maximal deviation of its 3D curve and its pcurve(s).
708* *StepToTopoDS_TranslatePolyLoop* constructs *TopoDS_Edges* in *TopoDS_Wire* with help of class *StepToTopoDS_TranslateEdge*. Their tolerances are not modified inside this method.
709* *StepToTopoDS_TranslateFace* constructs *TopoDS_Face* with the initial value of tolerance. *TopoDS_Wire* on *TopoDS_Face* is constructed with the help of classes *StepToTopoDS_TranslatePolyLoop, StepToTopoDS_TranslateEdgeLoop* or *StepToTopoDS_TranslateVertexLoop*.
710* *StepToTopoDS_TranslateShell* calls *StepToTopoDS_TranslateFace::Init* for each face. This class does not modify the tolerance value.
711* *StepToTopoDS_TranslateCompositeCurve* constructs *TopoDS_Edges* in *TopoDS_Wire* with help of class *BRepAPI_MakeEdge* and have a tolerance 10-7. Pcurves from a STEP file are translated if they are present and if *read.surfacecurve.mode* is not -3. The connection between segments of a composite curve (edges in the wire) is provided by calling method *ShapeFix_Wire::FixConnected()\** with a precision equal to the initial value of tolerance.
712* *StepToTopoDS_TranslateCurveBoundedSurface* constructs *TopoDS_Face* with tolerance *Precision::Confusion()*. *TopoDS_Wire* on *TopoDS_Face* is constructed with the help of class *StepToTopoDS_TranslateCompositeCurve*. Missing pcurves are computed using projection algorithm with the help of method *ShapeFix_Face::FixPcurves()*. For resulting face method *ShapeFix::SameParameter()* is called. It calls standard *BRepLib::SameParameter* for each edge in each wire, which can either increase or decrease the tolerances of the edges and vertices. *SameParameter* writes the tolerance corresponding to the real deviation of pcurves from 3D curve which can be less or greater than the tolerance in a STEP file.
713* *StepToTopoDS_Builder* a high level class. Its methods perform translation with the help of the classes listed above. If the value of *read.maxprecision.mode* is set to 1 then the tolerance of subshapes of the resulting shape is limited by 0 and *read.maxprecision.val*. Else this class does not change the tolerance value.
714* *StepToTopoDS_MakeTransformed* performs a translation of mapped_item entity and indirectly uses class *StepToTopoDS_Builder*. The tolerance of the resulting shape is not modified inside this method.
72b7576f 716<h4>Healing of resulting shape in ShapeHealing component</h4>
dba69de2 717##### ShapeFix_Wire::FixSelfIntersection()
718This method is intended for detecting and fixing self-intersecting edges and intersections of adjacent edges in a wire. It fixes self-intersections by cutting edges at the intersection point and/or by increasing the tolerance of the vertex (so that the vertex comprises the point of intersection). There is a maximum tolerance that can be set by this method transmitted as a parameter, currently is *read.maxprecision.value*.
72b7576f 720When a self-intersection of one edge is found, it is fixed by one of the two methods:
721 * tolerance of the vertex of that edge which is nearest to the point of self-intersection is increased so that it comprises both its own old position and the intersection point
722 * the self-intersecting loop on the pcurve is cut out and a new pcurve is constructed. This can increase the tolerance of the edge.
dba69de2 723
72b7576f 724The method producing a smaller tolerance is selected.
dba69de2 725
72b7576f 726When an intersection of two adjacent edges is detected, edges are cut at that point. Tolerance of the common vertex of these edges is increased in order to comprise both the intersection point and the old position.
dba69de2 727
728This method can increase the tolerance of the vertex up to a value of *read.maxprecision.value*.
730##### ShapeFix_Wire::FixLacking()
72b7576f 731This method is intended to detect gaps between pcurves of adjacent edges (with the precision of surface UVResolution computed from tolerance of a corresponding vertex) and to fix these gaps either by increasing the tolerance of the vertex, or by inserting a new degenerated edge (straight in parametric space).
dba69de2 732
72b7576f 733If it is possible to compensate a gap by increasing the tolerance of the vertex to a value of less than the initial value of tolerance, the tolerance of the vertex is increased. Else, if the vertex is placed in a degenerated point then a degenerated edge is inserted.
dba69de2 734
735##### ShapeFix_Wire::FixConnected()
736This method is intended to force two adjacent edges in the wire to share the same vertex. This method can increase the tolerance of the vertex. The maximal value of tolerance is *read.maxprecision.value*.
738@subsection occt_step_2_6 Code architecture
740The following diagram illustrates the structure of calls in reading STEP. The highlighted classes are intended to translate geometry
e5bd0d98 742@image html /user_guides/step/images/step_image003.png "The structure of calls in reading STEP"
743@image latex /user_guides/step/images/step_image003.png "The structure of calls in reading STEP"
dba69de2 744
745@subsection occt_step_2_7 Example
4ee1bdf4 747#include <STEPControl_Reader.hxx>
748#include <TopoDS_Shape.hxx>
749#include <BRepTools.hxx>
72b7576f 750
751Standard_Integer main()
dba69de2 753 STEPControl_Reader reader;
754 reader.ReadFile(;MyFile.stp;);
72b7576f 755
dba69de2 756 // Loads file MyFile.stp
757 Standard_Integer NbRoots = reader.NbRootsForTransfer();
72b7576f 758
dba69de2 759 // gets the number of transferable roots
760 cout;Number of roots in STEP file: ; NbRootsendl;
72b7576f 761
dba69de2 762 Standard_Integer NbTrans = reader.TransferRoots();
763 // translates all transferable roots, and returns the number of //successful translations
764 cout;STEP roots transferred: ; NbTransendl;
765 cout;Number of resulting shapes is: ;reader.NbShapes()endl;
72b7576f 766
dba69de2 767 TopoDS_Shape result = reader.OneShape();
768 // obtain the results of translation in one OCCT shape
72b7576f 769
dba69de2 770 . . .
72b7576f 771
dba69de2 773~~~~~
72b7576f 774
dba69de2 775
776@section occt_step_3 Writing STEP
777@subsection occt_step_3_1 Procedure
72b7576f 778You can translate OCCT shapes into STEP entities in the following steps:
dba69de2 779 1.initialize the process,
780 2.set the translation parameters,
781 3.perform the shape translation,
782 4.write the output file.
72b7576f 784You can translate several shapes before writing a file. All these translations output a separate shape_representation entity in STEP file.
dba69de2 785
786The user-defined option (parameter *write.step.schema*) is provided to define which version of schema (AP214 CD or DIS, or AP203) is used for the output STEP file.
788@subsection occt_step_3_2 Domain covered
789@subsubsection occt_step_3_2_1 Writing geometry and topology
72b7576f 790There are two families of OCCT objects that can be translated:
791 * geometrical objects,
792 * topological shapes.
dba69de2 793
794@subsubsection occt_step_3_2_2 Writing assembly structures
795The shapes organized in a structure of nested compounds can be translated either as simple compound shapes, or into the assembly structure, depending on the parameter *write.step.assembly*, which is described below.
72b7576f 796
4ee1bdf4 797The assembly structure placed in the produced STEP file corresponds to the structure described in the ProSTEP Agreement Log (item 21) as the second alternative (assembly structure through *representation_relationship* / *item_defined_transformation*). To represent an assembly it uses entities of the *representation_relationship_with_transformation* type. Transformation operators used for locating assembly components are represented by *item_defined_transformation* entities.
798If mode *write.step.assembly* is set to the values *ON* or *Auto* then an OCC shape consisting of nested compounds will be written as an assembly, otherwise it will be written as separate solids.
72b7576f 799
dba69de2 800Please see also <a href="#occt_step_3_4">Mapping OCCT shapes to STEP entities</a>
802@subsection occt_step_3_3 Description of the process
803@subsubsection occt_step_3_3_1 Initializing the process
72b7576f 804Before performing any other operation you have to create a writer object:
dba69de2 805~~~~~
72b7576f 806STEPControl_Writer writer;
dba69de2 807~~~~~
808@subsubsection occt_step_3_3_2 Setting the translation parameters
72b7576f 810The following parameters are used for the OCCT-to-STEP translation.
dba69de2 811
72b7576f 812<h4>write.precision.mode</h4>
dba69de2 813
72b7576f 814writes the precision value.
dba69de2 815* Least (-1) : the uncertainty value is set to the minimum tolerance of an OCCT shape
816* Average (0) : the uncertainty value is set to the average tolerance of an OCCT shape.
817* Greatest (1) : the uncertainty value is set to the maximum tolerance of an OCCT shape
818* Session (2) : the uncertainty value is that of the write.precision.val parameter.
72b7576f 820Read this parameter with:
dba69de2 821
822Standard_Integer ic = Interface_Static::IVal("write.precision.mode");
72b7576f 823Modify this parameter with:
dba69de2 824~~~~~
72b7576f 826.. error ..
dba69de2 827~~~~~
72b7576f 828Default value is 0.
dba69de2 829
72b7576f 830<h4>write.precision.val</h4>
831a user-defined precision value. This parameter gives the uncertainty for STEP entities constructed from OCCT shapes when the write.precision.mode parameter value is 1.
832 * 0.0001: default
833 * any real positive (non null) value.
dba69de2 834
72b7576f 835This value is stored in shape_representation in a STEP file as an uncertainty.
dba69de2 836
72b7576f 837Read this parameter with:
dba69de2 838~~~~~
839Standard_Real rp = Interface_Static::RVal("write.precision.val");
72b7576f 842Modify this parameter with:
dba69de2 843~~~~~
72b7576f 845.. error ..
dba69de2 846~~~~~
72b7576f 847Default value is 0.0001.
dba69de2 848
72b7576f 849<h4>write.step.assembly</h4>
850writing assembly mode.
dba69de2 851* 0 (Off) : (default) writes STEP files without assemblies.
852* 1 (On) : writes all shapes in the form of STEP assemblies.
853* 2 (Auto) : writes shapes having a structure of (possibly nested) *TopoDS_Compounds* in the form of STEP assemblies, single shapes are written without assembly structures.
72b7576f 855Read this parameter with:
dba69de2 856~~~~~
857Standard_Integer rp = Interface_Static::IVal("write.step.assembly");
72b7576f 859Modify this parameter with:
dba69de2 860~~~~~
72b7576f 862.. error ..
dba69de2 863~~~~~
72b7576f 864Default value is 0.
dba69de2 865
72b7576f 866<h4>write.step.schema</h4>
867defines the version of schema used for the output STEP file:
dba69de2 868 * 1 or ;AP214CD; (default): AP214, CD version (dated 26 November 1996),
869 * 2 or ;AP214DIS;: AP214, DIS version (dated 15 September 1998).
870 * 3 or ;AP203;: AP203, possibly with modular extensions (depending on data written to a file).
871 * 4 or *AP214IS*: AP214, IS version (dated 2002)
668c2575 872
72b7576f 873Read this parameter with:
dba69de2 874~~~~~
875TCollection_AsciiString schema = Interface_Static::CVal("write.step.schema");
72b7576f 877Modify this parameter with:
dba69de2 878~~~~~
72b7576f 880.. error ..
dba69de2 881~~~~~
72b7576f 882Default value is 1 (;CD;).
dba69de2 883For the parameter *write.step.schema* to take effect, method *STEPControl_Writer::Model(Standard_True)* should be called after changing this parameter (corresponding command in DRAW is *newmodel*).
72b7576f 885<h4>write.step.product.name</h4>
886Defines the text string that will be used for field ‘name’ of PRODUCT entities written to the STEP file.
dba69de2 887
888Default value: OCCT STEP translator (current OCCT version number).
72b7576f 890<h4>write.surfacecurve.mode</h4>
891This parameter indicates whether parametric curves (curves in parametric space of surface) should be written into the STEP file. This parameter can be set to Off in order to minimize the size of the resulting STEP file.
dba69de2 892
893* Off (0) : writes STEP files without pcurves. This mode decreases the size of the resulting STEP file .
894* On (1) : (default) writes pcurves to STEP file
72b7576f 896Read this parameter with:
dba69de2 897~~~~~
898Standard_Integer wp = Interface_Static::IVal("write.surfacecurve.mode");
72b7576f 900Modify this parameter with:
dba69de2 901~~~~~
72b7576f 903.. error ..
dba69de2 904~~~~~
72b7576f 905Default value is On.
dba69de2 906
72b7576f 907<h4>write.step.unit</h4>
908Defines a unit in which the STEP file should be written. If set to unit other than MM, the model is converted to these units during the translation.
dba69de2 909
72b7576f 910Default value is MM.
dba69de2 911
912<h4>write.step.resource.name and write.step.sequence</h4>
72b7576f 913These two parameters define the name of the resource file and the name of the sequence of operators (defined in that file) for Shape Processing, which is automatically performed by the STEP translator before translating a shape to a STEP file. Shape Processing is a user-configurable step, which is performed before the translation and consists in applying a set of operators to a resulting shape. This is a very powerful tool allowing customizing the shape and adapting it to the needs of a receiving application. By default the sequence consists of two operators: SplitCommonVertex and DirectFaces, which convert some geometry and topological constructs valid in Open CASCADE Technology but not in STEP to equivalent definitions conforming to STEP format.
dba69de2 914
72b7576f 915See description of parameter read.step.resource.name above for more details on using resource files.
dba69de2 916
917Default values:
918* read.step.resource.name - STEP,
919* read.step.sequence - ToSTEP.
1fa7cb8c 920
922This parameter indicates which of free vertices writing mode is switch on.
923* 0 (One Compound) : (default) All free vertices are united into one compound and exported in one SHAPE DEFINITION REPRESENTATION (vertex name and style are lost).
924* 1 (Single Vertex) : Each vertex exported in its own SHAPE DEFINITION REPRESENTATION (vertex name and style are not lost, but size of STEP file increases).
926Read this parameter with:
928Standard_Integer ic = Interface_Static::IVal("write.step.vertex.mode");
930Modify this parameter with:
933.. error ..
935Default value is 0.
dba69de2 936
937@subsubsection occt_step_3_3_3 Performing the Open CASCADE Technology shape translation
72b7576f 938An OCCT shape can be translated to STEP using one of the following models (shape_representations):
939 * manifold_solid_brep (advanced_brep_shape_representation)
940 * brep_with_voids (advanced_brep_shape_representation)
941 * faceted_brep (faceted_brep_shape_representation)
942 * shell_based_surface_model (manifold_surface_shape_representation)
943 * geometric_curve_set (geometrically_bounded_wireframe_shape_representation)
dba69de2 944
4ee1bdf4 945The enumeration *STEPControl_StepModelType* is intended to define a particular transferring model.
72b7576f 946The following values of enumeration are allowed:
ba06f8bb 947* *STEPControl_AsIs* Translator selects the resulting representation automatically, according to the type of CASCADE shape to translate it in its highest possible model;
948* *STEPControl_ManifoldSolidBrep* resulting entity is manifold_solid_brep or brep_with_voids
949* *STEPControl_FacetedBrep* resulting entity is *faceted_brep* or *faceted_brep_and_brep_with_voids* Note that only planar-face shapes with linear edges can be written;
dba69de2 950* *STEPControl_ShellBasedSurfaceModel* resulting entity is *shell_based_surface_model*;
ba06f8bb 951* *STEPControl_GeometricCurveSet* resulting entity is *geometric_curve_set*;
72b7576f 952
668c2575 953The following list shows which shapes can be translated in which mode:
ba06f8bb 954* *STEP214Control_AsIs* - any OCCT shape
955* *STEP214Control_ManifoldSolidBrep* - *TopoDS_Solid, TopoDS_Shell, TopoDS_Compound* (if it contains *TopoDS_Solids* and *TopoDS_Shells*.
956* *STEP214Control_FacetedBrep* - *TopoDS_Solid* or *TopoDS_Compound* containing *TopoDS_Solids* if all its surfaces are *Geom_Planes* and all curves are *Geom_Lines*.
dba69de2 957* *STEP214Control_ShellBasedSurfaceModel* - *TopoDS_Solid, TopoDS_Shell, TopoDS_Face* and *TopoDS_Compound* (if it contains all mentioned shapes)
958* *STEP214Control_GeometricCurveSet* - any OCCT shape.
960If *TopoDS_Compound* contains any other types besides the ones mentioned in the table, these sub-shapes will be ignored.
72b7576f 962In case if an OCCT shape cannot be translated according to its mode the result of translation is void.
dba69de2 963~~~~~
72b7576f 964STEP214Control_StepModelTope mode = STEP214Control_ManifoldSolidBrep;
965IFSelect_ReturnStatus stat = writer.Transfer(shape,mode);
dba69de2 966~~~~~
968@subsubsection occt_step_3_3_4 Writing the STEP file
72b7576f 969Write the STEP file with:
dba69de2 970~~~~~
971IFSelect_ReturnStatus stat = writer.Write("filename.stp");
72b7576f 973to give the file name.
dba69de2 974
975@subsection occt_step_3_4 Mapping Open CASCADE Technology shapes to STEP entities
72b7576f 976Only STEP entities that have a corresponding OCCT object and mapping of assembly structures are described in this paragraph. For a full list of STEP entities please refer to Appendix A.
dba69de2 977
978@subsubsection occt_step_3_4_1 Assembly structures and product information
979The assembly structures are written to the STEP file if parameter *write.step.assembly* is 1 or 2.
980Each *TopoDS_Compound* is written as an assembly with subshapes of that compound being components of the assembly. The structure of nested compounds is translated to the structure of nested assemblies. Shared subshapes are translated into shared components of assemblies. Shapes that are not compounds are translated into subtypes of shape_representation according to their type (see the next subchapter for details).
72b7576f 982A set of STEP entities describing general product information is written to the STEP file together with the entities describing the product geometry, topology and assembly structure. Most of these entities are attached to the entities being subtypes of shape_representation, but some of them are created only one per STEP file.
dba69de2 983
72b7576f 984The table below describes STEP entities, which are created when the assembly structure and product information are written to the STEP file, and shows how many of these entities are created. Note that the appearance of some of these entities depends on the version of the schema (AP214, CD, DIS or IS, or AP203).
72b7576f 985
ba06f8bb 986| CASCADE shape | STEP entity | Comments |
668c2575 987| :--------- | :------ | :----- |
988| | application_protocol_definition | One per STEP file, defines the application protocol used (depends on the schema version) |
ba06f8bb 989| | application_context | One per STEP file, defines the application generating the file (AP214 or AP203) |
990| TopoDS_Compound | shape_representation | Empty *shape_representation* describing the assembly. The components of that assembly are written as subtypes of shape_representation and are included to the assembly using *next_assembly_usage_occurence* entities. |
991| TopoDS_Shape | subtypes of shape_representation | Depending on the shape type, see the tables below for mapping details |
668c2575 992| | next_assembly_usage_occurence | Describes the instance of component in the assembly by referring corresponding *product_definitions*. If the same component is included in the assembly several times (for example, with different locations), several *next_assembly_usage_occurences* are created. |
ba06f8bb 993| | context_dependent_shape_representation | Describes the placement of a component in the assembly. One *context_dependent_shape_representation* corresponds to each *next_assembly_usage_occurence* entity. |
994| | shape_representation_relationship_with_transformation | Together with the *context_dependent_shape_representation* describes the location of a component in the assembly. |
995| | item_defined_transformation | Defines a transformation used for the location of a component in the assembly. Is referred by *shape_representation_relationship_with_transformation*. |
996| | shape_definition_representation | One per *shape_representation*. |
997| | product_definition_shape | One per *shape_definition_representation* and *context_dependent_shape_representation* |
998| | product_definition | Defines a product, one per *shape_definition_representation* |
999| | product_definition_formation | One per *product_definition*. All *product_definition_formations* in the STEP file have unique names. |
1000| | Product | One per *product_definition_formation*. All products in the STEP file have unique names. |
1001| | product_type (CD) or product_related_product_category (DIS,IS) | One per product |
1002| | Mechanical_context (CD) or product_context (DIS,IS) | One per product. |
1003| | product_definition_context | One per *product_definition*. |
dba69de2 1004
1006@subsubsection occt_step_3_4_2 Topological shapes
72b7576f 1007
ba06f8bb 1008| CASCADE shape | STEP entity | Comments |
668c2575 1009| :----- | :---- | :----- |
ba06f8bb 1010| TopoDS_Compound | geometric_curve_set | If the write mode is *STEP214Control_GeometricCurveSet* only 3D curves of the edges found in *TopoDS_Compound* and all its subshapes are translated |
1011| | manifold_solid_brep | If the write mode is *STEP214Control_AsIs* and *TopoDS_Compound* consists only of *TopoDS_Solids*. |
1012| | shell_based_surface_model | If the write mode is *STEP214Control_AsIs* and *TopoDS_Compound* consists of *TopoDS_Solids*, *TopoDS_Shells* and *TopoDS_Faces*.|
668c2575 1013| | geometric_curve_set | If the write mode is *STEP214Control_AsIs* and *TopoDS_Compound* contains *TopoDS_Wires, TopoDS_Edges, TopoDS_Vertices*. If the write mode is not *STEP214Control_AsIs* or *STEP214Control_GeometricCurveSet*, *TopoDS_Solids, TopoDS_Shells* and *TopoDS_Faces* are translated according to this table. |
ba06f8bb 1014| TopoDS_Solid | manifold_solid_brep | If the write mode is *STEP214Control_AsIs* or *STEP214Control_ManifoldSolidBrep* and CASCADE *TopoDS_Solid* has no voids. |
1015| | faceted_brep | If the write mode is *STEP214Control_FacetedBrep*. |
1016| | brep_with_voids | If the write mode is *STEP214Control_AsIs* or *STEP214Control_ManifoldSolidBrep* and CASCADE *TopoDS_Solid* has voids. |
668c2575 1017| | shell_based_surface_model | If the write mode is *STEP214Control_ShellBasedSurfaceModel*. |
ba06f8bb 1018| | geometric_curve_set | If the write mode is *STEP214Control_GeometricCurveSet*. Only 3D curves of the edges are translated. |
668c2575 1019| TopoDS_Shell in a TopoDS_Solid | closed_shell | If *TopoDS_Shell* is closed shell. |
1020| TopoDS_Shell | manifold_solid_brep | If the write mode is *STEP214Control_ManifoldSolidBrep*. |
1021| | shell_based_surface_model | If the write mode is *STEP214Control_AsIs* or *STEP214Control_ShellBasedSurfaceModel*. |
1022| | geometric_curve_set | If the write mode is *STEP214Control_GeometricCurveSet*. Only 3D curves of the edges are translated. |
ba06f8bb 1023| TopoDS_Face | advanced_face | |
1024| TopoDS_Wire in a TopoDS_Face | face_bound | The resulting *face_bound* contains *poly_loop* if write mode is *faceted_brep* or *edge_loop* if it is not. |
1025| TopoDS_Wire | geometric_curve_set | If the write mode is *STEP214Control_GeometricCurveSet*. Only 3D curves of the edges are translated. |
1026| TopoDS_Edge | oriented_edge | |
1027| TopoDS_Vertex | vertex_point | |
72b7576f 1028
dba69de2 1029@subsubsection occt_step_3_4_3 Geometrical objects
ba06f8bb 1030| Geometry | CASCADE object | STEP entity | Comments |
668c2575 1031| :----- | :------ | :----- | :----- |
ba06f8bb 1032| Points | Geom_CartesianPoint, Geom2d_CartesianPoint | cartesian_point | |
1033| | TColgp_Array1OfPnt, TColgp_Array1OfPnt2d | polyline | |
1034| Placements | Geom_Axis1Plasement, Geom2d_AxisPlacement | axis1_placement | |
1035| | Geom_Axis2Placement | axis2_placement_3d | |
1036| Directions | Geom_Direction, Geom2d_Direction | direction | |
1037| Vectors | Geom_Vector, Geom2d_Vector | vector | |
1038| Curves | Geom_Circle | circle | |
1039| | Geom2d_Circle | circle, rational_b_spline_curve | |
1040| | Geom_Ellipse | Ellipse | |
1041| | Geom2d_Ellipse | Ellipse, rational_b_spline_curve | |
1042| | Geom_Hyperbola, Geom2d_Hyperbola | Hyperbola | |
1043| | Geom_Parabola, Geom2d_Parabola | Parabola | |
1044| | Geom_BSplineCurve | b_spline_curve_with_knots or rational_b_spline_curve | *rational_b_spline_curve* is produced if *Geom_BsplineCurve* is a rational BSpline |
1045| | Geom2d_BSplineCurve | b_spline_curve_with_knots or rational_b_spline_curve | *rational_b_spline_curve* is produced if *Geom2d_BsplineCurve* is a rational BSpline |
1046| | Geom_BezierCurve | b_spline_curve_with_knots | |
1047| | Geom_Line or Geom2d_Line | Line | |
1048| Surfaces | Geom_Plane | Plane | |
1049| | Geom_OffsetSurface | offset_surface | |
1050| | Geom_ConicalSurface | conical_surface | |
1051| | Geom_CylindricalSurface | cylindrical_surface | |
1052| | Geom_OffsetSurface | offset_surface | |
1053| | Geom_RectangularTrimmedSurface | rectangular_trimmed_surface | |
1054| | Geom_SphericalSurface | spherical_surface | |
1055| | Geom_SurfaceOfLinear Extrusion | surface_of_linear_extrusion | |
1056| | Geom_SurfaceOf Revolution | surface_of_revolution | |
1057| | Geom_ToroidalSurface | toroidal_surface or degenerate_toroidal_surface | *degenerate_toroidal_surface* is produced if the minor radius is greater then the major one |
1058| | Geom_BezierSurface | b_spline_surface_with_knots | |
1059| | Geom_BsplineSurface | b_spline_surface_with_knots or rational_b_spline_surface | *rational_b_spline_surface* is produced if *Geom_BSplineSurface* is a rational Bspline |
dba69de2 1060
1062@subsection occt_step_3_5 Tolerance management
72b7576f 1063There are four possible values for the uncertainty when writing a STEP file:
1064 * user-defined value of the uncertainty
1065 * minimal value of sub-shapes tolerances
1066 * average value of sub-shapes tolerances
1067 * maximal value of sub-shapes tolerances
dba69de2 1068
72b7576f 1069The chosen value of the uncertainty is the final value that will be written into the STEP file.
dba69de2 1070See parameter *write.precision.mode*.
1073@subsection occt_step_3_6 Code architecture
1075@subsubsection occt_step_3_6_1 Graph of calls
72b7576f 1076The following diagram illustrates the structure of calls in writing STEP.
1077The highlighted classes are intended to translate geometry.
e5bd0d98 1080@image html /user_guides/step/images/step_image004.png "The structure of calls in writing STEP"
1081@image latex /user_guides/step/images/step_image004.png "The structure of calls in writing STEP"
72b7576f 1082
dba69de2 1083
1084@subsection occt_step_3_7 Example
72b7576f 1085~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.cpp}
4ee1bdf4 1086#include <STEPControl.hxx>
1087#include <STEPControl_Writer.hxx>
1088#include <TopoDS_Shape.hxx>
1089#include <BRepTools.hxx>
1090#include <BRep_Builder.hxx>
72b7576f 1091
1092Standard_Integer main()
1094TopoDS_Solid source;
1095. . .
1097STEPControl_Writer writer;
1098writer.Transfer(source, STEPControl_ManifoldSolidBrep);
1100// Translates TopoDS_Shape into manifold_solid_brep entity
1102// writes the resulting entity in the STEP file
dba69de2 1106
1107@section occt_step_4 Physical STEP file reading and writing
1109@subsection occt_step_4_1 Architecture of STEP Read and Write classes
1110@subsubsection occt_step_4_1_1 General principles
72b7576f 1112To perform data loading from a STEP file and to translate this data it is necessary to create correspondence between the EXPRESS schema and the structure of CDL classes. There are two possibilities to organize such correspondence: the so-called early binding and late binding.
dba69de2 1113* Late binding means that the processor works with a description of the schema. The processor builds a dictionary of entities and can recognize and read any entity that is described in the schema. To change the behavior and the scope of processor based on late binding it is enough to change the description of the schema. However, this binding has some disadvantages (for example low speed of reading process).
1114* In case of early binding, the structure of CDL classes is created beforehand with the help of a specific automatic tool or manually. If the processor finds an entity that is not found in this schema, it will simply be ignored. The processor calls constructors of appropriate classes and their read methods. To add a new type in the scope of the processor it is necessary to create a class corresponding to the new entity.
72b7576f 1116The STEP processor is based on early binding principles. It means that specific classes for each EXPRESS type have been created with the help of an automatic tool from the EXPRESS schema. There are two CDL classes for each EXPRESS type. The first class (named the representing class) represents the STEP entity in memory. The second one (RW - class) is intended to perform the initialization of the representing class and to output data to an intermediate structure to be written in a STEP file.
dba69de2 1117
1118@subsubsection occt_step_4_1_2 Complex entities
72b7576f 1119EXPRESS schema allows multiple inheritance. Entities that are built on the basis of multiple inheritance are called complex entities. Multiple inheritance is not available in CDL. EXPRESS enables any type of complex entities that can be inherited from any EXPRESS type. In the manner of early binding it is not possible to create a CDL class for any possible complex type. Thus, only widespread complex entities have corresponding representing classes and RW-classes that are created manually beforehand.
dba69de2 1120
1121@subsection occt_step_4_2 Physical file reading
72b7576f 1122Physical file reading consists of the following steps:
dba69de2 1123 1.Loading a STEP file and syntactic analysis of its contents
1124 2.Mapping STEP entities to the array of strings
1125 3.Creating empty OCCT objects representing STEP entities
1126 4.Initializing OCCT objects
1127 5.Building a references graph
1129@subsubsection occt_step_4_2_1 Loading a STEP file and syntactic analysis of its contents
72b7576f 1130In the first phase, a STEP file is syntactically checked and loaded in memory as a sequence of strings.
dba69de2 1131
1132Syntactic check is performed on the basis of rules defined in *step.lex* and *step.yacc* files. Files *step.lex* and *step.yacc* are located in the StepFile nocdlpack development unit. These files describe text encoding of STEP data structure (for additional information see ISO 10303 Part 21). The *step.lex* file describes the lexical structure of the STEP file. It describes identifiers, numbers, delimiters, etc. The *step.yacc* file describes the syntactic structure of the file, such as entities, parameters, and headers.
72b7576f 1134These files have been created only once and need to be updated only when norm ISO 10303-21 is changed.
dba69de2 1135
1136@subsubsection occt_step_4_2_2 Mapping STEP entities to arrays of strings
72b7576f 1137For each entity specified by its rank number the arrays storing its identifier, STEP type and parameters are filled.
dba69de2 1138@subsubsection occt_step_4_2_3 Creating empty Open CASCADE Technology objects that represent STEP entities
1139For each STEP entity an empty OCCT object representing this entity is created. A map of correspondence between entity rank and OCCT object is created and filled out. If a STEP entity is not recognized by the STEP processor then the *StepData_UndefinedEntity* object is created.
1140@subsubsection occt_step_4_2_4 Initializing Open CASCADE Technology objects
72b7576f 1141Each OCCT object (including StepData_UndefinedEntity) is initialized by its parameters with the help of the appropriate RW - class. If some entity has another entity as its parameter, the object that represents the latter entity will be initialized immediately. All initialized objects are put into a special map to avoid repeated initialization.
dba69de2 1142@subsubsection occt_step_4_2_5 Building a graph
72b7576f 1143The final phase is building a graph of references between entities. For each entity its RW-class is used to find entities referenced by this entity. Back references are built on the basis of direct references. In addition to explicit references defined in the STEP entities some additional (implicit) references are created for entities representing assembly structures (links from assemblies to their components).
dba69de2 1144@subsection occt_step_4_3 How to add a new entity in scope of the STEP processor
72b7576f 1145If it is necessary to read and translate a new entity by the STEP processor the Reader and Actor scope should be enhanced. Note that some actions to be made for adding a new type are different for simple and complex types.
1146The following steps should be taken:
dba69de2 1147* Create a CDL class representing a new entity. This can be *Stepxxx_NewEntity* class where xxx can be one of the following:
1148 * Basic
1149 * Geom
1150 * Shape
1151 * Visual
1152 * Repr
1153 * AP214
1154 * AP203
72b7576f 1155Each field of a STEP entity should be represented by a corresponding field of this class. The class should have methods for initializing, setting and obtaining fields and it should also have the default constructor.
dba69de2 1156* Create the *RWStepxxx_RWNewEntity* class with a default constructor and methods *ReadStep()*, *WriteStep()* and if the entity references other entities, then method *Share()*.
1157* Update file *StepAP214_Protocol.cxx*. In the constructor *StepAP214_Protocol::StepAP214_Protocol()* add the new type to the map of registered types and associate the unique integer identifier with this type.
1158* Update file *RWStepAP214_ReadWriteModule.cxx*. The changes should be the following:
ba06f8bb 1159 * For simple types:
1160 * Add a static object of class *TCollection_AsciiString* with name *Reco_NewEntity* and initialize it with a string containing the STEP type.
1161 * In constructor *WStepAP214_ReadWriteModule::RWStepAP214_ReadWriteModule()* add this object onto the list with the unique integer identifier of the new entity type.
1162 * In function *RWStepAP214_ReadWriteModule::StepType()* add a new C++ case operator for this identifier.
1163 * For complex types:
1164 * In the method *RWStepAP214_ReadWriteModule::CaseStep()* add a code for recognition the new entity type returning its unique integer identifier.
1165 * In the method *RWStepAP214_ReadWriteModule::IsComplex()* return True for this type.
1166 * In the method *RWStepAP214_ReadWriteModule::ComplexType()* fill the list of subtypes composing this complex type.
1167 * For both simple and complex types:
1168 * In function *RWStepAP214_ReadWriteModule::ReadStep()* add a new C++ case operator for the new identifier and call the *RWStepxxx_RWNewEntity* class, method *ReadStep* to initialize the new class.
dba69de2 1169* Update file *RWStepAP214_GeneralModule.cxx*. Add new C++ case operators to functions *NewVoid()* and *FillSharedCase()*, and in the method *CategoryNumber()* add a line defining a category of the new type.
1170* Enhance the *STEPControl_ActorRead class* (methods *Recognize()* and *Transfer()*), or class(es) translating some entities, to translate the new entity into an OCCT shape.
1172@subsection occt_step_4_4 Physical file writing
72b7576f 1173Physical file writing consists of the following steps:
dba69de2 1174 1. Building a references graph. Physical writing starts when STEP model, which was either loaded from a STEP file or created from OCCT shape with the help of translator, is available together with corresponding graph of references. During this step the graph of references can be recomputed.
1175 2. Transferring data from a model to a sequence of strings. For each representing entity from the model a corresponding RW - class is called. RW - class performs the writing of data that is contained in the representing class into an intermediate data structure. The mentioned structure is a sequence of strings in memory.
1176 3. Writing the sequence of strings into the file. The sequence of strings is written into the file. This is the last phase of physical STEP writing.
1179@subsection occt_step_4_5 How to add a new entity to write in the STEP file.
72b7576f 1181If it is necessary to write and translate an OCCT shape into a new entity by the STEP processor the Writer and Actor scope should be enhanced.
dba69de2 1182
1183For a description of steps, which should be taken for adding a new entity type to the STEP processor, see <a href="#occt_step_4_2">Physical file reading</a>. Then, enhance the *STEPControl_ActorWrite* class i.e. methods *Recognize()* and *Transfer()*, or other classes from *TopoDSToStep*, to translate the OCCT shape into a new STEP entity.
1185@section occt_step_6 Using DRAW
1186@subsection occt_step_6_1 DRAW STEP Commands Overview
1187*TKXSDRAW* toolkit provides commands for testing XSTEP interfaces interactively in the DRAW environment. It provides an additional set of DRAW commands specific for data exchange tasks, which allows loading and writing data files and an analysis of the resulting data structures and shapes.
72b7576f 1189This section is divided into five parts. Two of them deal with reading and writing a STEP file and are specific for the STEP processor. The first and the forth parts describe some general tools for setting parameters and analyzing the data. Most of them are independent of the norm being tested. Additionally, a table of mentioned DRAW commands is provided.
dba69de2 1190
1191In the description of commands, square brackets ([]) are used to indicate optional parameters. Parameters given in the angle brackets (\<\>) and sharps (#) are to be substituted by an appropriate value. When several exclusive variants are possible, a vertical dash (|) is used.
1193@subsection occt_step_6_2 Setting the interface parameters
72b7576f 1194A set of parameters for importing and exporting STEP data is defined in the XSTEP resource file. In XSDRAW, these parameters can be viewed or changed using the command
dba69de2 1195~~~~~
1196Draw:> param [<parameter_name> [<value>]]
4ee1bdf4 1198Command *param* with no arguments gives a list of all parameters with their values. When the argument *parameter_name* is specified, information about this parameter is printed (current value and short description).
dba69de2 1199
72b7576f 1200The third argument is used to set a new value of the given parameter. The result of the setting is printed immediately.
dba69de2 1201
72b7576f 1202During all interface operations, the protocol of the process (fail and warning messages, mapping of loaded entities into OCCT shapes etc.) can be output to the trace file. Two parameters are defined in the DRAW session: trace level (integer value from 0 to 9, default is 0), and trace file (default is standard output).
dba69de2 1203
72b7576f 1204Command xtrace is intended to view and change these parameters:
dba69de2 1205* *Draw:> xtrace* - prints current settings (e.g.: `Level=1 - Standard Output');
1206* *Draw:> xtrace \#* - sets trace level to the value #;
1207* *Draw:> xtrace tracefile.log* - sets the trace file as *tracefile.log*;
1208* *Draw:> xtrace.* - directs all messages to the standard output.
1210@subsection occt_step_6_3 Reading a STEP file
1212For a description of parameters used in reading a STEP file refer to <a href="#occt_step_2_3_3">Setting the translation parameters</a> section.
1214For reading a STEP file, the following parameters are defined (see above, <a href="#occt_step_6_2">the command *param*</a>):
ba06f8bb 1216| Description | Name | Values | Meaning |
668c2575 1217| :------------ | :---- | :------- | :------- |
ba06f8bb 1218| Precision for input entities | read.precision.mode | 0 or 1 | If 0 (File), precision of the input STEP file will be used for the loaded shapes; If 1 (Session), the following parameter will be used as the precision value. |
668c2575 1219| | read.precision.val | real | Value of precision (used if the previous parameter is 1) |
ba06f8bb 1220| Surface curves | read.surfacecurve.mode | 0 or 3 | Defines a preferable way of representing surface curves (2d or 3d representation). If 0, no preference. |
1221| Maximal tolerance | read.maxprecision.mode | 0 or 1 | If 1, maximum tolerance is used as a rigid limit If 0, maximum tolerance is used as a limit but can be exceeded by some algorithms. |
1222| | read.maxprecision.val | real | Value of maximum precision |
dba69de2 1223
72b7576f 1224It is possible either only to load a STEP file into memory (i.e. fill the *InterfaceModel* with data from the file), or to read it (i.e. load and convert all entities to OCCT shapes).
1225Loading is done by the command
dba69de2 1226~~~~~
1227Draw:> xload <file_name>
72b7576f 1229Once the file is loaded, it is possible to investigate the structure of the loaded data. To find out how you do it, look in the beginning of the analysis subsection.
1230Reading a STEP file is done by the command
dba69de2 1231~~~~~
1232Draw:> stepread <file_name> <result_shape_name> [selection]
72b7576f 1234Here a dot can be used instead of a filename if the file is already loaded by xload or stepread.
1235The optional selection (see below for a description of selections) specifies a set of entities to be translated. If an asterisk `*' is given, all transferable roots are translated. If a selection is not given, the user is prompted to define a scope of transfer interactively:
dba69de2 1236
668c2575 1237| N | Mode | Description |
1238| :---- | :---- | :---- |
ba06f8bb 1239| 0 | End | Finish transfer and exit stepread |
1240| 1 | root with rank 1 | Transfer first root |
1241| 2 | root by its rank | Transfer root specified by its rank |
1242| 3 | One entity | Transfer entity with a number provided by the user |
1243| 4 | Selection | Transfer only entities contained in selection |
dba69de2 1244
72b7576f 1245* root is an entity in the STEP file which is not referenced by another entities
1246Second parameter of the stepread command defines the name of the loaded shape.
dba69de2 1247
72b7576f 1248During the STEP translation, a map of correspondence between STEP entities and OCCT shapes is created.
dba69de2 1249
4ee1bdf4 1250To get information on the result of translation of a given STEP entity use the command @code Draw:> tpent #*.@endcode
dba69de2 1251
4ee1bdf4 1252To create an OCCT shape, corresponding to a STEP entity, use the command @code Draw:> tpdraw #*. @endcode
dba69de2 1253
4ee1bdf4 1254To get the number of a STEP entity, corresponding to an OCCT shape, use the command @code Draw:> fromshape <shape_name>. @endcode
1256To clear the map of correspondences between STEP entities and OCCT shapes use the command @code Draw:> tpclear. @endcode
dba69de2 1257
1258@subsection occt_step_6_4 Analyzing the transferred data
ba06f8bb 1259
72b7576f 1260The procedure of analysis of data import can be divided into two stages:
4ee1bdf4 1261 1. to check the file contents,
1262 2. to estimate the translation results (conversion and validated ratios).
ba06f8bb 1263
dba69de2 1264@subsubsection occt_step_6_4_1 Checking file contents
ba06f8bb 1265
72b7576f 1266General statistics on the loaded data can be obtained by using the command
ba06f8bb 1267
1269Draw:> data <symbol>
72b7576f 1272Information printed by this command depends on the symbol specified:
ba06f8bb 1274* *g* - Prints the information contained in the header of the file;
1275* *c* or *f* - Prints messages generated during the loading of the STEP file (when the procedure of the integrity of the loaded data check is performed) and the resulting statistics (f works only with fails while c with both fail and warning messages) ;
1276* *t* - The same as *c* or *f*, with a list of failed or warned entities;
1277* *m* or *l* - The same as *t* but also prints a status for each entity;
1278* *e* - Lists all entities of the model with their numbers, types, validity status etc.
1279* *R* - The same as e but lists only root entities
dba69de2 1280
72b7576f 1281There is a set of special objects, which can be used to operate with a loaded model. They can be of the following types:
ba06f8bb 1282* Selection Filters - allow selecting subsets of entities of the loaded model;
1283* Counter - calculates some statistics on the model data.
dba69de2 1284
4ee1bdf4 1285A list of these objects defined in the current session can be printed in DRAW by command @code Draw:> listitems. @endcode
72b7576f 1286
4ee1bdf4 1287Command @code Draw:> givelist <selection_name> @endcode prints a list of a subset of loaded entities defined by the <i>\<selection\></i> argument:
72b7576f 1288
ba06f8bb 1289* *xst-model-all* all entities of the model;
1290* *xst-model-roots* all roots;
1291* *xst-pointed* (Interactively) pointed entities (not used in DRAW);
1292* *xst-transferrable-all* all transferable (recognized) entities;
1293* *xst-transferrable-roots* Transferable roots.
dba69de2 1294
1295The command *listtypes* gives a list of entity types, which were encountered in the last loaded file (with a number of STEP entities of each type).
1297The list cannot be shown for all entities but for a subset of them. This subset is defined by an optional selection argument (for the list of possible values for STEP, see the table above).
72b7576f 1299Two commands are used to calculate statistics on the entities in the model:
dba69de2 1300~~~~~
ba06f8bb 1301Draw:> count <counter> [<selection>]
1302Draw:> listcount <counter> [<selection>]
dba69de2 1303~~~~~
72b7576f 1304The former only prints a count of entities while the latter also gives a list of them.
dba69de2 1305
72b7576f 1306The optional selection argument, if specified, defines a subset of entities, which are to be taken into account. The first argument should be one of the currently defined counters:
ba06f8bb 1307* *xst-types* - calculates how many entities of each OCCT type exist
dba69de2 1308* *step214-types* - calculates how many entities of each STEP type exist
1310Entities in the STEP file are numbered in the succeeding order. An entity can be identified either by its number or by its label. Label is the letter \# followed by the rank.
1311* *Draw:> elab \#* outputs a label for an entity with a known number.
1312* *Draw:> enum \#* prints a number for the entity with a given label.
ba06f8bb 1313* *Draw:> entity \# \<level_of_information\>* outputs the contents of a STEP entity.
dba69de2 1314* *Draw: estat \#* outputs the list of entities referenced by a given entity and the list of entities referencing to it.
1315* *Draw: dumpassembly* prints a STEP assembly as a tree.
1317Information about product names, *next_assembly_usage_occurence, shape_definition_representation, context_dependent_shape_representation* or *mapped_item entities* that are involved into the assembly structure will be printed.
1319@subsubsection occt_step_6_4_2 Estimating the results of reading STEP
72b7576f 1320All the following commands are available only after data is converted into OCCT shapes (i.e. after command 214read).
72b7576f 1321
ba06f8bb 1322Command *Draw:> tpstat [*|?]\<symbol\> [\<selection\>]* is provided to get all statistics on the last transfer, including a list of transferred entities with mapping from STEP to OCCT types, as well as fail and warning messages. The parameter <i>\<symbol\></i> defines what information will be printed:
dba69de2 1323
ba06f8bb 1324* *g* - General statistics (a list of results and messages)
1325* *c* - Count of all warning and fail messages
1326* *C* - List of all warning and fail messages
1327* *f* - Count of all fail messages
1328* *F* - List of all fail messages
1329* *n* - List of all transferred roots
1330* *s* - The same, with types of source entity and the type of result
1331* *b* - The same, with messages
1332* *t* - Count of roots for geometrical types
1333* *r* - Count of roots for topological types
1334* *l* - The same, with the type of the source entity
dba69de2 1335
1336The sign \* before parameters *n, s, b, t, r* makes it work on all entities (not only on roots).
1338The sign ? before *n, s, b, t* limits the scope of information to invalid entities.
4ee1bdf4 1340Optional argument <i>\<selection\></i> can limit the action of the command to the selection, not to all entities.
dba69de2 1341
72b7576f 1342To get help, run this command without arguments.
dba69de2 1343
1344The command *Draw:> tpstat \*1* gives statistics on the result of translation of different types of entities (taking check messages into account) and calculates summary translation ratios.
e5bd0d98 1346To get information on OCCT shape contents use command *Draw:> statshape \<shape_name\>* . It outputs the number of each kind of shapes (vertex, edge, wire, etc.) in the shape and some geometrical data (number of C0 surfaces, curves, indirect surfaces, etc.).
dba69de2 1347
72b7576f 1348The number of faces is returned as a number of references. To obtain the number of single instances, the standard command (from TTOPOLOGY executable) nbshapes can be used.
dba69de2 1349
e5bd0d98 1350To analyze the internal validity of the shape, use command *Draw:> checkbrep \<shape_name\> \<expurged_shape_name\>*. It checks shape geometry and topology for different cases of inconsistency, like self-intersecting wires or wrong orientation of trimming contours. If an error is found, it copies bad parts of the shape with the names <i>expurged_subshape_name _\#</i> and generates an appropriate message. If possible this command also tries to find STEP entities the OCCT shape was produced from.
dba69de2 1351
e5bd0d98 1352<i>\<expurged_shape_name\></i> will contain the original shape without invalid subshapes.
ba06f8bb 1353To get information on tolerances of the shape use command <i>Draw:> tolerance \<shape_name\> [\<min\> [\<max\>] [\<symbol\>]] </i>. It outputs maximum, average and minimum values of tolerances for each kind of subshapes having tolerances and for the whole shape in general.
dba69de2 1354
72b7576f 1355When specifying min and max arguments this command saves shapes with tolerances in the range [min, max] with names shape_name_... and gives their total number.
dba69de2 1356
ba06f8bb 1357<i>\<Symbol\></i> is used for specifying the kind of sub-shapes to analyze:
dba69de2 1358* *v* - for vertices,
1359* *e* - for edges,
1360* *f* - for faces,
1361* *c* - for shells and faces.
1363@subsection occt_step_6_5 Writing a STEP file
1364For writing shapes to a STEP file, the following parameters are defined (see above, <a href="#occt_step_6_2">the command *param*</a>):
ba06f8bb 1366| Description | Name | Values | Meaning |
668c2575 1367| :------------ | :----- | :------ | :------- |
ba06f8bb 1368| Uncertainty for resulting entities | Write.precision.mode | -1, 0, 1 or 2 | If -1 the uncertainty value is set to the minimal tolerance of CASCADE subshapes. If 0 the uncertainty value is set to the average tolerance of CASCADE subshapes. If 1 the uncertainty value is set to the maximal tolerance of CASCADE subshapes. If 2 the uncertainty value is set to write.precision.val |
1369| Value of uncertainty | Write.precision.val | real | Value of uncertainty (used if previous parameter is 2). |
dba69de2 1370
1371Several shapes can be written in one file. To start writing a new file, enter command *Draw:> newmodel*.
1372Actually, command *newmodel* will clear the *InterfaceModel* to empty it, and the next command will convert the specified shape to STEP entities and add them to the *InterfaceModel*:
668c2575 1373
dba69de2 1374~~~~~
ba06f8bb 1375Draw:> stepwrite <mode> <shape_name> [<file_name>]
dba69de2 1376~~~~~
668c2575 1377
bf62b306 1378The following modes are available :
1379 * *a* - as is - the mode is selected automatically depending on the type & geometry of the shape;
1380 * *m* - *manifold_solid_brep* or *brep_with_voids*
1381 * *f* - *faceted_brep*
1382 * *w* - *geometric_curve_set*
1383 * *s* - *shell_based_surface_model*
ba06f8bb 1384
72b7576f 1385After a successful translation, if file_name parameter is not specified, the procedure asks you whether to write a STEP model in the file or not:
dba69de2 1386~~~~~
72b7576f 1387execution status : 1
1388Mode (0 end, 1 file) :
dba69de2 1389~~~~~
1390It is necessary to call command *newmodel* to perform a new translation of the next OCCT shape.
1392@section occt_step_7 Reading from and writing to XDE
1393The *STEPCAFControl* package (TKXDESTEP toolkit) provides tools to read and write STEP files to and from XDE format (see XDE User’s Guide).
72b7576f 1394
72b7576f 1395In addition to the translation of shapes implemented in basic translator, it provides the following:
dba69de2 1396 * STEP assemblies, read as OCCT compounds by basic translator, are translated to XDE assemblies;
1397 * Names of products are translated and assigned to assembly components and instances in XDE;
1398 * STEP external references are recognized and translated (if external documents are STEP files);
1399 * Colors, layers, materials and validation properties assigned to parts or subparts are translated;
1400 * STEP dimensional tolerances are translated.
1402@subsection occt_step_7_1 Description of the process
1404@subsubsection occt_step_7_1_1 Loading a STEP file
72b7576f 1405Before performing any other operation, you must load a STEP file with:
dba69de2 1406~~~~~
72b7576f 1407STEPCAFControl_Reader reader(XSDRAW::Session(), Standard_False);
dba69de2 1408IFSelect_ReturnStatus stat = reader.ReadFile("filename.stp");
72b7576f 1410Loading the file only memorizes the data, it does not translate it.
dba69de2 1411
1412@subsubsection occt_step_7_1_2 Checking the loaded STEP file
1413This step is not obligatory. See a description of this step in section <a href="#occt_step_2_3_2">Checking the STEP file</a>.
1415@subsubsection occt_step_7_1_3 Setting the parameters for translation to XDE
1416See a description of this step in section <a href="#occt_step_2_3_3">Setting the translation parameters</a>.
72b7576f 1418In addition, the following parameters can be set for XDE translation of attributes:
1419 * Parameter for transferring colors:
dba69de2 1420~~~~~
72b7576f 1421reader.SetColorMode(mode);
1422// mode can be Standard_True or Standard_False
dba69de2 1423~~~~~
72b7576f 1424 * Parameter for transferring names:
dba69de2 1425~~~~~
72b7576f 1426reader.SetNameMode(mode);
1427// mode can be Standard_True or Standard_False
dba69de2 1428~~~~~
1429@subsubsection occt_step_7_1_4 Performing the translation of a STEP file to XDE
72b7576f 1430The following function performs a translation of the whole document:
dba69de2 1431~~~~~
72b7576f 1432Standard_Boolean ok = reader.Transfer(doc);
dba69de2 1433~~~~~
1434where *doc* is a variable which contains a handle to the output document and should have a type *Handle(TDocStd_Document)*.
1435@subsubsection occt_step_7_1_5 Initializing the process of translation from XDE to STEP
72b7576f 1436Here is how to initialize the process:
dba69de2 1437~~~~~
72b7576f 1438STEPCAFControl_Writer aWriter(XSDRAW::Session(),Standard_False);
dba69de2 1439~~~~~
1440@subsubsection occt_step_7_1_6 Setting the parameters for translation from XDE to STEP
72b7576f 1442The following parameters can be set for a translation of attributes to STEP:
1443 * Parameter for transferring colors:
dba69de2 1444~~~~~
72b7576f 1445aWriter.SetColorMode(mode);
1446// mode can be Standard_True or Standard_False
dba69de2 1447~~~~~
72b7576f 1448 * Parameter for transferring names:
dba69de2 1449~~~~~
72b7576f 1450aWriter.SetNameMode(mode);
1451// mode can be Standard_True or Standard_False
dba69de2 1452~~~~~
1453@subsubsection occt_step_7_1_7 Performing the translation of an XDE document to STEP
72b7576f 1454You can perform the translation of document by calling the function:
dba69de2 1455~~~~~
72b7576f 1456IFSelect_ReturnStatus aRetSt = aWriter.Transfer(doc);
dba69de2 1457~~~~~
1458where *doc* is a variable, which contains a handle to the input document for transferring and should have a type *Handle(TDocStd_Document)*.
1460@subsubsection occt_step_7_18 Writing a STEP file
72b7576f 1461Write a STEP file with:
dba69de2 1462~~~~~
1463IFSelect_ReturnStatus statw = aWriter.WriteFile("filename.stp");
72b7576f 1465or
dba69de2 1466~~~~~
72b7576f 1467IFSelect_ReturnStatus statw = writer.WriteFile (S);
dba69de2 1468~~~~~
1469where *S* is *OStream*.
72b7576f 1470