USD is a system of software and file formats for describing 3D scenes by composing layers. For example, a master USD file describing a kitchen scene (kitchen.usd)might reference layer files containing props (chair.usd, table.usd), lighting, characters, and so on, composing them into a single stage.

The main power of the layer paradigm is non-destructive editing. You can start with an existing scene and create a new layer containing your edits. These edits won’t affect other people using the same scene unless they choose to include your new layer. You can also replace one of the layers (for example a newer version of an asset or updated lighting) and automatically re-apply all existing changes on top of it. This allows multiple departments to collaborate, share data, and update assets without interfering with each other.

Houdini’s tooling and support for USD is collectively known as Solaris. Solaris includes USD support in the view and a new network type, LOPs (Light Operators). LOP networks are slightly similar to SOPs, where each node accepts incoming geometry, modifies it, and outputs new geometry. In LOPs, each node accepts an incoming USD scene, modifies it, and outputs a new scene.

Because USD is a very comprehensive framework, it is not simple. LOPs is designed so you don’t need to know about the underlying USD structure. However, wherever possible LOP parameters use USD terminology, and are sometimes a thin wrapper around functionality built into USD. A basic understanding of USD concepts and features will make it much easier to understand LOPs.

The following page explains the basics of USD, and relates them to how Solaris supports working with USD in Houdini. For a look at how LOP nodes generate USD, see how LOPs work.

Normally .usd (or .usdc) files are binary encoded for efficiency, however the USD scene description format has an plain text equivalent (.usda) that is human-readable. Here is a very simple .usda example to introduce some USD concepts we’ll explain in this document:

#usda 1.0
def Cube "box" {
    double size = 4.0
}

In this example, def is a keyword defining a new prim (USD also has an over operator that is like def but defines how a new prim overrides an existing prim). Cube is the prim’s type. What “being a Cube” means and what properties a Cube has are defined by a schema. box is the name of the primitive (this prim will appear in the scene tree as /box). The Cube prim type is defined by the built-in USD Geometry schema. There are additional built-in schema for volumes, shading, lighting, skeletal animation, and rendering. You can extend USD by creating a custom schema to define your own prim types.

The code inside curly braces { } defines the new prim’s child primitives and properties (the Cube has many properties but those we don’t specify will be filled in with defaults from the type schema).

In USD jargon, this is bit of code may be said to “author an opinion about the size of /box”. When composing layers, if a layer contains an “opinion” about the value of a property, it will be overridden if a layer with a stronger opinion has a different opinion (value) for the same property.

Now consider a second .usda file:

#usda 1.0
def "box1" ( references = @box.usda@ ) {

}
def "box2" ( references = @box.usda@ ) {
    float size = 2.0
}

In this file, we import the contents of the box.usda file above twice as two prims: /box1 and /box2. /box1 will inherit its size attribute from the referenced layer. /box2 overrides size with a new value.

In Houdini, you generally won’t directly manipulate the values of attributes on primitives (although there are nodes for doing low-level edits). Instead, LOP nodes specify higher-level operations (such as “bring in this geometry”, “point this light at this object”, “place this prop on this table with physics”) and the LOPs author the corresponding USD automatically.

You can actually inject plain text USD code into the stage built by a LOP network using the Inline USD LOP. This can sometimes be useful for debugging, but is not how you should work normally!

In USD, attributes are often scalar values that contain a prim’s “settings”. For example, on a Sphere prim, the radius attribute controls the size of the sphere. In this sense, attributes are similar to node parameters in Houdini, or attributes in Maya.

In USD, geometry settings, such as per-point variables, are also stored as attributes on the prim. They are stored as arrays, with one element for each component. For example, the points attribute on a mesh prim stores the point positions in an array of coordinates. This is the same as Houdini geometry attributes.

USD also recognizes a specific type of attribute called a primvar. (The name primvar comes from Renderman, and stands for “primitive variable”.)

At the basic tree level, primvars are just attributes with the primvars: schema namespace prefix. What makes them special is how Hydra treats them during rendering. Their main purpose is to override material parameters. However they have useful behaviors that mean they're also used to represent per-object properties that may affect geometry rendering aside from materials. Karma, for example, lets you use primvars to specify the number of motion blur frames per-object.

Every USD file contains a complete “scene”. USD files can import the contents of other USD files as layers.

The USD libraries include software for composing/overlaying multiple layers into the full scene (stage) created by the top-level file. Composition includes merging the following differences between layers:

• New prims.

• Prim ordering.

• Whether a prim is active or inactive.

• Variants.

• New properties (attributes and relationships).

• Attribute values. (Higher layers can even “block” (unset) the value of an attribute so it appears to be unassigned).

• Metadata values.

Houdini automatically composes the various on-disk and in-memory layers created as you edit USD. You can also use tools to understand what’s on each layer and how layers are composed.

#usda 1.0
(
    subLayers = [
            @shotLighting.usd@,
            @shotFX.usd@,
            @shotAnimation.usd@,
            @shotSetDressing.usd@,
            @sequence.usd@
    ]
)

/Lights/
    light1
    light2
/Models/
    tableside_lamp
        

/lamp/
    base
    bulb
    shade
    socket
    switch

/Lights/
    light1
    light2
/Models/
    tableside_lamp/
        base
        bulb
        shade
        socket
        switch

#usda 1.0
(
   defaultPrim = "TrashCan"
)

def Xform "TrashCan" (
   kind = "component"
)
{
   def Cylinder "Can"
   {
       token axis = "Y"
       bool doubleSided = 0
       double height = 2
       double radius = 1
   }
}

#usda 1.0
()

def Xform "Scene"
{
   def Xform "Set"
   {
       def "BathroomTrashCan" (
           append references = @./trashcan.usda@
       )
       {
           double3 xformOp:translate = (2, 0, 1.4)
           uniform token[] xformOpOrder = ["xformOp:translate"]
       }

       def "KitchenTrashCan" (
           append references = @./trashcan.usda@
       )
       {
           double3 xformOp:translate = (16.01, 5, -43.072)
           uniform token[] xformOpOrder = ["xformOp:translate"]
       }

       def "OfficeTrashCan" (
           append references = @./trashcan.usda@
       )
       {
           double3 xformOp:translate = (-7.12, 0, 11.9)
           uniform token[] xformOpOrder = ["xformOp:translate"]
       }
   }
}

Keeping track of how multiple levels of sublayering and referencing work together to generate the final opinion on a primitive at a single scene graph location can become complicated. You can use the Layer Stack and Composition tabs of the Scene Graph Details pane to examine which layers contribute to the primitive, and how those different layers were composed together.

# props.usd
/Materials/
    plastic1
/Things/
    Toy/
        geom
        toy_shader (references and overrides /Materials/plastic1)

# scene.usd
/Materials/
    plastic1
/Models/
    Props/
        Toy/  <– referenced onto this prim
            geom
            toy_shader

• You can write usda format code and evaluate it and insert the resulting prims directly into the in-memory scene graph tree using the Inline USD node.

• You can use the Python Usd API to manipulate the in-memory stage directly using the Python Script LOP.

You can use your custom file format plugins and asset resolvers with Houdini in one of two ways:

• Build your plugins using the USD headers and libraries shipped with Houdini. (These headers and libraries are included as part of the HDK.)

• Replace Houdini’s version of the USD library with your own version. To do this you must download the HoudiniUsdBridge repository from the SideFX GitHub. This repository contains all the Houdini source code that calls into USD. Rebuild that code using your own USD library, and use the results to replace the equivalent libraries in the Houdini install (either by copying them in or manipulating LD_LIBRARY_PATH).

Solaris output processors provide a place to customize how files are saved (such as taking paths that are relative to $HIP and making them relative to the root USD file, and tweaking file extensions).

USD refers to prims that represent geometry as gprims (these are prims that, when rendered, will actually cause something to be drawn in the image, as opposed to, say, a transform prim). The schema for these prim types (UsdGeomGprim) contains convenient methods such as finding bounding boxes.

USD includes a set of prims representing mathematically defined shapes (capsule, cone, cube, cylinder) as well as more complex prims that hold geometry such as polygonal meshes or subdivision surfaces.

Do not put gprims under other gprims in the scene graph tree. Many key features of USD apply hierarchically, such as activation, visibility, and purpose, and it can be frustrating and counter-productive to be unable to apply these operations to individual gprims.

Kinds are one of the harder-to-understand concepts in USD. Every prim that has geometry under should have a “kind”.

“Model kinds” are sub-classes of an “abstract” kind called model. You should never assign model as a kind. There are three model kinds:

Kinds support organizing the geometry in the scene into a model hierarchy. This is a “table of contents” of the models in the scene. Maintaining this hierarchy properly allows software packages to present better UI, such as for selection, and allows more efficient traversal of the models in the scene. (For example, if software wants to show the user all the models in the scene, it only needs to start searching the tree in roots that have a kind, and can stop descending in the tree when it hits a component kind.)

A model hierarchy in the scene graph tree might look like the following:

/Models ← group
    /Characters ← group
        /Lady ← assembly
            /Skin ← component
                /mesh
            /Purse ← component
                /mesh
        /Dog ← assembly
            /Skin ← component
                /mesh
            /Collar ← component
                /mesh
    /Props ← group
        ...

To maintain the model hierarchy, your scene should have the following:

• All prims that deal with geometry under (descending from) them should have a kind, starting, including the root prim (for example, /Models).

• Only group/assembly kinds should contain other model kinds. Component kinds cannot contain groups, assemblies, or models. (They can contain subcomponent kinds).

In Houdini, nodes that create/edit primitives have parameters to let you set the prim’s kind. It does not allow you to use model as a kind, in accordance with model hierarchy rules. Currently Houdini doesn’t do anything to help or force the user to maintain the model hierarchy.

There are various forms of “instancing” (efficient copying) in USD.

USD inherently has the concept of one prim in the tree being a light-weight reference to another. While this is more efficient than actually copying all the prims in the branch, to preserve the ability to override sub-prims, USD must also create references for each sub-prim under the reference.

To get more efficient ways of populating the scene with large numbers of copies/variations of things, USD has two separate methods of instancing.

Instanceable prims are easier to work with than point instancers. However, while each “alias” consumes a very small amount of memory compared to copying the prim, it can add up over a very large number of instances. Point instancing is designed to handle billions of instances, with constant memory usage.

Both types of instances support transforming the top-level of each primitive and they also allow primvars (on each native instance individually, or on the point instancer primitive) to override material parameters per-instance.

Houdini supports both kinds of instancing with the Instancer and various Tab menu tools that configure the instancer node for different ways of instancing, so you will choose the method of instancing mostly based on the number of instances needed. Houdini also supports nested point instancing (one or more nested levels of instancers instancing prototypes containing instancers), and heroing an instance to become a “real” model.

USD allows storing multiple named variants of a primitive on the primitive. Each variant can have different attributes, relationships, and children. You can switch the primitive between different variants in different layers. Each primitive can store multiple groups of variants in named variant sets.

The following are some common use cases for variants:

• A family of different geometry (for example, a primitive that can switch between different types of trees).

• Levels of detail (storing progressively lower resolution versions of the same geometry as variants, and switching based on distance to the camera).

  Houdini includes the Create LOD and Auto Select LOD nodes for automating this workflow.

• Material assignments (storing variants with different materials assigned to them to allow switching the look of the primitive easily).

Here is an example of a layer which contains a variant set called owner, where each variant’s color corresponds to which character in the story owns that ball:

#usda 1.0
()

def Sphere "toyBall" (
    variants = {
        string owner = "blake"
    }
    append variantSets = "owner"
)
{
    double radius = 1
    variantSet "owner" = {
        "andy" (
        ) {
            color3f[] primvars:displayColor = [(1, 0, 0)] (
                interpolation = "constant"
            )


        }
        "blake" (
        ) {
            color3f[] primvars:displayColor = [(0, 0, 1)] (
                interpolation = "constant"
            )


        }
        "sally" (
        ) {
            color3f[] primvars:displayColor = [(0, 1, 0)] (
                interpolation = "constant"
            )


        }
    }
}

See Variant Set in Pixar USD glossary

Animation in USD is through time-varying attribute values, similar to how animation in Houdini is through time-varying node parameters.

• Each attribute, besides have a single “default” value, can have an collection of “time samples”, a list of values indexed by time. Metadata on the attribute specifies how to interpolate between the samples.

• If you ask USD for the value at the “default” time, it will return the default value if one is set, otherwise it will return an empty value. All time sample values are ignored. If you ask for a value at any other time, and there is any default or time sampled value set, you will get back a value. This value may be the default (if you request the value for a time before the first time sample), the closest time sample value, or a linear interpolation of the two surrounding time samples.

You can animate Houdini parameters on LOP nodes, and when you write out USD to disk, it will write the animated values as time samples.

• Schemas are custom extensions that can define new prim types or define the meaning/behavior of new attributes.

  At the “tree” level, USD is quite generic and “free-form”. You can set attributes to arbitrary typed values directly. Schemas provide a way to enforce constraints and invariants. By using the higher-level API, you ensure that attributes are authored “correctly” (such as keeping values within a certain range, or not allowing impossible configurations).

• USD calls a schema that defines its own prim type a typed schema.

• USD calls a schema that just defines an API you can apply on top of prims of different types an API schema. This type of schema generally have names that end in API.

  API schemas are further divided into singly-applied and multiply-applied.

  • An example of a singly-applied schema is UsdLuxShapingAPI, where a light prim either has shaping controls added or not. Prims have metadata which records a list of all singly-applied API schemas that have been applied.

  • An example of a multiply-applied schema is the CollectionAPI. You can define as many uniquely named collection: attributes on a given prim as you want.

Houdini generally doesn’t use custom attributes. Instead it often stores information in a “custom data” dictionary in the metadata of a prim. This space is intended for use by software packages and studios for their own use. Houdini stores bookkeeping information here that helps with saving USD to disk or navigating the scene, but this custom data is usually stripped from the USD written to disk.

Every primitive described in a layer has a specifier which conveys the authors intent for how the primitive should be interpreted in the composed scene. There are three possible values:

• Define (def): A concrete primitive that should always exist in the composed scene.

• Over (over): A primitive that exists only to hold overrides for opinions that already exist in the composed scene. If the primitive isn’t defined in another layer, the primitive will not be made concrete, and often would not be shown in the scene graph tree.

• Class (class): Intended as the target of an Inherit or Specialize composition arc. These primitives will be ignored by Hydra, but are usually shown in the scene graph tree.

USD defines an API (called Hydra) for generating an image from a USD scene at a certain point in time. As long as a program (such as Houdini, or usdview, or a renderer) implements this API, it can be used to display/render a USD scene.

A piece of software that implements this API is called a render delegate.

In Houdini this has the great benefit that you can switch the scene view between available render delegates such as Houdini’s OpenGL viewer, Pixar’s Storm OpenGL viewer, and Karma IPR. Further, you can view the scene using any third-party renderer that has implemented the Hydra API. They don’t need to do extra work to integrate specifically with Houdini.

• Commonly, the “top-level” USD file will represent a shot. In a studio, the top-level file will usually reference in files broken down by department (characters, set/props, lights) which have their own references to individual assets. In a smaller or one-person environment, the top-level file might directly reference assets.

• It’s not useful to look at USD reference depth as a measure of “slowness” (or complexity). USD’s composition engine is quite fast. Performance (such as load time) depends more on what is in the layers, and your infrastructure (such as loading files locally or over the network), than how many levels of references there are.

• In USD documentation, they sometimes refer to the scene tree as the namespace.

• Avoid using absolute file paths, and use forward slashes even on Windows.

  Relative path references (for example ./chair.usd) are relative to the layer file containing the reference (for example /Users/Aisha/Work/kitchen.usd).

  For large studios or complex file management cases, it’s probably better to use asset IDs and a custom resolver than to use complicated file paths.

  In Houdini, you will usually store files relative to a directory specified by an environment variable, such as $HIP (the directory containing the scene file), or $JOB (the project directory), or a studio-specific variable). When Houdini writes out USD, it calls output processors to translate file paths. The default output process translates file paths relative to $HIP into paths relative to the top-level USD file, in line with USD’s conventions.

• Introduction to USD (Pixar)

• USD glossary (Pixar)

• USD frequently asked questions (Pixar)