 |
DATAKIT API
V2025.1
|
|
|
DATAKIT API
V2025.1
|
|
A STEP file describes a PRODUCT. A Product can be 3D Part containing shells, wire frames, points .. or an Assembly. An Assembly contains a list of instances of other PRODUCTS which are its components : an instance is the association of a Product and a relative position of it in the containing assembly. These contained products can be themselves 3D parts or assemblies. So, a Product can be alone, or used in one or several instances, in one or several assemblies : it is written only once in the STEP file, then it can be used as many times as needed.
STEP allows a Product to be both a 3D Part or an Assembly. In practice an Assembly has no 3D directly attached, in such case an empty part is required to be written.
Geometry is described by Bodies (class Dtk_Body). A 3D Part can contain one or several Bodies, or none if it is empty.
Each PRODUCT is required to be designated by a UNIQUE PRODUCT NAME, it is the key for identification in assemblies. Product Names define the nomenclature of the product set being written.
The difference between a simple Part and an Assembly is that for an Assembly, the 3D Part can be empty (but it is required) and its components are written and instances are added before writing the 3D Part.
Some entities are self-sufficient : for instance a Body (as described by a Dtk_Body) contains all the required data and information to write it (topology, geometry, graphical attributes like colors ..).
Some other entities combine an inner description and references to other entities. For instance a FDT (described by a Dtk_Fdt) brings its own description (graphical and semantic) which is completed by references to entities (like faces of a body), detained by another written entity (here, a Dtk_Body). Samely, a View (as Dtk_ModelDisplay) has its own data (camera ..) but its complete definition also includes a list of entities to be viewed (a list of Dtk_Fdt) which are written separately.
The combination of an Entity, the references which go with it (from this entity to others), and an Identifier to allow references to it defines a NODE. So
If an Entity is not written in the scope of a Node, it cannot have references to other entities, nor be referenced as a whole (with its Node ID) from another Node. An Entity can be directly referenced with its Entity ID if it is defined (in its Dtk_Info).
References from a Node can be :
By default, a Reference applies in the same Product. In the case of an assembly, it is possible to define a Reference to an entity of another Product, by defining an Instance Path.
This topic is especially developped in Writing FDT and Views in STEP.
This documentation explains how to write data to STEP : sequence of calls, settings, for the different possible cases.
An important topic is external references : basically, a STEP model, single part or assembly, can be written in one file. STEP also allows to write products in different files, then the assembly using these external files. External references are considered as a whole (for an assembly to the components it contains as instances), or to elements, as "External Element References" (for a FDT defined at assembly level, which has links to geometric items inside sub-components of the assembly).
So, to keep the explanations clears, they distinguish
Additional informations are given in annexes :
In the examples below, some parts of code are repeated (explained the first time, then reused in other examples). Repeated codes are noted in italic.
A complete STEP writing session starts by initalising it : opening a file, specifying a version of STEP. Then (just after), setting the writing modes if needed (otherwise, defaults will apply).
Then the content is written.
Finally, the STEP writing session is closed.
Here below an example.
Firstly, create Document and start STEP writing : give file name and identification of sending software (here below " sample ") Also, a version of STEP can be specified.
Here above, no version of STEP is specified : a default is determined, it is 2 (for AP214) in general, 4 (for AP242 Edition 1) when writing of FDT is specified. Some types of data require a given version of STEP, otherwise they are not written. Some types of data are better fit for a given version of STEP, even if others can also apply for them. The following examples precise the required or recommended values for each type of data.
Here below, a version of STEP is specified.
Values of step_version can be - 0 : default, as when not given, it is then computed from the settings - 1 : AP203 (first edition). This version is limited to geometry-topology and assemblies : no color, no FDT .. - 2 : AP214. This version also supports colors - also FDT but few STEP AP214 readers support FDT on reading - 3 : AP203E2 (Edition 2). This version also supports FDT, it is set by default when FDT mode is set. - 4 : AP242 (Edition 1). This version is the most complete. Among others, it supports a wider set of definitions for FDT, enhanced capabilities for external references, a really efficient tessellation .. Now ISO (IS) from year 2014. - 5 : AP242E3 (Edition 3). Continued enhancements on AP242, especially on FDT. Now ISO (IS) from year 2023. ( before 2023, value 5 was for AP242E2 (Edition 2) introduced in 2020 and replaced by Edition 3 in 2023)
Then (just after stepw_InitFile) set modes for STEP writing
Then write the Product Detailed hereafter : cases of Single Part and of Assembly
Finally, close the STEP writing
Mode functions are to be called before starting the writing (call to stepw_InitFile). Some can be called just after this call.
Some apply on products, they be called at any time and apply to the products which follow.
For each mode, a dedicated paragraph explains it (effect, values allowed).
The Annex A : Available modes for writing STEP files lists the available modes with values, effect, and condition of call.
STEP files are written according to STEP Part21 specifications. It is also possible to write STEP files as compressed, with extension stpZ , according to Recommended Practices for STEP File Compression (V1.0) from CAX-IF (the compression algorithm is pkzip).
The compressed writing is commanded by setting the compression mode, it is modal : it applies to all STEP writings which follow the call (including external references if any).
Remark : file names given as external references SHALL NOT have extrension stpZ, this is managed by the writer.
The function is stepw_SetModeCompress , it has to be called before stepw_InitFile.
Firstly, activate the compress mode
Then start the STEP writing itself (repeated)
The starting function stepw_InitFile allows to specify the field Origin of the header (in second argument). If this argument is given empty, the previously given one applies, if none has been given it is empty.
It is also possible to specify other fields of the STEP header : this specification is modal (applies to all files written afterwards).
If these fields are not specified, defaults apply.
5 fields of the Step Header can be edited : Description, Author, Organization, Originating System, Authorization. This is done by calling the function stepw_SetHeaderData, with a string :
Firstly, set the values for the header
Then start writing the file(s). Each writing session can define its Origin field, here "sample" If the argument Origin is empty, the previously defined one applies. stepw_InitFile( L"C:\\temp\\RootProduct.step", " sample "); or with a Dtk_string :
Each product is defined with a context. This context defines Units of Length and of Angle, and geometrical uncertainty. Defaults are : Length = Millimeter , Angle = Radian , uncertainty = 0.005.
This context can be changed. Setting is modal : it applies to all products defined afterwards. For each product, its context is defined at the time of calling stepw_InitProduct.
Units can be choosen among a defined list of values, they are not arbitrary. For Length : MM CM M KM INCH FOOT . For Angle : Radian Degree.
For Unit, there are 2 possibilities :
Each call to stepw_SetContextUnit/stepw_SetConversionLengthUnit or stepw_SetContextTolerance defines a new context for the following calls to stepw_InitProduct.
This sections tells about writing a single part. It is the basis, it will be reused for assemblies, for FDT (within a Part) .. FDT are explained separately, because they introduce specific notions.
There are also ANNEXES about data attached to the part and its geometry
A single part is a product which is self-contained, while an assembly is a product which is composed of other products. Each product has a name, which is unique in the STEP model. The STEP writer allocates an identifier to this product, which is then used by the application to handle it.
Firstly, start the writing of the part
Then, writing the content of the part : examples are given after. Finally, end writing the product
The value of PartID can then be used by the application if this part is used in an assembly (see after, examples of assemblies)
Important Notice * Product Name must be UNIQUE in a step model. To be sure, call the function stepw_GiveUniqueProductName. If the name is already used in the current step writing session, it will be suffixed, by "--i" whereas i is an integer (–2 –3 etc).
It can then be used for stepw_InitProduct.
The function stepw_Write3DPartBody takes a Dtk_Body with its content : geometry, topologies, colors, layers, names of items, attributes on the body or on items ..
Firstly, start writing a Part (repeated).
Here, the specific action to write a Dtk_Body
Then the usual end of a Part (repeated).
The way is similar as above : between stepw_Init3DPart and stepw_End3DPart, call stepw_Write3DPartBody for each Dtk_Body to be written.
The result of Tessellation is recorded in a Dtk_mesh. A Dtk_mesh can contain surfacic meshing, organised as a list of Dtk_MeshFace, wireframe meshing (independent curves and points). When the Tessellation has been computed from a Dtk_Body, a Dtk_MeshFace can have a reference to topoligical Face it comes from.
A Dtk_mesh can be written alone, or associated with the Dtk_Body it has been computed from. When written alone, if computed from a Dtk_Body by the Tessellation Library of DtkAPI, it can be written as "from the Body", to redirect the geometric links on items of the Body, to items of the Mesh.
Writing surfacic Tessellation is not recommended in STEP versions before AP242. AP242 brings a much more efficient description of tessellated data, and the capability to keep their association with topological data they come from. Using previous versions (AP203 or AP214) results in poorer data, and moreover very bigger files !
Subcase 1 : writing a Dtk_mesh alone
Subcase 2 : writing a Dtk_mesh together with the Dtk_Body it comes from. It is assumed that informations of original items are recorded for each tessellation item.
Subcase 3 : writing a Dtk_mesh alone, with information of the Dtk_Body it comes from. This allows geometric links (for instance from a FDT) to items of the Body to be redirected on the items of the Mesh instead It is assumed that informations of original items are recorded for each tessellation item : the Tessellation Library of DtkAPI records references from computed Dtk_Meshface to original Dtk_Face.
A Product can contain construction geometries. A construction geometry is written as a body, but it is qualified as construction geometry. It can contain infinite curves or faces.
Remark about infinite entities (planes or unbounded faces on planes, lines as untrimmed ..) : They may not be written as basic geometry of a STEP model, they have to be written as construction geometries.
A Product can contains axis systems.
This applies to the case of an assembly (the main assembly or any sub-assembly).
Firstly is the basic example of writing an assembly. Variants and complements are for external references, FDT in assembly, etc, they are explained in separate sections to keep this basis simple.
An assembly is a product which contains instances of other products.
Each instance in the assembly is defined by a component and a relative location (transformation matrix), it can have an instance name. A component is another product. Each product is identified by its PartID, provided by stepw_InitProduct.
Here below a sequence of writing an assembly. The products used as components can be written before the assembly, or after starting the assembly (stepw_InitProduct), but BEFORE the instances (stepw_AddInstance).
Each Product is written separately and completely then attached to a container product if needed. The global sequence is :
Generally, an assembly contains only instances of other products. But it can contain specific geometry, etc.
Firstly, case of an assembly without any specific data.
When the assembly node itself has a specific content. It can be written as for a Part, between stepw_Init3DPart and stepw_End3DPart.
As for a Product (part or assembly) or as for a Body or a geometric item, it is possible to write attributes attached to an Instance (of a component in an assembly).
In a similar way, attributes are recorded in a Dtk_Info. So, the sequence is to
To fill the attributes in the Dtk_Info, see the dedicated Annex C : Writing Attributes.
Remarks :
It is possible to write a STEP model in several files, by specifying different files for some or all Products (except the root product, which is written in the main file, given to stepw_InitFile). If an assembly has instances of products written in different files, external references are written to link the files.
External STEP files are written in the same location (file path) as the main file : only root name and extension are specified.
Warning : External files must be STEP. The possibility to have references to non-STEP files will be addressed when recommended practices will be commonly agreed and published.
Important remark : not every combination is permitted. Two are possible :
If no external reference is used, the writing is said "monolithic".
Other combinations can lead to an inconsistent result.
There must be a unique name for each additional STEP file.
When writing an assembly with external references to its leaf parts, it is also possible to consider the leaf parts already written and not rewrite them :
Here is explained how to write a STEP file with external references, in the basic case i.e. the case of FDT in assembly is seen separately, later.
Writing a Part as external file : declaration (repeated).<i>
Specific action : declare this Part as external
Then Writing the Part, as usual (repeated).
To ensure that name of STEP files are unique, the function stepw_GiveUniqueFileName can be used.
FDT in STEP are a combinatory subject, so they are covered by several paragraphs :
Writing a FDT in STEP involves to
This is made by defining a Node, with a Node Identifier (a positive integer value, unique in the scope of a Product, so within a sequence stepw_Init3DPart .. stepw_End3DPart). So in the scope of the Node, the FDT and the References to geometrical items are written.
Starting a Node :
Writing the FDT itself (more details below)
Writing the References to geometries (example; more details below)
Closing the Node
Remarks
For a View, a similar sequence apply (see Writing Views)
Additional sections concern : Construction Geometries, Axis Systems (seen in the section Case of a single part) , Views (seen below).
In STEP, description of FDT strongly separate the GRAPHICAL data : the PRESENTATION, and the SEMANTIC data : the REPRESENTATION. Both can be related to geometry (semantic data must be) and to each other.
Definitions for FDT were already in AP214, then AP203E2 (Edition 2), a first implementation was done on AP203E2. However, tests done in the frame of CAX-IF and LOTAR have showed limitations and drawbacks, so these definitions have been completed and reworked for AP242, which is the most complete.
This concerns
This leads to several combinations to be supported :
With AP203E2 and AP214, the semantics can be written only with "character based presentation", the graphics alone can be written as "character based" or "polyline". AP242 introduces "tessellated presentation" and allows to write any kind of graphics, alone or associated with semantics; also the mode "charactyer based" is deprecated. In addition, a "minimal presentation" is in discussion but not yet specified.
Types of presentation (graphics of FDT) :
Links to geometries : they are based on the identifiers attached to geometric items provided by the original model, recorded in their Dtk_Info as GetId. So the identifiers are provided by the user.
To write a FDT in a Part, the sequence is :
Initially, start the STEP writing itself (repeated)
Firstly, Global setting of parameters to write FDTs
Then Writing a Part with FDT (repeated)
Just after the product is declared, specify it as an anchor
Then Start write the Part (repeated)
Then Write a FDT in the Part
Remarks :
Remark about stepw_AddReference : it replaces the previous call to stepw_Add3dPartFdt with a Dtk_Fdt + a stepw_ER.
They complete the main functions already explained :
It is possible to enforce a graphical presentation of a FDT, computed separately. This can be done by creating a second FDT, used only for the graphical definition, while the original FDT is used only for the semantic definition.
Remark : if the "dual presentation" is selected for graphical output, the placeholder presentation is computed from the PartFdt, the tessellated presentation from the GraphicalFdt. So it is assumed in that case, that PartFdt is suitable to produce a correct placeholder presentation.
In STEP, the term "View" corresponds to Model Display or Capture.
A View can contain some or all the FDTs written in the STEP model. It contains the complete 3D model. A View is written in a Product - between stepw_Init3DPart and stepw_End3DPart. Typically the root product.
- Example, a View which contains all the FDTs
- Example, a View which contains some FDTs
Warning : according to STEP recommended practices on Views and FDT, a FDT has to be listed in at least one View. A FDT which is not listed in any View will be enforced to be, in the last view recorded in the same Component (Part or Assembly).
Remark about stepw_AddReference : it replaces the previous call to stepw_Add3DFdtModelDisplay with a Dtk_ModelDisplay + Dtk_Fdt.
A FDT in Assembly : it is a FDT defined in a Product which is an Assembly, and with geometric links to sub-parts of this assembly.
Sub-Part of an assembly : an instance of a Product at any level in the assembly tree; this defines an instance path, starting from the root product which contains the FDT. An instance path can have one or more levels of instances (sub-assemblies + final part). The instance path may not start from a container of the product which contains the FDT.
So, to write a FDT in Assembly :
So, links from FDT to geometries introduce user identifiers for INSTANCES in Assemblies, added to them for geometric items in Parts.
For each Product which contains geometric items used by a FDT Start writing the product (repeated)<i>
and specifiy it as anchor (specific for FDT)
Write the content of the product, as usual (bodies, etc)
In this example, an intermediate sub-assembly is introduced in order to illustrate an instance path at several levels.
Now, write the assembly itself (repeated)
When all the instances have been written : Write the part for this assembly, with its FDT in assembly, views if any ..
Finally, close the Product (repeated)
Remarks :
The principle is the same as for Writing a FDT in Assembly, in a monolithic file. Difference lies in the geometric links : in a monolithic file, geometric items (faces, ..) are directly pointed with the file, even if among several products.
With external references, the additional need is to make the geometric item "visible" from another file : the file written for the part has to specify which entities are "visible" from other models. This entities are "ANCHOR ENTITIES".
Geometric Links to Anchor Entities are called : External Element References.
(in a monolithic file, all items of a part are visible within this file, with external references the need is to have an explicit list).
With basic external references, all sub-assemblies and instances remain visible within the main file.
Changes from the previous case are, on the Part which contains geometric items to be specified anchors :
In a Product (typically a leaf part), an ANCHOR ENTITY is defined by :
Start writing the product (repeated)
Specify the geometric link for external reference
Continue the writing (repeated)
Remark : anchor entities can be specified in a monolithic file, but they are then ignored.
The difference from previous case is that, here the instances are not longer in the main file, except the instances defined at root level.
Previously, when writing STEP the instances were directly used within the main file.
With "nested external references", instances can be in the main file or in other files. To identify them, it is necessary to write them with a unique identifier. As for anchor entities, this identifier is a string, required to be unique (in the Assembly) and stable.
When defined, "reference designator" of instances is written in STEP, but they are used (on reading) only in the case of "nested external references".
The code for writing the Part, the Sub-Assembly(ies), the Main Assembly, is unchanged
except the reference designator of the instance, required and to be unique.
As a summary, here is the complete example, it applies in every case. Differences are only about definition of external references.
This complete example requires unique (string) IDs for : anchor entities, instances - these IDs are used through external references, unuse within a same file.
For each Product which contains geometric items used by a FDT : starting repeated<i>
Specify this product as external reference
Declare the product for writing (repeated)
Specify the geometric link for external reference
Then write the content of the Product (repeated)
In case of nested external reference : the sub-assembly is written in an external file
Continue : Write the sub-assembly, the main assembly with its FDT(repeated)
Functions which set mode have a modal effect : the value of a setting is unchanged if the function is not called again.
Some functions apply to the writing itself : they must be called before stepw_InitFile which starts the writing session.
Some functions drive a general working mode : they can be called before or just after stepw_InitFile, but not after first specific call (starting by stepw_InitProduct).
Some functions can be called at any time, they apply on the following actions : the impacted actions are indicated. For instance, for a setting which is managed by stepw_InitProduct, its change applies on the calls to stepw_InitProduct which follow.
To be called before stepw_InitFile
To be called before or just after stepw_InitFile
Mode to write FDT. Function : stepw_SetModeFdt
Warning : this mode is under control of a licence. If the licence is not active, this function has no effect
Taken into account by folllowing calls to step_InitProduct
Some data can be attached to the Body itself, added to geometry and topology. They are recorded in the Dtk_Info attached to the Dtk_Body itself and to each of its items. See the mapping table for details.
These data are :
The Annex C explains how to define attributes in the Dtk_Info to be written in STEP.
STEP allows to attach properties to various kind of data : products, instances (in an assembly), bodies, items in bodies (like faces) ... These properties have definitions specific to STEP, explained here below.
To write properties attached to an item into STEP, they have to be recorded in its Dtk_Info, as Dtk_Val. So, for items which are given directly, their properties are taken from their Dtk_Info : bodies, faces, FDT, etc For items written with specific calls, additional functions allow to specify a Dtk_Info which brings the attributes to write.
In addition, Metadata ( class Dtk_Metadata ) can be attached to components or bodies, they concern high level attributes attached to a whole product or a whole body, including product data. Detailed in : Metadata.
STEP provides a general mechanism to attach properties to any item. Here is a simplified presentation, focused on the case of attributes.
Properties addressed in STEP this way can be
The type of value can be of any kind, in practice it can be
A property can be attached to a large variety of STEP entities :
Properties are organized in sets of PROPERTY_DEFINITION, each of them having a list of properties represented by .. REPRESENTATION, finally the values of properties are items of the REPRESENTATION.
In practice, the matter is the NAMES of these different entities, rather than the organization of entities themselves : for instance, for geometric validation properties on a given solid, there is one PROPERTY_DEFINITION per property, its representation is named "volume" "surface area" etc.. respectively, rather than one PROPERTY_DEFINITION for all the geometric validation properties.
A property in STEP is identified by 3 terms :
These 3 names are independent.
For instance with material designation, this property is a TEXT, definition name is "material property", representation name is "material name", while item name provides the Material ID (in a database) and its value is a TEXT which provides the common name.
As a conclusion
Rules of grouping : for a given entity, properties with same names for definition and representation (which can empty) are gathered in STEP in a same property set.
Letting aside the case of cloud of points, this is well mapped as follows :
Examples of property name, defined in the Title of the Dtk_Val :
Metadata are reserved for really general informations (like data for PDM, etc, attached to a Product).
For various types of entities, it's enough to fill the Dtk_Info of the entity, the STEP writer then gets them for writing :
For a component (leaf or assembly node), the Dtk_Info has to be explicitly given to the STEP writer, 2 possible attachments :
Here below, info is a Dtk_Info
For an instance, the Dtk_Info has to be explicitly given to the STEP writer, with a variant of AddInstance in replacement of stepw_AddInstance, with the Dtk_Info as additional parameter.
Properties are attached to the NAUO or to the PDS, according to the recommended practices for validation properties, otherwise it is on the NAUO.
Only the Dtk_Val with title defined as "definition : representation : item" (like "geometric validation property : volume : volume measure") or "definition : representation : item : num" (with different "num", to have several properties with same names) are written to STEP properties.
Metadata can be used to describe attributes of various kinds attached to products or bodies.
By default, Metadata are attached to products. It is possible to attach them to sub-parts of a product.
For STEP writing, there are are several kinds of metadata, according to their TYPE of MetaData, and to their TITLE. This is why a specific setting allows the user to filter the writing of properties as metadata : by calling stepw_SetModeProp.
To write MetaData, firstly activate the writing mode, can be done before or just after each call to stepw_InitProduct :
Then specify to which item the Metadata is attached.
To record the MetaData to the Product being written, the call is to be done just after the call to stepw_Init3DPart :
To record the MetaData to the next Body or Mesh to be written :
Once the body or mesh has been written, the effect of stepw_InitPropertySet is over. Coming Metadata will then be attached to the product, unless stepw_InitPropertySet is called again.
This example calls functions used for creation of bodies and FDT which are not here (they are general) :