How To Use Step BOXML Writer APIs for writing of part or assembly in STEP BOXML

Table Of Contents:

• Guidelines Guidelines
• Initialisation, settings Initialisation, settings
  • Writing STEP BOXML compressed files Writing STEP BOXML compressed files
• Writing Products Writing Products
  • General sequence for writing a product General sequence for writing a product
  • Individual Metadata Individual Metadata
  • Attributes of Dtk_Info Attributes of Dtk_Info
• A Small Sample. A Small Sample.

---

Guidelines

This part of STEP has been introduced with the protocol AP242. Its initial name was Business Objects XML (BOXML). From AP242 Edition 2 (AP242E2), it is Domain Model . In the text, the term BOXML is generally used. Also it can be shortened as STEP XML.

STEP BOXML is NOT a XML form of the already defined AP242 (as defined by Part 28). It is based on another schema, to address new domains, of PLM, with intense semantic content.

Its first object is to convey products as parts and assembly, with PDM data. It is planned to be completed by other data, addressing various domains : kinematics, electrical harness, etc. But many data, like geometry, tessellation, etc, are conveyed in separate files.

STEP BOXML describes Products, as single parts or assemblies (an assembly has a list of instances of other products, each one with a position), with Product Data (and PDM data in general), and additional data like user defined attributes, data for domains like kinematics, electrical harness, etc. While, for each product, data like geometry are written in a separate file : this additional file can be called "side car file", here we call it "geometry file".

Hence, writing STEP BOXML goes together with writing 3D data in separate files, generally STEP (Part21) then referencing them from the products written in the STEP BOXML file.

An assembly written in STEP BOXML can be written in one STEP BOXML file for all ("perpart" mode), or in several STEP BOXML files, one per product ("nested" mode).

There must be one root product in a STEP BOXML file (just one single part, or one root assembly with no instance on it, all other products to be instanced in assemblies).

Remark : some settings are common with STEP writing functions.

Initialisation, settings

A complete STEP BOXML writing session starts by initialising it : opening a file, specifying a version of STEP BOXML.

As Products written in STEP BOXML may use another file ("geometry file"), it goes together with another writing sequence for these geometry files, which are then referenced from the BOXML file. For STEP BOXML, the need is to know, for each Product, its geometry file name (file name with no path). STEP is recommended for geometry files, but other formats are accepted as well.

Then, the content is written (Products as leaf parts or assemblies, with metadata, etc).

Finally, the STEP BOXML writing session is closed.

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.

stepw_boxml_InitGeneral  ( L"D:\\temp\\RootProduct.stpx" , "user");

Here above, no version of STEP BOXML is specified : a default is determined, it is 1. (0 for AP242E1 (Edition 1) , 1 for AP242E1TC (Edition 1 Technical Corrigendum) , 2 for AP242E2 (Edition 2) ).

Here below, a version of STEP BOXML is specified.

int step_boxml_version = 2;
stepw_boxml_InitGeneral  ( L"D:\\temp\\RootProduct.stpx" , "user", step_boxml_version);

Values of step_boxml_version can be
- 0 : AP242E1 (Edition 1)
- 1 : AP242E1TC (Edition 1 + Technical Corrigendum) : the default when absent
- 2 : AP242E2 (Edition 2)

When geometry files are STEP files, it is recommended to use : AP242E1TC with STEP as AP242E1, AP242E2 with STEP as AP242E2.

Then write the product structure. Detail hereafter : Products can be single parts or assemblies. Generally, a single part has a geometry file, an assembly has a list of instance of other products (either single parts or sub-assembies).

Details in following sections.

Finally, close the STEP BOXML writing

stepw_boxml_EndFile();

Writing STEP BOXML compressed files

Setting is same as for STEP. Compressed STEP BOXML files have extension as "stpxZ". References to STEP BOXML files are ALWAYS for basic name (without final Z), it is the same rule as for STEP : the reader then searches for firstly the non compressed file, then for the compressed file.

Specifying content of Header

in progress

Specifying Context of Products

in progress

Writing Products

This section tells about product definition, for the cases of single part and of assembly. It introduces the references to files : external references for "nested" writing, geometry files.

For each product, it is specified if it is written in the root file (defined when calling stepw_boxml_InitGeneral), or in a separate STEP BOXML file.

If EACH product is written in a separate STEP BOXML file, it is "nested mode". If ALL products are written in the SAME STEP BOXML file, it is "per part mode" (or "all in 1" mode). The ROOT Product must be declared "written in a STEP BOXML file", it defines the root file. NO MIXED CASE is allowed, this could be rejected or wrongly intepreted by readers.

Products can be written in any order, but when writing an assembly, its instanced sub-products must have been already initialised. It is for instance possible to initialise all the products, then write them; or to start by writing the sub-parts .. then ending by the root assembly.

General sequence for writing a product

Firstly , open the product, declare it as separate file (for nested case) or not, then attach a geometry file if any. This stage is required to be done for a product instanced in an assembly, before declaring these instances.

Location of files is relative to that of the main file (defined with stepw_boxml_InitGeneral). So

• if a separate file is given as just file name like "part.stpx", it is written at same location (directory) as the main file
• if a separate file is given with a RELATIVE PATH like "subfile\\part.stpx", it is written in the defined sub-directory of the location of the main file, also the external reference specifies this relative file
• WARNING : this sub-directory must exist
• absolute paths are to be avoided, they are recorded with external references, this can cause problem when reading

IMPORTANT : the ROOT Product must be declared "InFile", the same file as given to InitGeneral but without path.

Remark : the geometry files are not checked, it is up to the user to check that they are present with their specified name.

    int ProdID;    // will identify this product in the next stages , filled by stepw_boxml_InitProduct.. functions
 
//    case of nested writing : one STEP BOXML file per product
    stepw_boxml_InitProductInFile("ProductName", ProdID, "ProductName.stpx");
 
//    case of one STEP BOXML file for all products
    stepw_boxml_InitProductSameFile("ProductName", ProdID);
 
//    then, when a geometry file is associated (case of a single part)
    stepw_boxml_SetGeometryFile (ProdID, "ProductGeom.stp", "STEP AP242", "solid geometry");

Remark : the root assembly must be written in the main STEP BOXML file ! (call stepw_boxml_SetProductFileSame).

For stepw_boxml_SetGeometryFile , here above, "STEP AP242" stands for the file format, "solid geometry" stands for the type of content. Allowed values are listed in the "Recommended Practices for STEP AP242 TC Business Object Model XML - Product & Assembly Structure", section 10 "Document and File Properties".

Then write the content of the product (metadata, proper data ..), not the instances of an assembly which come later.

    // Starting content of a product
    stepw_boxml_InitPart (ProdID);
 
//    For individual metadata
    Dtk_MetaData Property  ..;
    stepw_boxml_AddProperty(Property);
//    Some property names are reserved, see hereafter
 
//    For a Dtk_Info : used to bring  Validation Properties
    Dtk_Info ProdInfo  ..;
    stepw_boxml_SetProductInfo(ProdInfo);
//    See hereafter for supported attributes
 
    // Ending content of a product
    stepw_boxml_EndPart();

Then for an assembly write the instances of sub-products.

//  For an instance in an assembly
Dtk_transfo position ..;  // the relative position of the instanced sub-product
int ChildID ..;  // Product ID of the instanced sub-product
stepw_boxml_AddInstance (ProdID, ChildID, position, "instance_name");

Finally close the product.

// Final end for this product
stepw_boxml_EndProduct(ProdID);

Individual Metadata

By default, an individual metadata (Dtk_Metadata) is written as "used defined attribute".

According to its title, it can be interpreted as Product Data. Here is the list

• "Description" : attribute Description of entity PartVersion
• "Revision" : attribute ID of entity PartVersion
• "Life Cycle Stage" : attribute LifeCycleStage of the Context of the Part

Attributes of Dtk_Info

If a Dtk_Info is associated with a Product (by stepw_boxml_SetProductInfo), these attributes are written, they are validation properties attached to this product :

• "assembly validation property : : number of children" , must be an integer value
• "assembly validation property : : notional solid centroid" , must be a point ( Dtk_pnt ) (remark : these attributes are also defined with basic STEP writing).

A Small Sample.

In the example below :

• FilePath is the location (directory, full path) where the STEP BOXML files will be written.
• testcase : 1 for "all in same BOXML file", 2 for "nested"
• geometry files are written separately; in this example they are STEP files

Content of the model written :

• The example includes an simple assembly with 3 instances of 2 leaf parts.
• One of the leafs has an property (user defined attribute).
• The root assembly has validation properties recorded in a Dtk_Info.
• In "nested" mode, one of the parts is written in same location as the root file, the other is written in a sub-directory named "subfile".

     //  Test case 1 : assembly of 2 parts, perpart
     //  Test case 2 : assembly of 2 parts, nested
void stepw_boxml_component_testapi(const Dtk_string& FilePath, const int testcase)
{
     Dtk_string filename;
     if (testcase == 1) filename = "root_assy-perpart.stpx";
     else filename = "root_assy.stpx";
     //  InitFile : file with complete location
     Dtk_ErrorStatus stat;
     stat = stepw_boxml_InitGeneral(FilePath + filename, "user", 0);
     //  Sequence to be tested
     if (testcase == 1 || testcase == 2) {
          int id0, id1, id2;
          //  Root Assembly
          //  The root must be defined in first
          stat = stepw_boxml_InitProductInFile("root_assy", id0, filename);  // InFile REQUIRED on the root assembly
          //  For validation properties : via une Dtk_Info
          //  RequiresInitPart (as for AddProperty)
          stat = stepw_boxml_InitPart(id0);
          Dtk_Info ProdInfo0 = Dtk_Info::create();
          ProdInfo0->AddAttribute("assembly validation property :  : number of children", Dtk_Val(4));
          ProdInfo0->AddAttribute("assembly validation property :  : notional solid centroid", Dtk_Val(Dtk_pnt(30., 20., 10.)));
          stat = stepw_boxml_SetProductInfo(ProdInfo0);
          stat = stepw_boxml_EndPart();
 
          //  Part (leaf 1)
          if (testcase == 2) stat = stepw_boxml_InitProductInFile("Part1", id1, "part1.stpx");
          else stat = stepw_boxml_InitProductSameFile("Part1", id1);
          stat = stepw_boxml_SetGeometryFile(id1, "part1.stp", "STEP AP242", "solid geometry");
          stat = stepw_boxml_EndProduct(id1);
          //  Part (leaf 2) with a property (user defined attribute)
          if (testcase == 2) stat = stepw_boxml_InitProductInFile("Part2", id2, "subfile\\part2.stpx");
          else stat = stepw_boxml_InitProductSameFile("Part2", id2);
          stat = stepw_boxml_SetGeometryFile(id2, "part2.stp", "STEP AP242", "solid geometry");
          stat = stepw_boxml_InitPart(id2);
          Dtk_MetaData uda2 = Dtk_MetaData::CreateMetaData(Dtk_MetaData::TypeUserAttribute, "uda2", "this_is_a_text");
          stat = stepw_boxml_AddProperty(uda2);
          stat = stepw_boxml_EndPart();
          stat = stepw_boxml_EndProduct(id2);
 
          //  Instances of Parts in the assembly
          Dtk_transfo tr1;
          stat = stepw_boxml_AddInstance(id0, id1, tr1, "instance_1");
          Dtk_transfo tr2;
          tr2.setOrigin(Dtk_pnt(30., 20., 10.));
          stat = stepw_boxml_AddInstance(id0, id2, tr2, "instance_2A");
          Dtk_transfo tr3;
          tr3.setOrigin(Dtk_pnt(10., 20., 30.));
          stat = stepw_boxml_AddInstance(id0, id2, tr3, "instance_2B");
          stat = stepw_boxml_EndProduct(id0);
     }
     //  Fin sequence a tester
     stat = stepw_boxml_EndFile();
}