Frequently Asked Questions

Terminology

Open USD provides an extensive glossary repleate with explicit definitions for various USD jargon. This section of the FAQ focuses on common misunderstandings or confusion regarding these terms and how they are represented in Isaac Sim.

Reference vs Payload vs Instance?

Everything is a USD primitive with attributes. Some of these primitives are defined in your current layer (the active stage), while others are defined in other layers (other USD files). A primitive that is included from some other layer is a Reference to that prim, and are indicated by the orange arrow on the associated Xform icon in the context tree of Isaac Sim. References are designed to be light weight, and carry with them an implicit assumption that the child prims of a reference will not be modified. If the contents of a reference does need to be modified during simulation, then we must convert it into a Payload first, indicated by the blue arrow on the associated xform in the context tree of Isaac Sim. Payloads are references that have all of their data actively loaded by the sim so it can be modified at runtime. Finally, Instances (indicated by a blue “I”) can be either references or payloads, but carry additional assumptions about the structure of the asset in order to allow it to be more efficiently vectorized (scaled up).

For example: Suppose you want to collect synthetic data with a robot. If you aren’t going to modify the structure of the robot, it can exist as a reference on the stage (the asset is defined in some other file). If, during data collection, you want to be able to swap the robot out for a different one, those meshes need to be held in active memory. This means that the asset first needs to be converted from a reference to a payload. If you wanted to collect data with 1000 robots at once, and they are all the same, you might use instantiable references, while if you wanted to collect data with 1000 randomly sampled robots (different arms with the same number of joints for example), you would use instance payloads.