Instancing in USD#

When instancing is enabled (Instancing Style set to “Scenegraph Instancing”), the DGN converter creates USD scenegraph instancing structures to efficiently represent Shared Cell References from the DGN file. This document explains how the converter uses USD instancing and how to work with the resulting structure.

For detailed information about USD Scenegraph Instancing concepts, see the NVIDIA Learn OpenUSD documentation on Scenegraph Instancing.

Pre-Conversion Considerations: Before converting CAD files to USD, consider reviewing the CAD Conversion Considerations guide, which provides recommendations for preparing CAD data before conversion, including reducing part count, reorganizing hierarchies, and optimizing scene scale.

Why Use Instancing#

Instancing provides declarative deduplication of repeated geometry, offering significant benefits:

Memory Efficiency: Geometry, materials, and other properties are stored once in the prototype rather than duplicated for each instance, reducing memory usage.
Performance: Rendering and scene traversal are optimized when multiple instances share the same prototype, improving overall performance.
File Size: USD files with instancing are typically smaller than files with duplicated geometry.

Instancing accelerates performance by allowing USD to recognize that certain scene elements are identical without needing to check each individual copy at runtime.

How the Converter Uses Instancing#

When instancing is enabled, the converter creates scenegraph instances by setting instanceable = true metadata on Prims representing Shared Cell References. USD then automatically creates implicit prototypes based on the composition arcs (references) used by these Instanceable Prims.

The converter creates a hierarchical structure in USD:

Prototypes Prim: A Prototypes Scope prim is created as a child of the default prim and is authored as a class Scope (abstract class prim). This prim serves as a container for all prototype definitions.
Prototype definitions: Under the Prototypes prim, the converter creates one def Xform prim per unique Shared Cell Definition (e.g. Prototype_1, Prototype_2). These def prims contain the geometry and other properties that are shared across multiple instances. Each prototype definition has a local def Scope Looks that contains materials; the converter uses a Specialize arc so that these materials are composed from a shared root-level Looks Scope, making them local to each prototype under its own Scope.
Looks Scope: A def Scope Looks is created (as a sibling of Prototypes under the default prim) and holds the shared material definitions. The prototype definitions under Prototypes each have their own Looks Scope that specializes this root Looks, so materials are available locally within each prototype.
Instanceable Prims: In the main scene hierarchy, Shared Cell References are represented as def Xform prims with instanceable = true and a references composition arc pointing at the corresponding prototype definition under Prototypes (e.g. prepend references = </ModelName/Prototypes/Prototype_1>). These instance prims are mutable and can have unique transformations and other properties.
Instance Proxies: When traversing instances, USD provides Instance Proxies that allow you to query properties of the prototype prims without following the indirection to the prototype.

The structure in the converted USDA/USDC looks like:

/ModelName (default prim, def Xform)
  ├── Prototypes (class Scope - abstract class prim)
  │   ├── Prototype_1 (def Xform - prototype definition)
  │   │   ├── Geometry
  │   │   └── Looks (def Scope, specializes "/ModelName/Looks" — materials local to prototype)
  │   └── Prototype_2 (def Xform - prototype definition)
  │       ├── Geometry
  │       └── Looks (def Scope, specializes "/ModelName/Looks" — materials local to prototype)
  ├── Looks (def Scope, shared material definitions)
  ├── Instance_1 (Instanceable Prim, references Prototype_1)
  │   ├── Geometry (Instance Proxy)
  │   └── Materials (Instance Proxy)
  └── Instance_2 (Instanceable Prim, references Prototype_1)
      ├── Geometry (Instance Proxy)
      └── Materials (Instance Proxy)

Key Concepts:

Explicit Instances, Implicit Prototypes: You explicitly mark Prims as instanceable, and USD implicitly creates prototypes based on composition arcs.
Instanceable Prims are Mutable: The root Prim of each instance can be edited (e.g., transformations, visibility) to position and control individual instances.
Instance Proxies are Immutable: Descendants within an instance (Instance Proxies) cannot be directly edited, which enables the performance benefits of instancing.

Why the Prototypes Prim Is a Class Prim#

Only the Prototypes Scope (the container) is created as an abstract class prim (the class specifier in USD). The prototype definition prims under it (e.g. Prototype_1, Prototype_2) are authored as def Xform prims. Using a class for the Prototypes container follows USD best practices:

The Prototypes Scope and prototype definitions are not part of default stage traversal and can be easily identified and filtered through OpenUSD’s traversal predicates. The Abstract Class designation helps distinguish these prototype definitions from the Instance Prims that reference them in the main scene hierarchy.

If the Prototypes prim appears non-editable in your DCC or viewer, it is because of this class specifier. The prototype definition prims under Prototypes are def and hold the actual geometry and materials; they may still be treated as non-editable when reached only through instance proxies.

Refining Scenegraph Instances#

While Instance Proxies (descendants within instances) are immutable, there are several techniques available to introduce variety and customization into instanced scenes while maintaining performance benefits. These refinement techniques allow you to balance optimization with authoring flexibility.

Instance Editability Rules#

Understanding instance editability is key to working with instanced scenes:

Prototypes are not editable: Prototypes are runtime data structures and cannot be directly edited.
Instance Proxies are not editable: Local opinions on Instance Proxies are discarded. You cannot edit Prims within an instance hierarchy.
Instanceable Prims are editable: The root Prim of each instance can be edited, allowing unique transformations, visibility, and other properties per instance.

For more details, see the Introduction to Scenegraph Instance Refinement.