Frequently Asked Questions

Terminology

Open USD provides an extensive glossary replete 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 in USD is a primitive (prim) 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 lightweight, and carry with them an implicit assumption that the child prims of a reference will not be modified.

If the contents of a reference need to be modified during simulation, then it must be converted into a Payload. A payload is 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 that it can be modified at runtime.

Instances are indicated by a blue “I”, and can be either references or payloads. They carry additional assumptions about the structure of the asset for more efficient vectorization (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 a 1000 robots at once, and they are all the same, you might use instantiable references. Whereas, if you wanted to collect data with a 1000 randomly sampled robots (different arms with the same number of joints for example), you would use instance payloads.

Application vs Simulation vs World vs Scene vs Stage?

Everything in USD is a primitive (prim) with attributes.

A Simulation (the sim) moves these prims forward through time by literally changing these attributes programmatically.

The Application is the thing that manages the gross aspects of the simulation (how things are rendered, for example) and how the user interacts with it. If there is a GUI for the sim, it is a part of the application.

A Stage is a USD concept, and defines the logical and relational context for prims in the simulation. If a mug prim is on a table prim then that relationship is expressed by the relative locations of those prims on the stage, and the specific attributes each has. In this way, the stage provides context for the application: prims cannot exist without a stage and so an application concerned with prims requires a stage to function.

Similarly, the World is what provides context to the simulation, defining which prims are relevant to the ongoing flow of time, the scene, and managing the aspects of the simulation that are most important to the user.

For example, imagine you are going to see a play at a theater. The theater is like the application, your gateway to the play, while the simulation is the play itself, defined by a program. You take your seat and you can see the stage, where the play will take place. When the play starts, the curtain rises and reveals a scene composed props and actors that then act out that part of the play. When it’s time to move to the next scene, the curtain falls, the scene is reset, and then the curtain rises again, revealing the next part of the play. The stage crew and all the mechanical devices behind the scene that manages the curtain and the props is the world of the play.