./features/assembly JSON hierarchy
Download Features Source code Forum Ask for support

Assembly JSON hierarchy


Any CAD product definition coming from a CAD file contains geometric information and metadata, including assembly hierarchy (can be plain) and metadata (colors, names, etc.). Analysis Situs employs OCAF/XDE data structures for storing format-agnostic product representation. The assembly representation in XDE is a Hierarchical Assembly Graph (HAG, see [Rappoport, 1993]), which can be turned into a scene tree by visiting its nodes and reporting all unique paths.

To read a CAD file into an XDE document and observe its structure, use:

> asm-xde-load -model M -filename as1-oc-214.stp
> asm-xde-browse -model M

The last command would open a browser window where you can visually navigate over the assembly structure.

Dump to JSON

The scene hierarchy exposed by the asm-xde-browse command can be used algorithmically if dumped in the JSON format. To dump an assembly tree to JSON use the asm-xde-dump-json command.

JSON serialization of an assembly tree is based on the following template (the contents of the following JSON are deliberately reduced to give it an observable structure):

  assemblyTree: {
    roots: [1],
    prototypes: {
      parts: [
          id: 3,
          name: "TS4-3",
          persistentId: "0:1:1:2"
      assemblies: [
          id: 1,
          name: "=>[0:1:1:2]",
          childInstances: [2]
    instances: [
        id: 2,
        name: "1",
        prototype: 3,
        rotation: [ 0, 0, 1, 0 ],
        translation: [ -10, -7.5, 185 ]

The following key observations are used in this template:

  1. All reusable data containers (i.e., parts and subassemblies) are embraced by the prototypes object. A "prototype" is something that can be instantiated.
  2. An instance is a reference to a prototype with the transformation properties represented with rotation (axis and angle) and translation.
  3. Rotation and translation are defined at the level of instances. It is always an instance that holds the transformation props of a prototype. An instance holds a reference to the prototype via the prototype integer property.
  4. To make it clear that an assembly can only contain instances as its components (children), and assembly prototype has a field named childInstances.

It is possible to dump the assembly hierarchy together with the base64-encoded B-rep shape buffers of each unique part. To do that in Analysis Situs, pass the additional -shapes flag to the asm-xde-dump-json command:

> asm-xde-dump-json -model M -shapes

This JSON can be saved to a text file by manually copying and pasting its contents.

To validate the transformations encoded in the JSON file, you can use the asm-xde-display-json command followed by the JSON filename. If shape BLOBs are available, this command will deserialize them into B-rep geometries and apply the hierarchy of transformations for a visual check.

If a CAD file is exported from a single-part design system, no instances may be present in the scene tree. We only output instances if they are contained in the STEP file (as NEXT_ASSEMBLY_USAGE_OCCURENCE entities); otherwise, while populating the scene tree, no new entities are added. For single-part files, you quite frequently only have the individual parts and no instances. This is a valid scenario because a part is often exported from CAD modules for part design (as opposed to modules for assembly design) without any transformation matrix.