Instancing in USD#

When instancing is enabled (Instancing Style set to “Reference” or “Instanceable Reference”), the JT converter creates USD scenegraph instancing structures to efficiently represent instanced Parts and Assemblies from the JT 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 instanced Parts and Assemblies (specifically JtkINSTANCE node types), with a references composition arc pointing at the prototype.

Note: Only JtkINSTANCE node types from the JT file are converted to instanceable prims. Other node types (e.g. JtkPart) are converted as regular prims in the scene hierarchy.

The converter authors prototypes and instances as siblings under the same root, with no Prototypes Scope and no class prims:

Prototype prims: Some prims under the default prim are full definitions (e.g. def Xform "Prototype_1") with geometry, omni:jt:nodeType = "JtkPart", and a local def Scope Looks for materials. The converter uses a Specialize arc so that each prototype’s Looks is composed from a shared root-level Looks Scope, making materials local to each prototype under its own Scope.
Looks Scope: A def Scope Looks is created under the default prim and holds the shared material definitions. Each prototype prim has its own Looks Scope that specializes this root Looks, so materials are available locally within each prototype.
Instance prims: Other prims (e.g. def Xform "Instance_1") have instanceable = true and prepend references = </ModelName/Prototype_1>, pointing at the prototype prim. They carry omni:jt:nodeType = "JtkInstance" and their own transform. These instance prims are mutable; their descendants are Instance Proxies.

In this layout, prototype and instance prims are all def Xform; there is no Prototypes Scope and no abstract class prim. The structure in the converted USD looks like:

/ModelName (default prim, def Xform)
  ├── Prototype_1 (def Xform — prototype, JtkPart, has geometry)
  │   ├── Geometry
  │   └── Looks (def Scope, specializes "/ModelName/Looks" — materials local to prototype)
  ├── Instance_1 (def Xform, instanceable = true, references Prototype_1, JtkInstance)
  │   ├── Geometry (Instance Proxy)
  │   └── Looks (Instance Proxy)
  ├── Instance_2 (def Xform, instanceable = true, references Prototype_1, JtkInstance)
  │   ├── Geometry (Instance Proxy)
  │   └── Looks (Instance Proxy)
  └── Looks (def Scope, shared material definitions)

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.

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.

Instancing in USD#

Why Use Instancing#

How the Converter Uses Instancing#

Refining Scenegraph Instances#

Instance Editability Rules#

Refinement Techniques#