1 STEP processor {#user_guides__step}
2 ========================
6 @section occt_step_1 Overview
8 This 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). STEP files conforming to AP 214, AP 203 and partially AP 209 can be read. STEP files that are produced by this interface conform to STEP AP 214 or AP 203, according to the user option.
10 Only 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.
12 File translation is performed in the programming mode, via C++ calls.
14 For 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.
16 @section occt_step_2 Reading STEP
17 @subsection occt_step_2_1 Procedure
18 You can translate a STEP file into an OCCT shape in the following steps:
20 2. check file consistency,
21 3. set the translation parameters,
22 4. perform the translation,
24 @subsection occt_step_2_2 Domain covered
25 @subsubsection occt_step_2_2_1 Assemblies
26 The **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.
28 Handling 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).
30 The 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.
32 The 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.
33 Implementation of the second level of translation (conversion to XDE data structure) is provided by XDE STEP translator.
35 @subsubsection occt_step_2_2_2 Shape representations
36 Length units, plane angle units and the uncertainty value are taken from shape_representation entities. This data is used in the translation process.
38 The types of STEP representation entities that are recognized are:
39 * advanced_brep_shape_representation
40 * faceted_brep_shape_representation
41 * manifold_surface_shape_representation
42 * geometrically_bounded_wireframe_shape_representation
43 * geometrically_bounded_surface_shape_representation
44 * hybrid representations (shape_representation containing models of different type)
46 @subsubsection occt_step_2_2_3 Topological entities
47 The types of STEP topological entities that can be translated are:
54 For further information see <a href="#occt_step_2_4">Mapping STEP entities to Open CASCADE Technology shapes</a>.
56 @subsubsection occt_step_2_2_4 Geometrical entities
57 The types of STEP geometrical entities that can be translated are:
64 For further information see 2.4 Mapping STEP entities to Open CASCADE Technology shapes.
66 @subsection occt_step_2_3 Description of the process
67 @subsubsection occt_step_2_3_1 Loading the STEP file
69 Before performing any other operation you have to load the file with:
71 STEPControl_Reader reader;
72 IFSelect_ReturnStatus stat = reader.ReadFile(;filename.stp;);
74 Loading the file only memorizes the data, it does not translate it.
76 @subsubsection occt_step_2_3_2 Checking the STEP file
77 This step is not obligatory. Check the loaded file with:
79 reader.PrintCheckLoad(failsonly,mode);
81 Error messages are displayed if there are invalid or incomplete STEP entities, giving you the information on the cause of error.
83 If *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:
85 IFSelect_PrintCount mode = IFSelect_xxx
87 Where xxx can be one of the following:
88 * *ItemsByEntity* - gives a sequential list of all messages per STEP entity,
89 * *CountByItem* - gives the number of STEP entities with their types per message
90 * *ListByItem* - gives the number of STEP entities with their types and rank numbers per message
92 @subsubsection occt_step_2_3_3 Setting the translation parameters
93 The following parameters can be used to translate a STEP file into an OCCT shape.
95 If you give a value that is not within the range of possible values it will simply be ignored.
97 <h4>read.precision.mode</h4>
98 Defines which precision value will be used during translation (see section 2.5 below for details on precision and tolerances).
99 * *File (0)* - the precision value is set to length_measure in uncertainty_measure_with_unit from STEP file.
100 * *User (1)* - the precision value is that of the *read.precision.val* parameter.
102 Read this parameter with:
105 Standard_Integer ic = Interface_Static::IVal("read.precision.mode");
107 Modify this parameter with:
109 if(!Interface_Static::SetIVal("read.precision.mode",1))
112 Default value is File (0).
114 <h4>read.precision.val:</h4>
115 User 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.
117 This 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.
119 Read this parameter with:
121 Standard_Real rp = Interface_Static::RVal("read.precision.val");
123 Modify this parameter with:
125 if(!Interface_Static::SetRVal("read.precision.val",0.01))
128 By default this value is 0.0001.
130 The 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.
132 <h4>read.maxprecision.val</h4>
133 Defines 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.
135 Read this parameter with:
137 Standard_Real rp = Interface_Static::RVal("read.maxprecision.val");
139 Modify this parameter with:
141 if(!Interface_Static::SetRVal("read.maxprecision.val",0.1))
146 Note 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.
148 <h4>read.maxprecision.mode:</h4>
149 Defines the mode of applying the maximum allowed tolerance. Its possible values are:
150 * 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,
151 * 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.
153 Read this parameter with:
155 Standard_Integer ic = Interface_Static::IVal("read.maxprecision.mode");
157 Modify this parameter with:
159 if(!Interface_Static::SetIVal("read.maxprecision.mode",1))
162 Default value is 0 ("Preferred").
164 <h4>read.stdsameparameter.mode</h4>
165 defines the use of *BRepLib::SameParameter*. Its possible values are:
167 * 0 (Off) - *BRepLib::SameParameter* is not called,
168 * 1 (On) - *BRepLib::SameParameter* is called.
169 The 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*.
171 Read this parameter with:
173 Standard_Integer mv = Interface_Static::IVal("read.stdsameparameter.mode");
175 Modify this parameter with:
177 if (!Interface_Static::SetIVal ("read.stdsameparameter.mode",1))
180 Default value is 0 (;Off;).
182 <h4>read.surfacecurve.mode:</h4>
183 a preference for the computation of curves in an entity which has both 2D and 3D representation.
184 Each *TopoDS_Edge* in *TopoDS_Face* must have a 3D and 2D curve that references the surface.
186 If both 2D and 3D representation of the entity are present, the computation of these curves depends on the following values of parameter:
187 * *Default (0)* : no preference, both curves are taken (default value),
188 * *3DUse_Preferred (3)* : 3D curves are used to rebuild 2D ones.
190 Read this parameter with:
192 Standard_Integer rp = Interface_Static::IVal("read.surfacecurve.mode");
194 Modify this parameter with:
196 if(!Interface_Static::SetIVal("read.surfacecurve.mode",3))
199 Default value is (0).
201 <h4>read.encoderegularity.angle</h4>
203 This 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.
204 Read this parameter with:
206 Standard_Real era = Interface_Static::RVal("read.encoderegularity.angle");
208 Modify this parameter with:
210 if (!Interface_Static::SetRVal ("read.encoderegularity.angle",0.1))
213 Default value is 0.01.
215 <h4>step.angleunit.mode</h4>
216 This 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.
218 Default value is File
220 <h4>read.step.resource.name and read.step.sequence</h4>
222 These 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.
224 Please 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>.
226 In 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.
229 * read.step.resource.name - STEP,
230 * read.step.sequence - FromSTEP.
232 <h4>read.scale.unit</h4>
233 This 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.
236 <h4>xstep.cascade.unit</h4>
237 This 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.
241 <h4>read.step.product.mode:</h4>
242 Defines the approach used for selection of top-level STEP entities for translation, and for recognition of assembly structures
243 * 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.
244 * 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.
246 Read this parameter with:
248 Standard_Integer ic = Interface_Static::IVal("read.step.product.mode");
251 Modify this parameter with:
253 if(!Interface_Static::SetIVal("read.step.product.mode",1))
256 Default value is 1 (ON).
258 Note that the following parameters have effect only if *read.step.product.mode* is ON.
260 <h4>read.step.product.context:</h4>
262 When reading AP 209 STEP files, allows selecting either only ‘design’ or ‘analysis’, or both types of products for translation
263 * 1 (all) - translates all products;
264 * 2 (design) - translates only products that have *PRODUCT_DEFINITION_CONTEXT* with field *life_cycle_stage* set to ‘design’;
265 * 3 (analysis) - translates only products associated with *PRODUCT_DEFINITION_CONTEXT* entity whose field *life_cycle_stage* set to ‘analysis’.
267 Note 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.
269 Read this parameter with:
271 Standard_Integer ic = Interface_Static::IVal("read.step.product.context");
274 Modify this parameter with:
276 if(!Interface_Static::SetIVal(;read.step.product.context;,1))
279 Default value is 1 (all).
281 <h4>read.step.shape.repr:</h4>
283 Specifies 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
284 * 1 (All) - Translate all representations (if more than one, put in compound).
285 * 2 (ABSR) - Prefer ADVANCED_BREP_SHAPE_REPRESENTATION
286 * 3 (MSSR) - Prefer MANIFOLD_SURFACE_SHAPE_REPRESENTATION
287 * 4 (GBSSR) - Prefer GEOMETRICALLY_BOUNDED_SURFACE_SHAPE_REPRESENTATION
288 * 5 (FBSR) - Prefer FACETTED_BREP_SHAPE_REPRESENTATION
289 * 6 (EBWSR) - Prefer EDGE_BASED_WIREFRAME_SHAPE_REPRESENTATION
290 * 7 (GBWSR) - Prefer GEOMETRICALLY_BOUNDED_WIREFRAME _SHAPE_REPRESENTATION
292 When 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.
294 Read this parameter with:
296 Standard_Integer ic = Interface_Static::IVal("read.step.shape.repr");
298 Modify this parameter with:
300 if(!Interface_Static::SetIVal("read.step.shape.repr",1))
303 Default value is 1 (All).
305 <h4>read.step.assembly.level:</h4>
307 Specifies which data should be read for the products found in the STEP file:
308 * 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.
309 * 2 (assembly) - Translate the assembly structure and shapes associated with parts only (not with sub-assemblies).
310 * 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.
311 * 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.
313 Read this parameter with:
315 Standard_Integer ic = Interface_Static::IVal("read.step.assembly.level");
317 Modify this parameter with:
319 if(!Interface_Static::SetIVal("read.step.assembly.level",1))
323 Default value is 1 (All).
325 <h4>read.step.shape.relationship:</h4>
326 Defines 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.
328 * 0 (OFF) - do not translate
330 Read this parameter with:
332 Standard_Integer ic = Interface_Static::IVal("read.step.shape.relationship");
334 Modify this parameter with:
336 if(!Interface_Static::SetIVal(;read.step.shape.relationship;,1))
339 Default value is 1 (ON).
341 <h4>read.step.shape.aspect:</h4>
342 Defines 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.
345 * 0 (OFF) - do not translate
347 Read this parameter with:
349 Standard_Integer ic = Interface_Static::IVal("read.step.shape.aspect");
352 Modify this parameter with:
354 if(!Interface_Static::SetIVal(;read.step.shape.aspect;,1))
357 Default value is 1 (ON).
359 @subsubsection occt_step_2_3_4 Performing the STEP file translation
361 Perform 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:
363 * next_assembly_usage_occurrence
364 * shape_definition_representation
365 * subtypes of shape_representation (only if referred representation is transferable)
366 * manifold_solid_brep
369 * faceted_brep_and_brep_with_voids
370 * shell_based_surface_model
371 * geometric_set and geometric_curve_set
373 * subtypes of face_surface (including advanced_face)
374 * subtypes of shape_representation_relationship
375 * context_dependent_shape_representation
377 The following methods are used for translation:
379 * *Standard_Boolean ok = reader.TransferRoot(rank)* - translates a root entity identified by its rank;
380 * *Standard_Boolean ok = reader.TransferOne(rank)* - translates an entity identified by its rank;
381 * *Standard_Integer num = reader.TransferList(list)* - translates a list of entities in one operation (this method returns the number of successful translations);
382 * *Standard_Integer NbRoots = reader.NbRootsForTransfer()* and *Standard_Integer num = reader.TransferRoots()* - translate all transferable roots.
384 @subsubsection occt_step_2_3_5 Getting the translation results
385 Each successful translation operation outputs one shape. A series of translations gives a set of shapes.
387 Each time you invoke *TransferOne(), TransferRoot()* or *TransferList()*, their results are accumulated and the counter of results increases. You can clear the results with:
389 reader.ClearShapes();
391 between two translation operations, if you do not, the results from the next translation will be added to the accumulation.
393 *TransferRoots()* operations automatically clear all existing results before they start.
394 * *Standard_Integer num = reader.NbShapes()* - gets the number of shapes recorded in the result;
395 * *TopoDS_Shape shape = reader.Shape(rank)* gets the result identified by its rank, where rank is an integer between 1 and NbShapes;
396 * *TopoDS_Shape shape = reader.Shape()* gets the first result of translation;
397 * *TopoDS_Shape shape = reader.OneShape()* - gets all results in a single shape which is:
398 * a null shape if there are no results,
399 * in case of a single result, a shape that is specific to that result,
400 * a compound that lists the results if there are several results.
402 <h5>Clearing the accumulation of results</h5>
404 If several individual translations follow each other, the results give a list that can be purged with *reader.ClearShapes()*, which erases the existing results.
406 <h5>Checking that translation was correctly performed</h5>
407 Each time you invoke *Transfer* or *TransferRoots()*, you can display the related messages with the help of:
409 reader.PrintCheckTransfer(failsonly,mode);
412 This check concerns the last invocation of *Transfer* or *TransferRoots()* only.
414 @subsubsection occt_step_2_3_6 Selecting STEP entities for translation
416 <h4>Selection possibilities</h4>
418 There are three selection possibilities. You can select:
420 * a list of entities,
425 Transferring the whole file means transferring all root entities. The number of roots can be evaluated when the file is loaded:
427 Standard_Integer NbRoots = reader.NbRootsForTransfer();
428 Standard_Integer num = reader.TransferRoots();
431 <h4>List of entities</h4>
432 A list of entities can be formed by invoking *STEP214Control_Reader::GiveList* (this is a method of the parent class).
434 Here is a simple example of how a list is translated:
436 Handle(TColStd_HSequenceOfTransient) list = reader.GiveList();
438 The result is a *TColStd_HSequenceOfTransient*.
439 You can either translate a list entity by entity or all at once. An entity-by-entity operation lets you check each individual entity translated.
441 <h5>Translating a whole list in one operation</h5>
443 Standard_Integer nbtrans = reader.TransferList (list);
445 *nbtrans* gives the number of items in the list that produced a shape.
447 <h5>Translating a list entity by entity:</h5>
449 Standard_Integer i,nb = list->Length();
450 for (i = 1; i <= nb; i ++) {
451 Handle(Standard_Transient) ent = list->Value(i);
452 Standard_Boolean OK = reader.TransferEntity (ent);
457 There is a number of predefined operators that can be used. They are:
458 * *step214-placed-items* - selects all mapped_items or context_depended_shape_representations.
459 * *step214-shape-def-repr* - selects all shape_definition_representations.
460 * *step214-shape-repr* - selects all shape_representations.
461 * *step214-type(\<entity_type\>)* - selects all entities of a given type
462 * *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.
463 * *step214-derived(\<entity_type\>)* - selects entities of a given type or any subtype.
464 * *step214-GS-curves* - selects all curve entities or any subtype except the composite_curve if these entities are shared by the geometric_set entity.
465 * *step214-assembly* - selects all mapped_items or context_depended_shape_representations involved into the assembly structure.
466 * *xst-model-all* - selects all entities.
467 * *xst-model-roots* - selects all roots.
468 * *xst-shared + \<selection\>* - selects all entities shared by at least one entity selected by selection.
469 * *xst-sharing + \<selection\>* - selects all entities sharing at least one entity selected by selection.
470 * *xst-transferrable-all* - selects all transferable entities.
471 * *xst-transferrable-roots* selects all translatable roots.
472 Cumulative lists can be used as well.
474 <h5>Single entities</h5>
475 You 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).
477 <h5>Selection by rank</h5>
478 Use method *StepData_StepModel::NextNumberForLabel* to find its rank with the following:
480 Standard_CString label = ‘#...’;
481 StepData_StepModel model = reader.StepModel();
482 rank = model->NextNumberForLabe(label, 0, Standard_False);
484 Translate an entity specified by its rank:
486 Standard_Boolean ok = reader.Transfer (rank);
489 <h5>Direct selection of an entity</h5>
490 *ent* is the entity. The argument is a *Handle(Standard_Transient)*.
492 Standard_Boolean ok = reader.TransferEntity (ent);
495 @subsection occt_step_2_4 Mapping STEP entities to Open CASCADE Technology shapes
496 Tables 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.
498 @subsubsection occt_step_2_4_1 Assembly structure representation entities
499 Not 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.
501 | STEP entity type | CASCADE shape | Comments |
503 product_definition For assemblies, a TopoDS_Compound,
504 for components, a CASCADE shape corresponding to the type of component 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
505 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
506 shape_definition_representation For assemblies, a TopoDS_Compound,
507 for components, a CASCADE shape corresponding to the type of component 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.
508 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.
509 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.
510 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.
511 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.
512 item_defined_transformation This entity defines a transformation operator used by shape_representation_relationship_with_transformation or mapped_item entity
513 cartesian_transformation_operator This entity defines a transformation operator used by shape_representation_relationship_with_transformation or mapped_item entity
515 @subsubsection occt_step_2_4_2 Models
516 STEP entity type CASCADE shape Comments
518 brep_with_voids TopoDS_Solid
519 faceted_brep TopoDS_Solid
520 manifold_solid_brep TopoDS_Solid
522 shell_based_surface_model TopoDS_Compound shell_based_surface_model is translated into one or more TopoDS_Shell grouped in a TopoDS_Compound
523 geometric_set TopoDS_Compound TopoDS_Compound contains only TopoDS_Faces, TopoDS_Wires, TopoDS_Edges and/or TopoDS_Vertices
525 geometric_curve_set TopoDS_Compound TopoDS_Compound contains only TopoDS_Wires, TopoDS_Edges and/or TopoDS_Vertices
527 @subsubsection occt_step_2_4_3 Topological entities
528 STEP entity type CASCADE shape Comments
530 vertex_point TopoDS_Vertex
532 oriented_edge TopoDS_Edge
533 edge_curve TopoDS_Edge
535 face_bound TopoDS_Wire
536 face_outer_bound TopoDS_Wire
537 edge_loop TopoDS_Wire
538 poly_loop TopoDS_Wire Each segment of poly_loop is translated into TopoDS_Edge with support of Geom_Line
539 vertex_loop TopoDS_Wire Resulting TopoDS_Wire contains only one degenerated TopoDS_Edge
541 face_surface TopoDS_Face
542 advanced_face TopoDS_Face
544 connected_face_set TopoDS_Shell
545 oriented_closed_shell TopoDS_Shell
546 closed_shell TopoDS_Shell
547 open_shell TopoDS_Shell
550 @subsubsection occt_step_2_4_4 Geometrical entities
551 3D STEP entities are translated into geometrical objects from the Geom package while 2D entities are translated into objects from the Geom2d package.
552 STEP entity type CASCADE object Comments
554 cartesian_point Geom_CartesianPoint
555 Geom2d_CartesianPoint
557 direction Geom_Direction
560 vector Geom_VectorWithMagnitude
561 Geom2d_VectorWithMagnitude
563 axis1_placement Geom_Axis1Placement
564 axis2_placement_2d Geom2d_AxisPlacement
565 axis2_placement_3d Geom_Axis2Placement
569 Geom2d_BsplineCurve Circle is translated into Geom2d_BSplineCurve when it references the surface of revolution (spherical surface, conical surface, etc.)
572 Geom2d_BsplineCurve Ellipse is translated into Geom2d_BSplineCurve when it references the surface of revolution (spherical surface, conical surface, etc.)
573 hyperbola Geom_Hyperbola
577 parabola Geom_Parabola
579 pcurve Geom2d_Curve Pcurve in edge
580 curve_replica Geom_Curve Depending on the type of basis curve
582 offset_curve_3d Geom_OffsetCurve
583 trimmed_curve Geom_TrimmedCurve
584 Geom2d_BsplineCurve Only trimmed_curves trimmed by parameters are translated. All trimmed_curves are converted to Geom2d_BSplineCurve.
585 b_spline_curve Geom_BsplineCurve
588 knots Geom_BsplineCurve
590 bezier_curve Geom_BsplineCurve
592 rational_b_spline_curve Geom_BsplineCurve
594 uniform_curve Geom_BsplineCurve
596 quasi_ uniform_curve Geom_BsplineCurve
598 surface_curve TopoDS_Edge surface_curve defines geometrical support of an edge and its pcurves.
599 seam_curve TopoDS_Edge the same as surface_curve
600 composite_curve_segment TopoDS_Edge as a segment of composite_curve
601 composite_curve TopoDS_Wire
602 composite_curve_on_surface TopoDS_Wire
603 boundary_curve TopoDS_Wire
605 b_spline_surface Geom_BsplineSurface
606 b_spline_surface_with_knots Geom_BsplineSurface
607 bezier_surface Geom_BSplineSurface
608 conical_surface Geom_ConicalSurface
609 cylindrical_surface Geom_CylindricalSurface
610 offset_surface Geom_OffsetSurface
611 surface_replica Geom_Surface Depending on the type of basis surface
613 rational_b_spline_surface Geom_BSplineSurface
615 surface Geom_RectangularTrimmedSurface
616 spherical_surface Geom_SphericalSurface
617 surface_of_linear_extrusion Geom_SurfaceOfLinearExtrusion
618 surface_of_revolution Geom_SurfaceOfRevolution
619 toroidal_surface Geom_ToroidalSurface
620 degenerate_toroidal_surface Geom_ToroidalSurface
621 uniform_surface Geom_BSplineSurface
622 quasi_uniform_surface Geom_BSplineSurface
623 rectangular_composite_surface TopoDS_Compound Contains TopoDS_Faces
624 curve_bounded_surface TopoDS_Face
627 @subsection occt_step_2_5 Tolerance management
628 @subsubsection occt_step_2_5_1 Values used for tolerances during reading STEP
630 During the STEP = OCCT translation several parameters are used as tolerances and precisions for different algorithms. Some of them are computed from other tolerances using specific functions.
632 <h4>3D (spatial) tolerance</h4>
633 * Package method *Precision::Confusion()* Value is 10-7. It is used as the minimal distance between points, which are considered to be distinct.
634 * 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.
635 * User - defined variable *read.precision.val* is used instead of uncertainty from a STEP file when parameter *read.precision.mode* is 1 (User).
637 <h4>2D (parametric) tolerances</h4>
638 * Package method *Precision::PConfusion()* is a value of *0.01\*Precision::Confusion()*. It is used to compare parametric bounds of curves.
639 * 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.
640 * Methods *Resolution (tolerance3d)* of the class *GeomAdaptor_Curve* or *BRepAdaptor_Curve* return tolerance in parametric space of a curve computed from 3d tolerance.
642 @subsubsection occt_step_2_5_2 Initial setting of tolerances in translating objects
643 In 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).
645 Translation 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.
647 This 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.
649 @subsubsection occt_step_2_5_3 Transfer process
651 <h4>Evolution of shape tolerances during transfer</h4>
652 Let us follow the evolution of tolerances during the translation of STEP entities into an OCCT shape.
654 If the starting STEP entity is a geometric_curve_set all the edges and vertices are constructed with *Precision::Confusion()*.
656 If the starting STEP entity is not a geometric_curve_set the sub-shapes of the resulting shape have the following tolerance:
657 * all the faces are constructed with *Precision::Confusion()*,
658 * edges are constructed with *Precision::Confusion()*. It can be modified later by:
659 * *ShapeFix::SameParameter()* - the tolerance of edge shows real deviation of the 3D curve and pcurves.
660 * *ShapeFix_Wire::FixSelfIntersection()* if a pcurve of a self-intersecting edge is modified.
661 * vertices are constructed with Precision::Confusion(). It can be modified later by:
662 *StepToTopoDS_TranslateEdge*
663 *ShapeFix::SameParameter()*
664 *ShapeFix_Wire::FixSelfIntersection()*
665 *ShapeFix_Wire::FixLacking()*
666 *ShapeFix_Wire::Connected()*
668 So, 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.
670 <h4>Translating into Geometry</h4>
672 Geometrical 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).
674 <h4>Translating into Topology</h4>
675 STEP topological entities are translated into OCCT shapes by use of classes from package *StepToTopoDS*.
677 Although 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.
679 The following default tolerances are used when creating shapes and how they are updated during translation.
680 * *StepToTopoDS_TranslateVertex* constructs *TopoDS_Vertex* from a STEP *vertex_point* entity with *Precision::Confusion()*.
681 * *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.
682 * *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.
683 * *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).
684 * *StepToTopoDS_TranslatePolyLoop* constructs *TopoDS_Edges* in *TopoDS_Wire* with help of class *StepToTopoDS_TranslateEdge*. Their tolerances are not modified inside this method.
685 * *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*.
686 * *StepToTopoDS_TranslateShell* calls *StepToTopoDS_TranslateFace::Init* for each face. This class does not modify the tolerance value.
687 * *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.
688 * *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.
689 * *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.
690 * *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.
692 <h4>Healing of resulting shape in ShapeHealing component</h4>
693 ##### ShapeFix_Wire::FixSelfIntersection()
694 This 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*.
696 When a self-intersection of one edge is found, it is fixed by one of the two methods:
697 * 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
698 * the self-intersecting loop on the pcurve is cut out and a new pcurve is constructed. This can increase the tolerance of the edge.
700 The method producing a smaller tolerance is selected.
702 When 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.
704 This method can increase the tolerance of the vertex up to a value of *read.maxprecision.value*.
706 ##### ShapeFix_Wire::FixLacking()
707 This 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).
709 If 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.
711 ##### ShapeFix_Wire::FixConnected()
712 This 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*.
714 @subsection occt_step_2_6 Code architecture
716 The following diagram illustrates the structure of calls in reading STEP. The highlighted classes are intended to translate geometry
718 @image html /user_guides/step/images/step_image003.png "The structure of calls in reading STEP"
719 @image latex /user_guides/step/images/step_image003.png "The structure of calls in reading STEP"
721 @subsection occt_step_2_7 Example
723 #include STEPControl_Reader.hxx
724 #include TopoDS_Shape.hxx
725 #include BRepTools.hxx
727 Standard_Integer main()
729 STEPControl_Reader reader;
730 reader.ReadFile(;MyFile.stp;);
732 // Loads file MyFile.stp
733 Standard_Integer NbRoots = reader.NbRootsForTransfer();
735 // gets the number of transferable roots
736 cout;Number of roots in STEP file: ; NbRootsendl;
738 Standard_Integer NbTrans = reader.TransferRoots();
739 // translates all transferable roots, and returns the number of //successful translations
740 cout;STEP roots transferred: ; NbTransendl;
741 cout;Number of resulting shapes is: ;reader.NbShapes()endl;
743 TopoDS_Shape result = reader.OneShape();
744 // obtain the results of translation in one OCCT shape
752 @section occt_step_3 Writing STEP
753 @subsection occt_step_3_1 Procedure
754 You can translate OCCT shapes into STEP entities in the following steps:
755 1.initialize the process,
756 2.set the translation parameters,
757 3.perform the shape translation,
758 4.write the output file.
760 You can translate several shapes before writing a file. All these translations output a separate shape_representation entity in STEP file.
762 The 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.
764 @subsection occt_step_3_2 Domain covered
765 @subsubsection occt_step_3_2_1 Writing geometry and topology
766 There are two families of OCCT objects that can be translated:
767 * geometrical objects,
768 * topological shapes.
770 @subsubsection occt_step_3_2_2 Writing assembly structures
771 The 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.
773 The 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.
774 If 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.
776 Please see also <a href="#occt_step_3_4">Mapping OCCT shapes to STEP entities</a>
778 @subsection occt_step_3_3 Description of the process
779 @subsubsection occt_step_3_3_1 Initializing the process
780 Before performing any other operation you have to create a writer object:
782 STEPControl_Writer writer;
784 @subsubsection occt_step_3_3_2 Setting the translation parameters
786 The following parameters are used for the OCCT-to-STEP translation.
788 <h4>write.precision.mode</h4>
790 writes the precision value.
791 * Least (-1) : the uncertainty value is set to the minimum tolerance of an OCCT shape
792 * Average (0) : the uncertainty value is set to the average tolerance of an OCCT shape.
793 * Greatest (1) : the uncertainty value is set to the maximum tolerance of an OCCT shape
794 * Session (2) : the uncertainty value is that of the write.precision.val parameter.
796 Read this parameter with:
798 Standard_Integer ic = Interface_Static::IVal("write.precision.mode");
799 Modify this parameter with:
801 if(!Interface_Static::SetIVal("write.precision.mode",1))
806 <h4>write.precision.val</h4>
807 a 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.
809 * any real positive (non null) value.
811 This value is stored in shape_representation in a STEP file as an uncertainty.
813 Read this parameter with:
815 Standard_Real rp = Interface_Static::RVal("write.precision.val");
818 Modify this parameter with:
820 if(!Interface_Static::SetRVal("write.precision.val",0.01))
823 Default value is 0.0001.
825 <h4>write.step.assembly</h4>
826 writing assembly mode.
827 * 0 (Off) : (default) writes STEP files without assemblies.
828 * 1 (On) : writes all shapes in the form of STEP assemblies.
829 * 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.
831 Read this parameter with:
833 Standard_Integer rp = Interface_Static::IVal("write.step.assembly");
835 Modify this parameter with:
837 if(!Interface_Static::SetIVal("write.step.assembly",1))
842 <h4>write.step.schema</h4>
843 defines the version of schema used for the output STEP file:
844 * 1 or ;AP214CD; (default): AP214, CD version (dated 26 November 1996),
845 * 2 or ;AP214DIS;: AP214, DIS version (dated 15 September 1998).
846 * 3 or ;AP203;: AP203, possibly with modular extensions (depending on data written to a file).
847 * 4 or *AP214IS*: AP214, IS version (dated 2002)
848 This parameter affects the following entities written to the STEP file:
850 AP214, CD version AP214, DIS version AP214,IS version AP203
851 FILE_SCHEMA( (`AUTOMOTIVE_DESIGN_CC2 { 1 2 10303 214 -1 1 5 4}')) FILE_SCHEMA( (`AUTOMOTIVE_DESIGN { 1 2 10303 214 0 1 1 1}')) FILE_SCHEMA(
853 { 1 0 10303 214 1 1 1 1 }')) FILE_SCHEMA( (`CONFIG_CONTROL_DESIGN'))
854 APPLICATION_PROTOCOL_ DEFINITION
857 ,1997,##) APPLICATION_PROTOCOL_ DEFINITION(
858 'draft international standard',
860 1998,##) APPLICATION_PROTOCOL_DEFINITION
861 ('international standard', ‘automotive_design',
862 2000,##); APPLICATION_PROTOCOL_ DEFINITION
863 ('international standard', 'config_control_design',1994,##)
864 APPLICATION_CONTEXT( 'core data for automotive mechanical design processes') APPLICATION_CONTEXT( ‘configuration controlled 3D designs of mechanical parts and assemblies' )
865 PRODUCT_TYPE(`part',$,(##)) PRODUCT_RELATED_PRODUCT_CATEGORY( `part',$,(##))
866 MECHANICAL_CONTEXT(`',##, 'mechanical') PRODUCT_CONTEXT(`',##, 'mechanical') PRODUCT_CONTEXT('',##,'mechanical'); MECHANICAL_CONTEXT(`',##, 'mechanical')
868 In addition, in AP203 mode more product and organizational entities are generated (entities like PERSON_AND_ORGANIZATION, SECURITY_CLASSIFICATION etc., as required by AP203).
869 Read this parameter with:
871 TCollection_AsciiString schema = Interface_Static::CVal("write.step.schema");
873 Modify this parameter with:
875 if(!Interface_Static::SetCVal("write.step.schema","DIS"))
878 Default value is 1 (;CD;).
879 For 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*).
881 <h4>write.step.product.name</h4>
882 Defines the text string that will be used for field ‘name’ of PRODUCT entities written to the STEP file.
884 Default value: OCCT STEP translator (current OCCT version number).
886 <h4>write.surfacecurve.mode</h4>
887 This 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.
889 * Off (0) : writes STEP files without pcurves. This mode decreases the size of the resulting STEP file .
890 * On (1) : (default) writes pcurves to STEP file
892 Read this parameter with:
894 Standard_Integer wp = Interface_Static::IVal("write.surfacecurve.mode");
896 Modify this parameter with:
898 if(!Interface_Static::SetIVal("write.surfacecurve.mode",1))
903 <h4>write.step.unit</h4>
904 Defines 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.
908 <h4>write.step.resource.name and write.step.sequence</h4>
909 These 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.
911 See description of parameter read.step.resource.name above for more details on using resource files.
914 * read.step.resource.name - STEP,
915 * read.step.sequence - ToSTEP.
917 @subsubsection occt_step_3_3_3 Performing the Open CASCADE Technology shape translation
918 An OCCT shape can be translated to STEP using one of the following models (shape_representations):
919 * manifold_solid_brep (advanced_brep_shape_representation)
920 * brep_with_voids (advanced_brep_shape_representation)
921 * faceted_brep (faceted_brep_shape_representation)
922 * shell_based_surface_model (manifold_surface_shape_representation)
923 * geometric_curve_set (geometrically_bounded_wireframe_shape_representation)
925 The enumeration **TEPControl_StepModelType* is intended to define a particular transferring model.
926 The following values of enumeration are allowed:
927 * *STEPControl_AsIs* Translator selects the resulting representation automatically, according to the type of CASCADE shape to translate it in its highest possible model;
928 * *STEPControl_ManifoldSolidBrep* resulting entity is manifold_solid_brep or brep_with_voids
929 * *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;
930 * *STEPControl_ShellBasedSurfaceModel* resulting entity is *shell_based_surface_model*;
931 * *STEPControl_GeometricCurveSet* resulting entity is *geometric_curve_set*;
933 The following table shows which shapes can be translated in which mode:
934 * *STEP214Control_AsIs* - any OCCT shape
935 * *STEP214Control_ManifoldSolidBrep* - *TopoDS_Solid, TopoDS_Shell, TopoDS_Compound* (if it contains *TopoDS_Solids* and *TopoDS_Shells*.
936 * *STEP214Control_FacetedBrep* - *TopoDS_Solid* or *TopoDS_Compound* containing *TopoDS_Solids* if all its surfaces are *Geom_Planes* and all curves are *Geom_Lines*.
937 * *STEP214Control_ShellBasedSurfaceModel* - *TopoDS_Solid, TopoDS_Shell, TopoDS_Face* and *TopoDS_Compound* (if it contains all mentioned shapes)
938 * *STEP214Control_GeometricCurveSet* - any OCCT shape.
940 If *TopoDS_Compound* contains any other types besides the ones mentioned in the table, these sub-shapes will be ignored.
942 In case if an OCCT shape cannot be translated according to its mode the result of translation is void.
944 STEP214Control_StepModelTope mode = STEP214Control_ManifoldSolidBrep;
945 IFSelect_ReturnStatus stat = writer.Transfer(shape,mode);
948 @subsubsection occt_step_3_3_4 Writing the STEP file
949 Write the STEP file with:
951 IFSelect_ReturnStatus stat = writer.Write("filename.stp");
953 to give the file name.
955 @subsection occt_step_3_4 Mapping Open CASCADE Technology shapes to STEP entities
956 Only 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.
958 @subsubsection occt_step_3_4_1 Assembly structures and product information
959 The assembly structures are written to the STEP file if parameter *write.step.assembly* is 1 or 2.
960 Each *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).
962 A 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.
964 The 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).
966 CASCADE shape STEP entity Comments
967 application_protocol_definition One per STEP file, defines the application protocol used (depends on the schema version)
968 application_context One per STEP file, defines the application generating the file (AP214 or AP203)
969 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.
970 TopoDS_Shape subtypes of shape_representation Depending on the shape type, see the tables below for mapping details
971 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.
972 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.
973 shape_representation_relationship_with_transformation Together with the context_dependent_shape_ representation describes the location of a component in the assembly.
974 item_defined_transformation Defines a transformation used for the location of a component in the assembly. Is referred by shape_representation_relationship_with_transformation
975 shape_definition_representation One per shape_representation
976 product_definition_shape One per shape_definition_representation and context_dependent_shape_representation
977 product_definition Defines a product, one per shape_definition_representation
978 product_definition_formation One per product_definition. All product_definition_formations in the STEP file have unique names.
979 Product One per product_definition_formation. All products in the STEP file have unique names.
980 product_type (CD) or product_related_product_category (DIS,IS) One per product
981 Mechanical_context (CD) or product_context (DIS,IS) One per product.
982 product_definition_context One per product_definition.
985 @subsubsection occt_step_3_4_2 Topological shapes
987 CASCADE shape STEP entity Comments
988 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
989 manifold_solid_brep If the write mode is STEP214Control_AsIs and TopoDS_Compound consists only of TopoDS_Solids
990 shell_based_surface_model If the write mode is STEP214Control_AsIs and TopoDS_Compound consists of TopoDS_Solids, TopoDS_Shells and TopoDS_Faces
991 geometric_curve_set If the write mode is STEP214Control_AsIs and TopoDS_Compound contains TopoDS_Wires, TopoDS_Edges, TopoDS_Vertices
992 If the write mode is not STEP214Control_AsIs or STEP214Control_GeometricCurveSet TopoDS_Solids, TopoDS_Shells and TopoDS_Faces are translated according to this table.
993 TopoDS_Solid manifold_solid_brep If the write mode is STEP214Control_AsIs or STEP214Control_ManifoldSolidBrep and CASCADE TopoDS_Solid has no voids.
994 faceted_brep If the write mode is STEP214Control_FacetedBrep.
995 brep_with_voids If the write mode is STEP214Control_AsIs or STEP214Control_ManifoldSolidBrep and CASCADE TopoDS_Solid has voids.
996 shell_based_surface_model If the write mode is STEP214Control_ShellBasedSurfaceModel.
997 geometric_curve_set If the write mode is STEP214Control_GeometricCurveSet. Only 3D curves of the edges are translated.
998 TopoDS_Shell in a TopoDS_Solid closed_shell If TopoDS_Shell is closed shell.
999 TopoDS_Shell manifold_solid_brep If the write mode is STEP214Control_ManifoldSolidBrep.
1000 shell_based_surface_model If the write mode is STEP214Control_AsIs or STEP214Control_ShellBasedSurfaceModel.
1001 geometric_curve_set If the write mode is STEP214Control_GeometricCurveSet. Only 3D curves of the edges are translated.
1002 TopoDS_Face advanced_face
1003 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 not .
1004 TopoDS_Wire geometric_curve_set If the write mode is STEP214Control_GeometricCurveSet. Only 3D curves of the edges are translated.
1005 TopoDS_Edge oriented_edge
1006 TopoDS_Vertex vertex_point
1008 @subsubsection occt_step_3_4_3 Geometrical objects
1009 CASCADE object STEP entity Comments
1011 Geom_CartesianPoint cartesian_point
1012 Geom2d_CartesianPoint
1013 TColgp_Array1OfPnt polyline
1014 TColgp_Array1OfPnt2d
1016 Geom_Axis1Plasement axis1_placement
1017 Geom2d_AxisPlacement
1018 Geom_Axis2Placement axis2_placement_3d
1020 Geom_Direction direction
1027 Geom2d_Circle circle
1028 rational_b_spline_curve
1029 Geom_Ellipse Ellipse
1030 Geom2d_Ellipse Ellipse
1031 rational_b_spline_curve
1032 Geom_Hyperbola Hyperbola
1034 Geom_Parabola Parabola
1036 Geom_BSplineCurve b_spline_curve_with_knots
1037 rational_b_spline_curve if Geom_BsplineCurve is a rational BSpline
1038 Geom2d_BSplineCurve b_spline_curve_with_knots
1039 b_spline_curve_with_knots_ and_rational_b_spline_curve if Geom2d_BSplineCurve is a rational Bspline
1040 Geom_BezierCurve b_spline_curve_with_knots
1045 Geom_OffsetSurface offset_surface
1046 Geom_ConicalSurface conical_surface
1047 Geom_CylindricalSurface cylindrical_surface
1048 Geom_OffsetSurface offset_surface
1049 Geom_RectangularTrimmedSurface rectangular_trimmed_surface
1050 Geom_SphericalSurface spherical_surface
1051 Geom_SurfaceOfLinear Extrusion surface_of_linear_extrusion
1052 Geom_SurfaceOf Revolution surface_of_revolution
1053 Geom_ToroidalSurface toroidal_surface
1054 degenerate_toroidal_surface if the minor radius is greater then the major one
1055 Geom_BezierSurface b_spline_surface_with_knots
1056 Geom_BsplineSurface b_spline_surface_with_knots
1057 b_spline_surface_with_knots_ and_rational_b_spline_surface if Geom_BSplineSurface is a rational Bspline
1060 @subsection occt_step_3_5 Tolerance management
1061 There are four possible values for the uncertainty when writing a STEP file:
1062 * user-defined value of the uncertainty
1063 * minimal value of sub-shapes tolerances
1064 * average value of sub-shapes tolerances
1065 * maximal value of sub-shapes tolerances
1067 The chosen value of the uncertainty is the final value that will be written into the STEP file.
1068 See parameter *write.precision.mode*.
1071 @subsection occt_step_3_6 Code architecture
1073 @subsubsection occt_step_3_6_1 Graph of calls
1074 The following diagram illustrates the structure of calls in writing STEP.
1075 The highlighted classes are intended to translate geometry.
1078 @image html /user_guides/step/images/step_image004.png "The structure of calls in writing STEP"
1079 @image latex /user_guides/step/images/step_image004.png "The structure of calls in writing STEP"
1082 @subsection occt_step_3_7 Example
1083 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.cpp}
1084 #include STEPControl.hxx
1085 #include STEPControl_Writer.hxx
1086 #include TopoDS_Shape.hxx
1087 #include BRepTools.hxx
1088 #include BRep_Builder.hxx
1090 Standard_Integer main()
1092 TopoDS_Solid source;
1095 STEPControl_Writer writer;
1096 writer.Transfer(source, STEPControl_ManifoldSolidBrep);
1098 // Translates TopoDS_Shape into manifold_solid_brep entity
1099 writer.Write(;Output.stp;);
1100 // writes the resulting entity in the STEP file
1103 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1105 @section occt_step_4 Physical STEP file reading and writing
1107 @subsection occt_step_4_1 Architecture of STEP Read and Write classes
1108 @subsubsection occt_step_4_1_1 General principles
1110 To 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.
1111 * 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).
1112 * 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.
1114 The 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.
1116 @subsubsection occt_step_4_1_2 Complex entities
1117 EXPRESS 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.
1119 @subsection occt_step_4_2 Physical file reading
1120 Physical file reading consists of the following steps:
1121 1.Loading a STEP file and syntactic analysis of its contents
1122 2.Mapping STEP entities to the array of strings
1123 3.Creating empty OCCT objects representing STEP entities
1124 4.Initializing OCCT objects
1125 5.Building a references graph
1127 @subsubsection occt_step_4_2_1 Loading a STEP file and syntactic analysis of its contents
1128 In the first phase, a STEP file is syntactically checked and loaded in memory as a sequence of strings.
1130 Syntactic 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.
1132 These files have been created only once and need to be updated only when norm ISO 10303-21 is changed.
1134 @subsubsection occt_step_4_2_2 Mapping STEP entities to arrays of strings
1135 For each entity specified by its rank number the arrays storing its identifier, STEP type and parameters are filled.
1136 @subsubsection occt_step_4_2_3 Creating empty Open CASCADE Technology objects that represent STEP entities
1137 For 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.
1138 @subsubsection occt_step_4_2_4 Initializing Open CASCADE Technology objects
1139 Each 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.
1140 @subsubsection occt_step_4_2_5 Building a graph
1141 The 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).
1142 @subsection occt_step_4_3 How to add a new entity in scope of the STEP processor
1143 If 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.
1144 The following steps should be taken:
1145 * Create a CDL class representing a new entity. This can be *Stepxxx_NewEntity* class where xxx can be one of the following:
1153 Each 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.
1154 * Create the *RWStepxxx_RWNewEntity* class with a default constructor and methods *ReadStep()*, *WriteStep()* and if the entity references other entities, then method *Share()*.
1155 * 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.
1156 * Update file *RWStepAP214_ReadWriteModule.cxx*. The changes should be the following:
1158 * Add a static object of class *TCollection_AsciiString* with name *Reco_NewEntity* and initialize it with a string containing the STEP type.
1159 * In constructor *WStepAP214_ReadWriteModule::RWStepAP214_ReadWriteModule()* add this object onto the list with the unique integer identifier of the new entity type.
1160 * In function *RWStepAP214_ReadWriteModule::StepType()* add a new C++ case operator for this identifier.
1161 * For complex types:
1162 * In the method *RWStepAP214_ReadWriteModule::CaseStep()* add a code for recognition the new entity type returning its unique integer identifier.
1163 * In the method *RWStepAP214_ReadWriteModule::IsComplex()* return True for this type.
1164 * In the method *RWStepAP214_ReadWriteModule::ComplexType()* fill the list of subtypes composing this complex type.
1165 * For both simple and complex types:
1166 * 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.
1167 * 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.
1168 * Enhance the *STEPControl_ActorRead class* (methods *Recognize()* and *Transfer()*), or class(es) translating some entities, to translate the new entity into an OCCT shape.
1170 @subsection occt_step_4_4 Physical file writing
1171 Physical file writing consists of the following steps:
1172 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.
1173 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.
1174 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.
1177 @subsection occt_step_4_5 How to add a new entity to write in the STEP file.
1179 If 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.
1181 For 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.
1183 @section occt_step_6 Using DRAW
1184 @subsection occt_step_6_1 DRAW STEP Commands Overview
1185 *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.
1187 This 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.
1189 In 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.
1191 @subsection occt_step_6_2 Setting the interface parameters
1192 A 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
1194 Draw:> param [<parameter_name> [<value>]]
1196 Command 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).
1198 The third argument is used to set a new value of the given parameter. The result of the setting is printed immediately.
1200 During 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).
1202 Command xtrace is intended to view and change these parameters:
1203 * *Draw:> xtrace* - prints current settings (e.g.: `Level=1 - Standard Output');
1204 * *Draw:> xtrace \#* - sets trace level to the value #;
1205 * *Draw:> xtrace tracefile.log* - sets the trace file as *tracefile.log*;
1206 * *Draw:> xtrace.* - directs all messages to the standard output.
1208 @subsection occt_step_6_3 Reading a STEP file
1210 For 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.
1212 For reading a STEP file, the following parameters are defined (see above, <a href="#occt_step_6_2">the command *param*</a>):
1214 Description Name Values Meaning
1215 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
1216 If 1 (Session), the following parameter will be used as the precision value
1217 read.precision.val real Value of precision (used if the previous parameter is 1)
1218 Surface curves read.surfacecurve.mode 0 or 3 Defines a preferable way of representing surface curves (2d or 3d representation).
1219 If 0, no preference.
1220 Maximal tolerance read.maxprecision.mode 0 or 1 If 1, maximum tolerance is used as a rigid limit
1221 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
1225 It 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).
1226 Loading is done by the command
1228 Draw:> xload <file_name>
1230 Once 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.
1231 Reading a STEP file is done by the command
1233 Draw:> stepread <file_name> <result_shape_name> [selection]
1235 Here a dot can be used instead of a filename if the file is already loaded by xload or stepread.
1236 The 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:
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
1245 * root is an entity in the STEP file which is not referenced by another entities
1246 Second parameter of the stepread command defines the name of the loaded shape.
1248 During the STEP translation, a map of correspondence between STEP entities and OCCT shapes is created.
1250 To get information on the result of translation of a given STEP entity use the command *Draw:> tpent \#*.
1252 To create an OCCT shape, corresponding to a STEP entity, use the command *Draw:> tpdraw \#*.
1253 To get the number of a STEP entity, corresponding to an OCCT shape, use the command *Draw:> fromshape \<shape_name\>*.
1255 To clear the map of correspondences between STEP entities and OCCT shapes use the command *Draw:> tpclear*.
1257 @subsection occt_step_6_4 Analyzing the transferred data
1258 The procedure of analysis of data import can be divided into two stages:
1259 1.to check the file contents,
1260 2.to estimate the translation results (conversion and validated ratios).
1262 @subsubsection occt_step_6_4_1 Checking file contents
1263 General statistics on the loaded data can be obtained by using the command
1264 Draw:> data \<symbol\>
1265 Information printed by this command depends on the symbol specified:
1267 * *g* - Prints the information contained in the header of the file;
1268 * *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) ;
1269 * *t* - The same as *c* or *f*, with a list of failed or warned entities;
1270 * *m* or *l* - The same as *t* but also prints a status for each entity;
1271 * *e* - Lists all entities of the model with their numbers, types, validity status etc.
1272 * *R* - The same as e but lists only root entities
1274 There is a set of special objects, which can be used to operate with a loaded model. They can be of the following types:
1275 * Selection Filters - allow selecting subsets of entities of the loaded model;
1276 * Counter - calculates some statistics on the model data.
1278 A list of these objects defined in the current session can be printed in DRAW by command *Draw:> listitems*.
1280 Command *Draw:> givelist <selection_name>* prints a list of a subset of loaded entities defined by the selection argument:
1282 * *xst-model-all* all entities of the model;
1283 * *xst-model-roots* all roots;
1284 * *xst-pointed* (Interactively) pointed entities (not used in DRAW);
1285 * *xst-transferrable-all* all transferable (recognized) entities;
1286 * *xst-transferrable-roots* Transferable roots.
1288 The 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).
1290 The 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).
1292 Two commands are used to calculate statistics on the entities in the model:
1294 Draw:> count <counter> [\<selection\>]
1295 Draw:> listcount <counter> [\<selection\>]
1297 The former only prints a count of entities while the latter also gives a list of them.
1299 The 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:
1300 * *xst-types* - calculates how many entities of each OCCT type exist
1301 * *step214-types* - calculates how many entities of each STEP type exist
1303 Entities 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.
1304 * *Draw:> elab \#* outputs a label for an entity with a known number.
1305 * *Draw:> enum \#* prints a number for the entity with a given label.
1306 * *Draw:> entity \# <level_of_information>* outputs the contents of a STEP entity.
1307 * *Draw: estat \#* outputs the list of entities referenced by a given entity and the list of entities referencing to it.
1308 * *Draw: dumpassembly* prints a STEP assembly as a tree.
1310 Information 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.
1312 @subsubsection occt_step_6_4_2 Estimating the results of reading STEP
1313 All the following commands are available only after data is converted into OCCT shapes (i.e. after command 214read).
1315 Command *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 symbol defines what information will be printed:
1317 * *g* - General statistics (a list of results and messages)
1318 * *c* - Count of all warning and fail messages
1319 * *C* - List of all warning and fail messages
1320 * *f* - Count of all fail messages
1321 * *F* - List of all fail messages
1322 * *n* - List of all transferred roots
1323 * *s* - The same, with types of source entity and the type of result
1324 * *b* - The same, with messages
1325 * *t* - Count of roots for geometrical types
1326 * *r* - Count of roots for topological types
1327 * *l* - The same, with the type of the source entity
1329 The sign \* before parameters *n, s, b, t, r* makes it work on all entities (not only on roots).
1331 The sign ? before *n, s, b, t* limits the scope of information to invalid entities.
1333 Optional argument \<selection\> can limit the action of the command to the selection, not to all entities.
1335 To get help, run this command without arguments.
1337 The 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.
1339 To 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.).
1341 The 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.
1343 To 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.
1345 <i>\<expurged_shape_name\></i> will contain the original shape without invalid subshapes.
1346 To 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.
1348 When 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.
1350 <i><Symbol></i> is used for specifying the kind of sub-shapes to analyze:
1351 * *v* - for vertices,
1354 * *c* - for shells and faces.
1356 @subsection occt_step_6_5 Writing a STEP file
1357 For writing shapes to a STEP file, the following parameters are defined (see above, <a href="#occt_step_6_2">the command *param*</a>):
1360 Description Name Values Meaning
1361 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.
1362 If 0 the uncertainty value is set to the average tolerance of CASCADE subshapes.
1363 If 1 the uncertainty value is set to the maximal tolerance of CASCADE subshapes.
1364 If 2 the uncertainty value is set to write.precision.val
1365 Value of uncertainty Write.precision.val real Value of uncertainty (used if previous parameter is 2)
1368 Several shapes can be written in one file. To start writing a new file, enter command *Draw:> newmodel*.
1369 Actually, 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*:
1371 Draw:> stepwrite <mode> \<shape_name\> [<file_name>]
1373 The available modes are following:
1375 * *m* - manifold_solid_brep or brep_with_voids
1376 * *f* - faceted_brep
1377 * *w* - geometric_curve_set
1378 * *s* - shell_based_surface_model
1380 After 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:
1382 execution status : 1
1383 Mode (0 end, 1 file) :
1385 It is necessary to call command *newmodel* to perform a new translation of the next OCCT shape.
1387 @section occt_step_7 Reading from and writing to XDE
1388 The *STEPCAFControl* package (TKXDESTEP toolkit) provides tools to read and write STEP files to and from XDE format (see XDE User’s Guide).
1390 In addition to the translation of shapes implemented in basic translator, it provides the following:
1391 * STEP assemblies, read as OCCT compounds by basic translator, are translated to XDE assemblies;
1392 * Names of products are translated and assigned to assembly components and instances in XDE;
1393 * STEP external references are recognized and translated (if external documents are STEP files);
1394 * Colors, layers, materials and validation properties assigned to parts or subparts are translated;
1395 * STEP dimensional tolerances are translated.
1397 @subsection occt_step_7_1 Description of the process
1399 @subsubsection occt_step_7_1_1 Loading a STEP file
1400 Before performing any other operation, you must load a STEP file with:
1402 STEPCAFControl_Reader reader(XSDRAW::Session(), Standard_False);
1403 IFSelect_ReturnStatus stat = reader.ReadFile("filename.stp");
1405 Loading the file only memorizes the data, it does not translate it.
1407 @subsubsection occt_step_7_1_2 Checking the loaded STEP file
1408 This step is not obligatory. See a description of this step in section <a href="#occt_step_2_3_2">Checking the STEP file</a>.
1410 @subsubsection occt_step_7_1_3 Setting the parameters for translation to XDE
1411 See a description of this step in section <a href="#occt_step_2_3_3">Setting the translation parameters</a>.
1413 In addition, the following parameters can be set for XDE translation of attributes:
1414 * Parameter for transferring colors:
1416 reader.SetColorMode(mode);
1417 // mode can be Standard_True or Standard_False
1419 * Parameter for transferring names:
1421 reader.SetNameMode(mode);
1422 // mode can be Standard_True or Standard_False
1424 @subsubsection occt_step_7_1_4 Performing the translation of a STEP file to XDE
1425 The following function performs a translation of the whole document:
1427 Standard_Boolean ok = reader.Transfer(doc);
1429 where *doc* is a variable which contains a handle to the output document and should have a type *Handle(TDocStd_Document)*.
1430 @subsubsection occt_step_7_1_5 Initializing the process of translation from XDE to STEP
1431 Here is how to initialize the process:
1433 STEPCAFControl_Writer aWriter(XSDRAW::Session(),Standard_False);
1435 @subsubsection occt_step_7_1_6 Setting the parameters for translation from XDE to STEP
1437 The following parameters can be set for a translation of attributes to STEP:
1438 * Parameter for transferring colors:
1440 aWriter.SetColorMode(mode);
1441 // mode can be Standard_True or Standard_False
1443 * Parameter for transferring names:
1445 aWriter.SetNameMode(mode);
1446 // mode can be Standard_True or Standard_False
1448 @subsubsection occt_step_7_1_7 Performing the translation of an XDE document to STEP
1449 You can perform the translation of document by calling the function:
1451 IFSelect_ReturnStatus aRetSt = aWriter.Transfer(doc);
1453 where *doc* is a variable, which contains a handle to the input document for transferring and should have a type *Handle(TDocStd_Document)*.
1455 @subsubsection occt_step_7_18 Writing a STEP file
1456 Write a STEP file with:
1458 IFSelect_ReturnStatus statw = aWriter.WriteFile("filename.stp");
1462 IFSelect_ReturnStatus statw = writer.WriteFile (S);
1464 where *S* is *OStream*.