USD Python API Notes
The USD APIs for C++ are well defined at Pixar's API Documentation. However, for Python there are some differences overall between C++ and Python which leads to confusion when you're trying to call a function you know exists based on the documentation.
C++ vs Python
In the C++ USD API classes are named using a pattern that always includes their high-level USD prefix. For example,
UsdGeomImageable both include Usd in the name (there are other high-level prefixes such as Sdf and Tf). However in Python classes are grouped into a hierarchy that is not always based on a common prefix, so extra attention is required to correlate C++ and Python classes.
For example, there is a
Usd module inside the root
pxr module (all of the USD API exists in the
pxr module), but you won't find C++'s
Usd , or
GeomIMageable , instead
UsdGeomImageable is found under
However C++'s '
UsdPrim class does exist under
Usd , simple as
So when you read the API Documentation for UsdPrim or some other C++ class and you want to apply that information to Python, you need to drop some part of the class name from the beginning and turn it into the module. For example:
# analog to the UsdPrim() constructor in C++ from pxr import Usd prim = Usd.Prim()
And to create a
UsdGeomSphere it would be:
# analog to the UsdGeomSphere() constructor in C++ from pxr import Usd, UsdGeom invalid_prim = Usd.Prim() sphere = UsdGeom.Sphere(invalid_prim)
USD Python Module Names
Below is a list of Python Modules that are declared in the
pxr module. These will help you find the translation between C++ and Python from the API Documentation. To find the equivalent class (for example
UsdGeomSphere ), first find the longest prefix that appears in the list below (so
UsdGeom ), remove the prefix and refer to the class as the resulting string inside that module (so
|Usd (this contains important subclasses like UsdPrim )|
If you're wondering how to put this advice into practice, let's try to find out how to refer to C++'s UsdLuxDistantLight's Python API, specifically the
- Look at the table above, and try to find the longest module name that exists in the name of
UsdLuxDistantLight. You will see that it is UsdLuxDistantLight.
- Now, you can import that module and look inside to make sure that DistantLight is defined:
from pxr import UsdLux # if you are in the Python REPL you can just write dir(UsdLux) print(dir(UsdLux)) # Output is: ['BlackbodyTemperatureAsRgb', 'CylinderLight', 'DiskLight', 'DistantLight', 'DomeLight', 'GeometryLight', 'Light', 'LightFilter', 'LightPortal', 'ListAPI', 'RectLight', 'ShadowAPI', 'ShapingAPI', 'SphereLight', 'Tokens', '__MFB_FULL_PACKAGE_NAME', '__builtins__', '__cached__', '__doc__', '__file__', '__loader__', '__name__', '__package__', '__path__', '__spec__', '_usdLux']
- We can see that
DistantLightis exposed as an object, and if we want to be sure we're in the right spot we can repeat the above to see what is available within
from pxr import UsdLux # if you are in the Python REPL you can just write dir(UsdLux.DistantLight) print(dir(UsdLux.DistantLight)) # Output is: ['AddOrientOp', 'AddRotateXOp', 'AddRotateXYZOp', 'AddRotateXZYOp', 'AddRotateYOp', 'AddRotateYXZOp', 'AddRotateYZXOp', 'AddRotateZOp', 'AddRotateZXYOp', 'AddRotateZYXOp', 'AddScaleOp', ... snipped]
- Now you may be wondering why are there so many more exposed objects above versus the "Public Member Functions" on UsdLuxDistantLight's API page, and that's because
UsdLuxDistantLightinherits from a few other classes (notably
UsdGeomXformable), so we're seeing the full object namespace. It is extremely useful to open the Inheritance Diagram in the C++ class’ API documentation that you're inspecting, things become clear there.