Hello World - Creating Your First USD Stage

This tutorial walks through creating a simple USD stage containing a transform and a sphere.

Python for USD

  1. Open USD/extras/usd/tutorials/helloWorld/helloWorld.py to see the Python script that creates and exports the stage. It should look like the following.

    from pxr import Usd, UsdGeom
    stage = Usd.Stage.CreateNew('HelloWorld.usda')
    xformPrim = UsdGeom.Xform.Define(stage, '/hello')
    spherePrim = UsdGeom.Sphere.Define(stage, '/hello/world')
  2. Execute the Python script to create HelloWorld.usda.

    $ python extras/usd/tutorials/helloWorld/helloWorld.py

Visualizing the stage

Use usdview to visualize and inspect the stage.

  1. Open the stage in usdview:

    $ usdview HelloWorld.usda
  2. You can refine the geometry with the View ‣ Complexity menu item or use the hotkeys Ctrl-+ and Ctrl-- to increase or decrease the refinement.

  3. You can also bring up an embedded Python interpreter by pressing i or using the Window ‣ Interpreter menu item. This interpreter has a built-in API object, usdviewApi, that contains some useful variables. One is usdviewApi.prim, which refers to the first prim, hierarchically, in the set of currently selected prims.

    Select the sphere either by clicking it in the viewport or by clicking its name, world, in the tree view on the left. Then try the following commands:

    >>> usdviewApi.prim
    >>> usdviewApi.prim.GetTypeName()
    >>> usdviewApi.prim.GetAttribute('radius').Get()

Viewing and editing USD file contents

The exported file is human-readable via usdcat and text-editable via usdedit (both available in USD_INSTALL_ROOT/bin in the default installation). The usdedit program will bring up any .usd file as plain text in your EDITOR regardless of its underlying format, and save it back out in its original format when editing is complete. See usdedit for more details.

This particular example can be edited in a text editor directly since we created a text-based USD file with the .usda extension. If we had created a binary usd file with the .usdc extension instead, both usdcat and usdedit would work just the same on it.

#usda 1.0

def Xform "hello"
    def Sphere "world"

Further Reading

  • UsdStage is the outermost container for scene description, which owns and presents composed prims as a scenegraph.

  • UsdPrim is the sole persistent scenegraph object on a UsdStage.