./features/assembly XDE document
Download Features Source code Forum Ask for support

XDE in nutshell

XDE stands for the eXtended Data Exchange framework provided by the open-source OpenCascade kernel for representing CAD assemblies. Although XDE comes with its inherent deficiencies, such as missing assembly-level API, Analysis Situs exposes some functions for working with these structures for the sake of better compatibility with the kernel.

XDE is a specialization of OCAF (OpenCascade Application Framework) that is a sort of "rapid application development" engine for CAD/CAM/CAE. This XDE framework found its primary use at reading STEP files (and possibly other formats) as not just shapes but also with assembly hierarchies and metadata, such as colors, names, etc. In this chapter, we explain in a bit more detail what is XDE, how it works, and how to make use of it through the provided Analysis Situs' API functions.

OpenCascade, as a C++ kernel, has its own data structures for keeping and manipulating CAD geometries in boundary representation. A CAD shape's primary data structure is a C++ class named TopoDS_Shape (where TopoDS stands for "topological data structure"). When it comes to assemblies, you need something more. A good practice is to separate geometries from the product structure. Recall that at the level of geometry itself, we divorce the mathematics of form from its topology. For CAD assemblies, we need something similar, i.e., another level of indirection. XDE is an attempt to address this problem by exploiting the means of OCAF.

The software developers familiar with the OpenCascade's geometric structures tend to avoid using OCAF as they find this framework a bit horrible. E.g., it is not apparent how to use it, and the provided functionality looks hard to exploit. That's not necessarily the case, though. Speaking about OCAF itself will bring us too far from the topic (CAD assemblies), so we leave this discussion for another chapter.

API functions

In this section, we cover the primary API functions exposed by Analysis Situs for the XDE documents representing CAD assemblies. The API is a set of Tcl functions available in the module cmdAsm loaded to the Active Script session on Analysis Situs launch. In case of any doubt on the specific function's signature, check out the hints in the dialog opened by show-commands command.


The asm-xde-new function constructs a new empty XDE document and sets it as a Tcl variable.

asm-xde-new -model M


The asm-xde-load function reads a CAD file of any supported format to the XDE document.

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

At this point, you should give your model a name, which is M in our example. The model becomes a Tcl variable, which you can check for existence using the provided whatis command:

whatis M

It is possible to work with several models as you can give them distinct names.


The asm-xde-save function stores the XDE document in the native OpenCascade's binary format (.xbf).

asm-xde-save -model M -filename as1-oc-214.xbf


The asm-xde-release function closes the XDE document with the given name and unsets the corresponding Tcl variable.

asm-xde-release -model M

Use this function to clean up the memory occupied by a model. This function can be especially useful for batch processing when you deal with multiple XDE documents representing different CAD files.


The asm-xde-browse function opens a GUI dialog for observing the XDE document's structure. This structure is basically the scene tree for the assembly.

The icons of distinct colors encode different entity types. Notice that an assembly never includes parts or subassemblies directly. The components are always nested by means of an intermediate instance object, which is a lightweight reference to a prototype with location. The difference between the assembly instances and part instances is not captured by XDE entities, though can count these types of instances separately using the asm-xde-show-summary command.

Root Instance
Subassembly Part

The following code snippet illustrates how to browse an XDE document named M:

asm-xde-browse -model M

You can open up as many browsers as you want. Just keep in mind that the browsers' contents are not being automatically synchronized with the assembly structure. That is, whenever you modify the assembly structure, consider opening a new browser.

The lack of synchronization is the as-designed behavior. We wanted Analysis Situs to be able to trace the modifications over the product's structure. That can be done by opening several browsers at the same time.


The asm-xde-xcompounds function turns the compound-type parts into subassemblies.

asm-xde-xcompounds -model M

You can optionally pass the IDs of the assembly items of interest in the case you know which items exactly you'd like to expand. For the passed items, this function will get their ultimate leaves (if any) and expand compounds on the leave items.


The asm-xde-print-structure function prints the hierarchical structure of the CAD assembly to the Log Window. You may control the level down to which the exploration is done.

asm-xde-print-structure -model M [-level <level>]


The asm-xde-show-summary function counts the number of parts, subassemblies and their instances in the XDE document. A GUI dialog is shown to consult the summary.

asm-xde-show-summary -model M


The asm-xde-get-parts function returns the IDs of all unique parts in the model. The following code snippet illustrates how to initialize a Tcl list from the API function's outcome. The last two commands print the number of the extracted part IDs and the IDs themselves. A common practice is to use the extracted IDs later on in a pipeline for automatic assembly processing.

set pids [asm-xde-get-parts -model M]
puts [llength $pids]
puts $pids

You can optionally pass the parent assembly items whose child parts have to be returned:

set parts [asm-xde-get-parts -model M -items 0:1:1:1/0:1:1:1:1/0:1:1:2:1/0:1:1:3:1]


The asm-xde-get-leaves function returns the IDs of the leaf assembly items for the passed items.

set leaves [asm-xde-get-leaves -model M -items 0:1:1:1/0:1:1:1:1/0:1:1:2:1/0:1:1:3:1]


The asm-xde-find-items function searches for assembly items having the passed name. The name is taken from the OCAF label being visited on iterating the assembly graph in the depth-first manner.

set items [asm-xde-find-items -model M -name "X473"]

Since the object's name does not have to be unique, this function might return several IDs.


The asm-xde-add-part function adds the active part of Analysis Situs to the XDE document as another root. If the -name key is passed, the new part will get the specified name. If not, it will get the "Unnamed" label as its name. The function returns the persistent ID of the newly added part. The B-rep geometry of the active part is set as the part's representation within the XDE document.

asm-xde-new -model M
asm-xde-add-part -model M
asm-xde-add-part -model M -name "part 2"
asm-xde-add-part -model M -name "part 3"
asm-xde-browse -model M
asm-xde-release -model M


The asm-xde-save-gltf function saves the specified XDE document to a glTF file. The visualizaton facets should be precomputed in the stored CAD shapes with asm-xde-generate-facets beforehand. Make sure that Analysis Situs is compiled with RAPIDJSON dependency to use glTF export.


The asm-xde-save-fbx function saves the specified XDE document to an FBX file. The visualizaton facets should be precomputed in the stored CAD shapes with the asm-xde-generate-facets function. For FBX export, the Autodesk's FBX SDK is used (therefore, it should be enabled in CMake when Analysis Situs is compiled from sources).


asm-xde-load -model M -filename "box-colored.stp"
asm-xde-generate-facets -model M -fine
asm-xde-save-fbx -model M -filename box-colored.fbx


The asm-xde-save-step function exports the entire document or a specified part to a STEP file.


The asm-xde-generate-facets function triangulates B-rep shapes available in the XDE document. You will need facets to take advantage of mesh-based algorithms or if you want to export meshes, e.g., to glTF format. Analysis Situs does not construct visualization meshes automatically as this data is often not needed. Also, meshing large assemblies may take significant amount of time, so we keep visualization meshes disabled to allow for working with large assemblies (in the command line).


The asm-xde-set-as-var function sets the passed assembly item as a project variable.


The asm-xde-set-name function assigns the passed name to a part/subassembly or its instance referenced by given assembly item ID. By default, the name is set for a prototype (i.e., the object being referenced). To name an instance, pass -instance key.


The asm-xde-remove-parts function removes the specified parts with all their occurrences in the model. All empty subassemblies that may remain after this operation are cleaned up automatically. In the case you want to remove all parts except for the selected subset, pass the -invert keyword.


The asm-xde-unload function breaks down the entire assembly document onto individual parts. This feature is especially useful for large assemblies that cannot be processed as a whole and require further decomposition. As a result, all unique parts get exported into the corresponding STEP files having filenames derived from the part names (if there are several parts with the same name, a unique integer index is added as a suffix).

The following image illustrates the contents of the output directory specified via -path keyword. Each part is exported as a separate STEP file.

In the same output directory, the asm-xde-unload function puts a file named "bom.csv" (stands for "Bill of materials"). This file contains information on part occurrences and their corresponding filenames:


Extract unique parts

The following script extracts all unique parts from an assembly and exports them to STEP files. This way you can break down an assembly file to individual solids. It should be noted though that such technique does not take into account part occurrences, so if, for example, you have one bolt instantiated 10 times, the following script will output only one file for the unique bolt's geometry.

asm-xde-load -model M -filename "assembly.stp"
asm-xde-xcompounds -model M
set pids [asm-xde-get-parts -model M]
set i 0
foreach pid $pids {
  asm-xde-save-step -model M -filename part_$i.stp -part $pid
  incr i