STEPmod utilities

Purpose

The stepmod-utils Ruby gem provides a number of tools to work with the STEPmod repository.

Installation

gem install stepmod-utils

Or include it in your gemspec.

Usage

EXPRESS schema validation

This command uses Expressir to validate all EXPRESS schemas listed in the {stepmod}/repository_index.xml file.

There is a SHOULD_REWRITE constant that can be switched in the code which allows overwriting of the EXPRESS schemas into a pretty-printed format.

Warning

The SHOULD_REWRITE function is turned off because Expressir currently does not support outputting remarks, and some of the pretty-printed schemas will fail validation.

$ stepmod-validate-express {stepmod-directory}

Output:

Validating all EXPRESS schema files listed in:
repository_index.xml

NOTE: SHOULD_REWRITE mode is turned OFF
validating: ./data/modules/activity/arm.exp
validated : ./data/modules/activity/arm.exp
validating: ./data/modules/activity/mim.exp
validated : ./data/modules/activity/mim.exp
validating: ./data/modules/activity_as_realized/arm.exp
validated : ./data/modules/activity_as_realized/arm.exp
validating: ./data/modules/activity_as_realized/mim.exp
validated : ./data/modules/activity_as_realized/mim.exp
...
The following schemas failed validation:
SCHEMA: data/resources/geometric_model_schema/geometric_model_schema.exp

Generating Annotated EXPRESS

This command takes the STEPmod directory and parses its XML to synthesize with the target EXPRESS schemas to migrate into Annotated EXPRESS schemas.

Given the following schemas:

Simple EXPRESS schema: {stepmod-root-dir}/data/resources/action_schema/action_schema.exp
Output of Annotated EXPRESS schema: {schemas-output-dir}/action_schema/action_schema.exp

Command:

$ bundle exec stepmod-annotate-all \
  --stepmod-dir {stepmod-root-dir} \
  --output {schemas-output-dir}

e.g.

$ bundle exec stepmod-annotate-all \
  --stepmod-dir ./iso-10303-stepmod-wg12 \
  --output schemas

Output:

$ bundle exec stepmod-annotate-all --stepmod-dir iso-10303-stepmod-wg12 --output schemas
[stepmod-utils] STEPmod data path: `iso-10303-stepmod-wg12`
[stepmod-utils] SRL schemas output path: `schemas`
5760: `iso-10303-stepmod-wg12/data/modules/activity/arm.exp` processing...
5760: Written to: `schemas/activity/arm.exp`
5760: Done processing `arm.exp` => `schemas/activity/arm.exp`
5760: `iso-10303-stepmod-wg12/data/modules/activity/mim.exp` processing...
5760: Written to: `schemas/activity/mim.exp`
5760: Done processing `mim.exp` => `schemas/activity/mim.exp`
5760: `iso-10303-stepmod-wg12/data/modules/activity_as_realized/arm.exp` processing...
5760: Written to: `schemas/activity_as_realized/arm.exp`
5760: Done processing `arm.exp` => `schemas/activity_as_realized/arm.exp`
5760: `iso-10303-stepmod-wg12/data/modules/activity_as_realized/mim.exp` processing...
5760: Written to: `schemas/activity_as_realized/mim.exp`
5760: Done processing `mim.exp` => `schemas/activity_as_realized/mim.exp`
5760: `iso-10303-stepmod-wg12/data/modules/activity_characterized/arm.exp` processing...
5760: Written to: `schemas/activity_characterized/arm.exp`
...

ISO 10303-2 concepts extraction

$ bundle exec stepmod-extract-concepts \
  -p ./data \
  -i ./repository_index.xml \
  -o ./output-yaml

Then these files will be created:

031-generated-terms.adoc all terms extracted
991-generated-bibliography.adoc all bibliographic sources where the terms come from

If the STEPmod repository is a Git repository, term extract will work.

Sample output:

[stepmod-utils] INFO: STEPmod directory set to ../iso-10303-stepmod.
[stepmod-utils] INFO: Detecting paths...
[stepmod-utils] INFO: Processing XML file data/application_protocols/boundary_representation_for_iso_14306_open_jt/application_protocol.xml
[stepmod-utils] INFO: skipped ISO/CD 10303-243 as it is not IS, DIS or TS
[stepmod-utils] INFO: Processing XML file data/application_protocols/configuration_control_3d_design_ed2/application_protocol.xml
[stepmod-utils] INFO: Completed processing XML file data/application_protocols/configuration_control_3d_design_ed2/application_protocol.xml
[stepmod-utils] INFO: Processing XML file data/application_protocols/electronic_assembly_interconnect_and_packaging_design/application_protocol.xml
[stepmod-utils] INFO: skipped ISO/CD 10303-210:2019 as it is not IS, DIS or TS
[stepmod-utils] INFO: Processing XML file data/application_protocols/functional_data_and_their_schematic_representation_for_process_plant/application_protocol.xml
[stepmod-utils] INFO: Completed processing XML file data/application_protocols/functional_data_and_their_schematic_representation_for_process_plant/application_protocol.xml
...

Creating the SRL

The single command to create the SRL from the STEPmod repository is as follows.

The command also takes the --stepmod2mn-path {path} option to specify the location of the stepmod2mn.jar file. If it is not specified, or the path doesn’t exist, the command will automatically download the latest release of it to use.

$ bundle exec stepmod-srl-migrate \
    --srl-schemas-dir {path-to-new-srl-schemas} \
    --srl-docs-dir {path-to-new-srl-documents} \
    --stepmod-dir {stepmod-root-path}

e.g.

$ bundle exec stepmod-srl-migrate \
    --srl-schemas-dir schemas \
    --srl-docs-dir documents \
    --stepmod-dir iso-10303-stepmod-wg12

Output:

To use retry middleware with Faraday v2.0+, install `faraday-retry` gem
[stepmod-utils] `stepmod2mn.jar` path: `/Users/mulgogi/src/mn/iso-10303-srl/stepmod2mn-1.25.jar`
[stepmod-utils] STEPmod path: `iso-10303-stepmod-wg12`
[stepmod-utils] SRL output schemas directory path: `schemas`
[stepmod-utils] SRL output documents directory path: `documents`
[stepmod-utils] ******************************
[stepmod-utils] [SRL MIGRATION] Migration starts!
[stepmod-utils] ******************************
[stepmod-utils] [SRL MIGRATION: stepmod2mn.jar] START document migration and SVG generation.
[stepmod-utils] ******************************
stepmod2mn Generate SVG file for iso-10303-stepmod-wg12/data/resource_docs/systems_engineering_representation/schema_diagexpg1.xml...
SVG saved in documents/systems_engineering_representation/schema_diagexpg1.svg.
Generate SVG file for iso-10303-stepmod-wg12/data/resource_docs/fundamentals_of_product_description_and_support/schema_diagexpg1.xml...
SVG saved in documents/fundamentals_of_product_description_and_support/schema_diagexpg1.svg.
Generate SVG file for iso-10303-stepmod-wg12/data/resource_docs/mathematical_representation/schema_diagexpg1.xml...
...
Generate SVG file for iso-10303-stepmod-wg12/data/modules/assembly_module_with_subassembly/mimexpg2.xml...
SVG saved in documents/assembly_module_with_subassembly/mimexpg2.svg.
End!
[stepmod-utils] ******************************
[stepmod-utils] [SRL MIGRATION: stepmod2mn.jar] COMPLETE document migration and SVG generation.
[stepmod-utils] ******************************
[stepmod-utils] [SRL MIGRATION: stepmod-utils] START Annotated EXPRESS generation.
[stepmod-utils] ******************************
[stepmod-utils] STEPmod data path: `iso-10303-stepmod-wg12`
[stepmod-utils] SRL schemas output path: `schemas`
5720: `iso-10303-stepmod-wg12/data/modules/activity/arm.exp` processing...
5720: Written to: `schemas/activity/arm.exp`
5720: Done processing `arm.exp` => `schemas/activity/arm.exp`
5720: `iso-10303-stepmod-wg12/data/modules/activity/mim.exp` processing...
5720: Written to: `schemas/activity/mim.exp`
5720: Done processing `mim.exp` => `schemas/activity/mim.exp`
5720: `iso-10303-stepmod-wg12/data/modules/activity_as_realized/arm.exp` processing...
...
5720: Done processing `mim.exp` => `schemas/zonal_breakdown/mim.exp`
5720: `iso-10303-stepmod-wg12/data/resources/action_and_model_relationships_schema/action_and_model_relationships_schema.exp` processing...
5720: Written to: `schemas/action_and_model_relationships_schema/action_and_model_relationships_schema.exp`
5720:     Copy image SKIPPED for `schemas/action_and_model_relationships_schema/action_and_model_relationships_schemaexpg1.svg` as it exists.
5720:     Copy image SKIPPED for `schemas/action_and_model_relationships_schema/action_and_model_relationships_schemaexpg2.svg` as it exists.
5720: Done processing `action_and_model_relationships_schema.exp` => `schemas/action_and_model_relationships_schema/action_and_model_relationships_schema.exp`
5720: `iso-10303-stepmod-wg12/data/resources/action_schema/action_schema.exp` processing...
5720: Written to: `schemas/action_schema/action_schema.exp`
5720:     Copy image SKIPPED for `schemas/action_schema/action_schemaexpg1.svg` as it exists.
5720:     Copy image SKIPPED for `schemas/action_schema/action_schemaexpg2.svg` as it exists.
5720: Done processing `action_schema.exp` => `schemas/action_schema/action_schema.exp`
5720: `iso-10303-stepmod-wg12/data/resources/aic_advanced_brep/aic_advanced_brep.exp` processing...
5720: Written to: `schemas/aic_advanced_brep/aic_advanced_brep.exp`
5720: Done processing `aic_advanced_brep.exp` => `schemas/aic_advanced_brep/aic_advanced_brep.exp`
5720: `iso-10303-stepmod-wg12/data/resources/aic_associative_draughting_elements/aic_associative_draughting_elements.exp` processing...
5720: Written to: `schemas/aic_associative_draughting_elements/aic_associative_draughting_elements.exp`
...
5720: Written to: `schemas/business_object_models/managed_model_based_3d_engineering_domain/DomainModel.exp`
5720: Done processing `DomainModel.exp` => `schemas/business_object_models/managed_model_based_3d_engineering_domain/DomainModel.exp`
[stepmod-utils] ******************************
[stepmod-utils] [SRL MIGRATION: stepmod-utils] COMPLETE Annotated EXPRESS generation.
[stepmod-utils] ******************************
[stepmod-utils] [SRL MIGRATION: stepmod-utils] START EXPRESS change YAML extraction.
[stepmod-utils] STEPmod data path: `iso-10303-stepmod-wg12`
[stepmod-utils] Copied arm.changes.yaml to schemas/activity/arm.changes.yaml
[stepmod-utils] Copied arm_lf.changes.yaml to schemas/activity/arm_lf.changes.yaml
[stepmod-utils] Copied mim.changes.yaml to schemas/activity/mim.changes.yaml
[stepmod-utils] Copied mim_lf.changes.yaml to schemas/activity/mim_lf.changes.yaml
[stepmod-utils] Copied arm.changes.yaml to schemas/activity_as_realized/arm.changes.yaml
...
[stepmod-utils] Copied topology_schema.changes.yaml to schemas/topology_schema/topology_schema.changes.yaml
[stepmod-utils] ******************************
[stepmod-utils] [SRL MIGRATION: stepmod-utils] COMPLETE EXPRESS change YAML extraction.
[stepmod-utils] ******************************
[stepmod-utils] [SRL MIGRATION] Migration complete!
[stepmod-utils] ******************************

Conversion of STEPmod descriptions.xml into adoc

$ stepmod-convert-express-description /path/to/the/stepmod/descriptions.xml

Example output:

(*"application_context_schema"

*)
(*"application_context_schema.exchange_identification_context_select"
 The *exchange\_identification\_context\_select* type allows for the designation of the data types express_ref:[management_resources_schema:ir_express:management_resources_schema.identification_assignment] and express_ref:[person_organization_schema:ir_express:person_organization_schema.organization] .
*)
(*"application_context_schema.application_context"
 An *application\_context*, as defined in ISO 10303-1, is a context in which product data is defined and has meaning. An *application\_context* represents various types of information that relate to product data and may affect the meaning and usage of that data.
*)
(*"application_context_schema.application_context.application"

the express_ref:[support_resource_schema:ir_express:support_resource_schema.label] by which the *application\_context* is known.

[NOTE]
--
The meaning of this attribute can be defined in the annotated EXPRESS schemas that use or specialize this entity, or in an agreement of common understanding between the partners sharing this information.
--

*)

Conversion of STEPmod resource.xml into adoc

Given resource.xml file contents:

<schema name="contract_schema" number="8369" version="3">
  <introduction>
    The subject of the <b>contract_schema</b> is the description of contract agreements.
  </introduction>
  <fund_cons>
    Contract information may be attached to any aspect of a product data.
  </fund_cons>
  <express-g>
    <imgfile file="contract_schemaexpg1.xml"/>
    <imgfile file="contract_schemaexpg2.xml"/>
  </express-g>
</schema>

Command:

$ stepmod-convert-express-resource resource.xml

Will give output:

== Introduction

The subject of the *contract_schema* is the description of contract agreements.

== Fundamental concerns

Contract information may be attached to any aspect of a product data.

expg_image:contract_schemaexpg1.xml[]
expg_image:contract_schemaexpg2.xml[]

Generate EXPRESS Change YAML files

EXPRESS Change YAML files are YAML files that contain schema history information.

This command migrates existing schema change information (in XML) into independent per-schema YAML files.

The files will be created in the same directory as the schema:

Schema: shape_dimension_schema/shape_dimension_schema.exp
Output: shape_dimension_schema/shape_dimension_schema.changes.yaml

Command:

$ stepmod-extract-changes -p {stepmod-data-directory}

Examples

Given the following XML

<change version="4">
   <arm.changes>
      <arm.modifications>
         <modified.object type="TYPE" name="ap242_requirement_assignment_item" />
         <!-- ... -->
      </arm.modifications>
   </arm.changes>
   <mim.changes>
      <mim.additions>
         <modified.object type="CONSTANT" name="ap242_shape_representation_reference_types" />
         <!-- ... -->
      </mim.additions>
      <mim.modifications>
         <modified.object type="CONSTANT" name="deprecated_interfaced_data_types" />
         <!-- ... -->
      </mim.modifications>
      <mim.deletions>
         <modified.object type="RULE" name="subtype_mandatory_shape_representation" />
      </mim.deletions>
   </mim.changes>

   <arm_longform.changes>
      <arm.additions>
         <modified.object type="TYPE" name="advanced_face_model" />
         <!-- ... -->
      </arm.additions>
      <arm.modifications>
         <modified.object type="TYPE" name="assembly_constraint_select">
            <description>
               <ul>
                  <li>Remove SELECT value 'ENTITY Binary_assembly_constraint'</li>
               <!-- ... -->
               </ul>
            </description>
         </modified.object>
         <!-- ... -->
      </arm.modifications>
      <arm.deletions>
         <modified.object type="TYPE" name="axis_placement_mapping_source" />
      </arm.deletions>
   </arm_longform.changes>

   <mim_longform.changes>
      <mim.additions>
         <modified.object type="CONSTANT" name="ap242_shape_representation_reference_types" />
      </mim.additions>

      <mim.modifications>
         <modified.object type="CONSTANT" name="deprecated_constructed_data_types">
            <description>
               CONSTANT 'deprecated_constructed_data_types': Expression Changed
            </description>
         </modified.object>
         <!-- ... -->
      </mim.modifications>

      <mim.deletions>
         <modified.object type="TYPE" name="connected_edge_with_length_set_items" />
         <!-- ... -->
      </mim.deletions>
   </mim_longform.changes>

</change>

Will Generate 4 files:

arm.changes.yml
mim.changes.yml
arm_lf.changes.yml
mim_lf.changes.yml

arm.changes.yml:

---
schema: Ap242_managed_model_based_3d_engineering_arm
change_edition:
- version: 4
   description:
   modifications:
   - type: TYPE
   name: ap242_requirement_assignment_item

mim.changes.yml:

---
schema: Ap242_managed_model_based_3d_engineering_mim
change_edition:
- version: 4
  description:
  additions:
  - type: CONSTANT
    name: ap242_shape_representation_reference_types
  modifications:
  - type: CONSTANT
    name: deprecated_interfaced_data_types
  deletions:
  - type: RULE
    name: subtype_mandatory_shape_representation

arm_lf.changes.yml:

---
schema: Ap242_managed_model_based_3d_engineering_arm_LF
change_edition:
- version: 4
  description:
  additions:
  - type: TYPE
    name: advanced_face_model
  modifications:
  - type: TYPE
    name: assembly_constraint_select
    descriptions:
    - Remove SELECT value 'ENTITY Binary_assembly_constraint'
  deletions:
  - type: TYPE
    name: axis_placement_mapping_source

mim_lf.changes.yml:

---
schema: Ap242_managed_model_based_3d_engineering_mim_LF
change_edition:
- version: 4
  description:
  additions:
  - type: CONSTANT
    name: ap242_shape_representation_reference_types
  modifications:
  - type: CONSTANT
    name: deprecated_constructed_data_types
    description: |
      CONSTANT 'deprecated_constructed_data_types': Expression Changed
  deletions:
  - type: TYPE
    name: connected_edge_with_length_set_items

stepmod-utils

Development

Runtime

STEPmod utilities

Purpose

Installation

Usage

EXPRESS schema validation

Generating Annotated EXPRESS

ISO 10303-2 concepts extraction

Creating the SRL

Conversion of STEPmod descriptions.xml into adoc

Conversion of STEPmod resource.xml into adoc

Generate EXPRESS Change YAML files

Examples