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.
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
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:
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.
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 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 glTF file. The visualizaton facets should be precomputed in the stored CAD shapes.
The asm-xde-save-fbx function saves the specified XDE document to FBX file. The visualizaton facets should be precomputed in the stored CAD shapes. For FBX export, the Autodesk's FBX SDK is used.
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-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.
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.