=========================================== 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 ##############

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

.. code-block:: python

  from pxr import Usd, UsdGeom
  stage = Usd.Stage.CreateNew('HelloWorld.usda')
  xformPrim = UsdGeom.Xform.Define(stage, '/hello')
  spherePrim = UsdGeom.Sphere.Define(stage, '/hello/world')
  stage.GetRootLayer().Save()

#. Execute the Python script to create :filename:HelloWorld.usda.

.. code-block:: sh

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

Visualizing the stage #####################

Use :ref:toolset:usdview to visualize and inspect the stage.

#. Open the stage in usdview:

.. code-block:: sh

  $ usdview HelloWorld.usda

.. image:: http://openusd.org/images/tut_helloworld_sphere_1.png

#. You can refine the geometry with the :menuselection:Display --> Complexity menu item or use the hotkeys :kbd:Ctrl-+ and :kbd:Ctrl-- to increase or decrease the refinement.

.. image:: http://openusd.org/images/tut_helloworld_sphere_2.png

#. You can also bring up an embedded Python interpreter by pressing :kbd:i or using the :menuselection:Window --> Interpreter menu item. This interpreter has a built-in API object, :python:usdviewApi, that contains some useful variables. One is :python: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, :usda:world, in the tree view on the left. Then try the following commands:

usdviewApi.prim Usd.Prim(</hello/world>) usdviewApi.prim.GetTypeName() 'Sphere' usdviewApi.prim.GetAttribute('radius').Get() 1.0

Viewing and editing USD file contents #####################################

The exported file is human-readable via :ref:toolset:usdcat and text-editable via :ref:toolset:usdedit (both available in :filename:USD_INSTALL_ROOT/bin in the default installation). The :ref:toolset:usdedit program will bring up any .usd file as plain text in your :envvar:EDITOR regardless of its underlying format, and save it back out in its original format when editing is complete. See :ref:toolset: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 :filename:.usda extension. If we had created a binary usd file with the :filename:.usdc extension instead, both :ref:toolset:usdcat and :ref:toolset:usdedit would work just the same on it.

.. code-block:: usda

#usda 1.0

def Xform "hello" { def Sphere "world" { } }

.. admonition:: Further Reading

:usdcpp:UsdStage is the outermost container for scene description, which owns and presents composed prims as a scenegraph.
:usdcpp:UsdPrim is the sole persistent scenegraph object on a :usdcpp:UsdStage.