USD Frequently Asked Questions

USD Frequently Asked Questions


USD FAQ

General Questions

What is USD and why should I use it?

USD stands for "Universal Scene Description." It is a system for encoding scalable, hierarchically organized, static and time-sampled data, for the primary purpose of interchanging and augmenting the data between cooperating digital content creation applications. USD also provides a rich set of composition operators, including asset and file references and variants, that let consumers aggregate multiple assets into a single scenegraph while still allowing for sparse overrides.

See the Purpose and Overview section of the USD documentation for a more detailed discussion of what USD is (and isn't).

What programming languages are supported?

USD consists of a set of C++ libraries with Python bindings for scripting.

What file formats are supported?

Out of the box, USD includes a human-readable ASCII file format ("usda") and a binary file format ("usdc"), also known as Crate. It also includes support for reading and writing Alembic filesUsers can extend USD to read and write from other file formats by writing a plugin that will translate the data in that format to the USD scenegraph.

What file format is my .usd file?

USD files created with the plain .usd extension, can be either binary-backed Crate files, or ASCII-backed files. This can be advantageous in certain scenarios; for example, if one has USD files which contain references to plain .usd assets, those assets can be converted between binary and ascii without changing the sources which refer to them.

How can I convert USD files between binary and ASCII? 

usdcat can be used to convert files between file formats. With plain, .usd files, you can change them using the --usdFormat option.  Note: although you can specify "–usdFormat usdc", it is not necessary, since the "–out file.usd" argument will, by default choose the usdc format.
$ usdcat file.usd --out file.usd --usdFormat usda

 

Alternatively, one can convert files using the explicit file extensions, such as usda and usdc, directly. 

$ usdcat file.usd --out file.usdc

 

For more information on USD file formats, see Converting Between Layer Formats.

What data types are supported?

See the Basic Datatypes for Scene Description section of the USD documentation for a complete list of supported data types.  USD does not support the addition of new basic datatypes via plugin.

What does a USD file look like?

Here's an example using references, inheritance, and variants. This is the representation generated by the ASCII file format.

solarSystem.usda
#usda 1.0

class "_class_Planet"
{
    bool has_life = False
}

def Xform "SolarSystem"
{
    def "Earth" (
        references = @./planet.usda@</Planet>
    )
    {
        bool has_life = True
        string color = "blue"
    }

    def "Mars" (
        references = @./planet.usda@</Planet>
    )
    {
        string color = "red"
    }

    def "Saturn" (
        references = @./planet.usda@</Planet>
        variants = {
            string rings = "with_rings"
        }
    )
    {
        string color = "beige"
    }
}
planet.usda
#usda 1.0

class "_class_Planet"
{
}

def Sphere "Planet" (
    inherits = </_class_Planet>
    kind = "model"
    variantSets = "rings"
    variants = {
        string rings = "none"
    }
)
{
    variantSet "rings" = {
        "none" {
            bool has_rings = False
        }
        "with_rings" {
            bool has_rings = True
        } 
    }
     
}

This example is purely illustrative. It does not make use of all of the composition operators that USD provides and should not necessarily be taken as a model for how assets should be structured. Different users have different needs; USD simply provides the data encoding and composition operators and lets users decide how best to construct their assets.

The USD Tutorials page contains more examples as well as demonstrations of how to construct those examples using the provided APIs.

Subtler Aspects of Scene Description and Composition

I have some layers I want to combine: Should I use SubLayers or References?

If you have two or more layers that you want to combine so that they override in a particular order, you have two simple options, SubLayers and References.  Which one you should choose depends on both the contents of the layers and what you will need to do with the resulting composition.

If it satisfies your requirements, prefer subLayering over referencing.  SubLayering has the following advantages:

What requirements might make SubLayering inappropriate?

  • If the layers you need to combine to do not share the same namespace, sublayering will simply "overlay" the different namespaces without any possibility of renaming parts of the namespace.  By contrast, references allow you to remap specific prims into a different namespace.  For example, the prim </Bob> in the file Bob.usd can be renamed to "Bob_1" as it is referenced onto the prim </Characters/Bob_1> in the file lineup.usd.
  • Related to the first point, if one or more of your layers contains root prims that you do not want "exposed"  in the resulting composition, references provide a means of doing so: because each time you add a reference you target a specific prim within a layer, you may pick out just the prims you want/need in the composed result.  You can add as many references (even on the same prim) as you require, targeting different prims in the same layer - even targeting prims in the same layer in which you are adding the reference.
  • If you want to add VariantSets that override the result of your composition, you will need to reference your results together rather than sublayer them - or add another layer into the mix so that you can reference in the root layer of your sublayer stack.  This is because the data in the layers that you SubLayer form the L in LIVRPS Strength Ordering, whereas opinions from VariantSets form the V, so anything defined in VariantSets will be weaker than the data in your sublayers.  By extension, if you want to compose several layers into the existing file master.usd, if you sublayer them into master.usd, the direct opinions they contain will be stronger than any Inherits or VariantSet opinions in master.usd, whereas if you reference them in, their opinions will be weaker than any Inherits or VariantSets.

What happens to "overs" when their underlying prim is moved to a different location in the scenegraph?

USD provides the ability to provide sparse overrides for assets that are brought in to the scenegraph via one of the various composition operators. These overrides are referred to as "overs." For instance, consider the following example involving sublayers:

shot.usda
#usda 1.0
(
    subLayers = [
         @sequence.usda@            
    ]
)

over "World"
{
    over "Sets"
    {
        over "Bookshelf"
        {
            over "Book_1"
            {
                string name = "Wall-E"
            }
        }
    } 
}
sequence.usda
#usda 1.0

def Xform "World"
{
    def Xform "Sets"
    {
        def Xform "Bookshelf"
        {
            def Xform "Book_1"
            {
                string name = "Toy Story"
            }
        }

        def Xform "Desk"
        {
        }
     }
} 

In this example, the book defined in sequence.usda has the title "Toy Story". However, this layer is brought in to shot.usda via a sublayer statement, and the book's title is overridden to "Wall-E." The question is: what happens if a user independently working on the sequence.usda file moves Book_1 to Desk, or if Book_1 is renamed to Video_1? In such a case, the "over" in shot.usda would be orphaned and be ignored in the scenegraph for shot.usda. It is the responsibility of the user working on sequence.usda to ensure that shot.usda is updated to avoid this problem.

What's the difference between an "over" and a "typeless def" ?

In a lot of usd files, I see something like:

def "MyModel"
( payload = @./MyModel_payload.usd@ )
{
}

Since we're not saying what type of prim "MyModel" is at this level, why isn't it just 

over "MyModel"

Answer: When you def a prim, you're providing more information to the system than when you over a prim.  

  • def means "Even though I may not be declaring a typed prim in this layer, by the time the UsdStage has finished composing, I expect a type to have been provided by referenced/layered scene description" (in the example, presumably the type would be provided by the layer targetted by the payload arc.
  • over means "If some referenced layer happens to define this prim, then layer the information I contain onto it; but if not, just consider this information ancillary"

This distinction is actually used in the Usd core to define, for e.g., default stage traversal behavior, as UsdPrim::GetChildren() only iterates over a prim's defined children (regardless of whether they possess a type in the current view of the stage), skipping prims that are just over

Build and Runtime Issues

Why Isn't Python Finding USD Modules?

If you get an error message when using USD's Python bindings like this:

Traceback (most recent call last):
  File "./usdGenSchema", line 23, in <module>
    from pxr import Sdf, Usd, Tf
ImportError: No module named pxr

This is caused by your PYTHONPATH environment variable not containing the USD modules. To fix this, simply add USD's Python libraries:

$ export PYTHONPATH=$PYTHONPATH:USD_INSTALL_ROOT/lib/python

Where USD_INSTALL_ROOT represents the CMAKE_INSTALL_PREFIX set in your build configuration. See Advanced Build Configuration for more information.

Why Isn't the Maya/Katana/Alembic Plugin Being Built?

Each plugin USD ships is off by default in the build, to enable any of the plugins, simply activate the following flags in your CMake script, presuming you have the required dependencies.

-DPXR_BUILD_KATANA_PLUGIN
-DPXR_BUILD_MAYA_PLUGIN
-DPXR_BUILD_ALEMBIC_PLUGIN

See Advanced Build Configuration for more information. 

 

 


Graphics Home