USD Assemblies For Data Aggregation

Assemblies are annotated with the “assembly” kind to make it easy to identify assembly hierarchies. The referenced prims may either be assemblies themselves (e.g., workcell), or they may be “component models” with kind = “component” (e.g., safety fences).

  • Assemblies with Internal References

    Connectors and converters aggregate prim hierarchies within a single layer by creating internal references (if instancing is enabled - see Instances for more information on instancing).

  • Assemblies with External References

    Omniverse users typically aggregate prim hierarchies from other USD layers by creating external references.

  • Instances

    In addition to being referenced, Components are often instanced - see Instances for more information on instancing.

Considerations for Units

  • We highly recommend that you encode your datasets in consistent units (e.g., meters) across all data sources when possible.

  • This simplifies data aggregation via assemblies considerably, and the Measure Tool will still operate in whatever units you choose to display.

  • If you must reference or payload external layers with differing units, the Metrics Assembler Extension, enabled by default in USD Explorer, can facilitate by writing transform correctives to account to non-destructively scale the external content accordingly.

  • We do not recommend sublayering content with differing units, as there is no non-destructive scaling possible, given that the entire sublayer is “merged” in with no single prim upon which to write the transform corrective.

  • Learn More about Units in USD.

Assemblies with Internal References


Many applications which are supported by OV offer the ability to define repeatable objects, which might be stored in “libraries” for sharing and distribution: For example “family elements” in Revit or .prt files in Creo.

Most connectors and converters in OV support this, when the “Enable Instancing” toggle in the Import / Convert Options is enabled. Some connectors additionally offer a “batch mode” which creates -> Assemblies with External References.


Stages which do not contain substantial amounts of repetition may not benefit from these options. Enable it for large stages with significant counts of duplicate objects once comfortable with simpler stages.

When an object is identified as a repeatable object, it will be placed at a specific path in the USD scene hierarchy (the exact path varies depending on connector/converter).

Conceptually, this path can be understood to serve as an “object library”. Any occurrences of an object (and their entire sub hierarchies) are then referenced onto their respective prims in the stage. This avoids unnecessary duplication of data and allows users to modify all references simply by editing the prototypes in the “object library”.

Prims with such references are annotated in the Stage panel with an orange arrow. In order to find the source of the reference, look up the path in the “Reference” section of the property panel.

In addition to being referenced, the components are also marked instanceable by the connectors and converters.

See Instances for more information on instances.

Assemblies with External References


The main difference to Assemblies with “Internal References” is that the “Component Models” are in external layers and therefore do not require the “prototypes” hierarchy within the same layer. Editing of the Component models is therefore done by opening their respective layers directly, for example in a second application instance of “USD Explorer”. Once the intended changes are made, the layer is saved and USD Explorer will ask whether it should be updated in the assembly.


If the reference is used more than once, consider setting the prim to instanceable to gain efficiences.

Prim Hierarchies in Assemblies

Referencing USD layers onto prims at the “root” of the hierarchy is perhaps the simplest form of creating an assembly (this can be done via File > Import + “External Stage” option or dragging from the Content Browser). But for additional structure, articulation and organization, it is highly recommended to create a prim hierarchy from Scope and Xform prims to host the references.

Nested Assemblies

Assemblies with external references can be “nested” into multiple assemblies, e.g., a chain of references.

For example, a robot “component model” defined in robot.usd may need to be placed inside a room that has been defined in architecture.structure.usd. In this case, the reference to process.usd might be added to the rooms’ Xform. This can be done in an “over” of the Room prim in factory.usd (Option A) or on the prim itself by editing architecture.structure.usd directly (Option B). In both cases, the composed hierarchy will be the same.


Option A: The reference to process.usd is introduced in an “over” in factory.usd


Option B: The reference to process.usd is added to the room in structure.usd. It will appear at the same location in the prim hierarchy in the compose stage.