./features/assembly XDE document
Download Features Source code References 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.

asm-xde-new

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

asm-xde-new -model M

asm-xde-load

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.

asm-xde-save

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

asm-xde-release

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.

asm-xde-browse

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.

asm-xde-xcompounds

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.

asm-xde-print-structure

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>]

asm-xde-show-summary

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

asm-xde-get-parts

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]

asm-xde-get-leaves

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]

asm-xde-find-items

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.

asm-xde-add-part

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

asm-xde-save-gltf

The asm-xde-save-gltf function saves the specified XDE document to glTF file. The visualizaton facets should be precomputed in the stored CAD shapes.

asm-xde-generate-facets

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.

asm-xde-set-as-var

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