Generating New USDRT Schemas using usdGenSchema

Current Schemas

The USDRT schema apis and tokens are easy to use, and familiar to USD users, with the added performance benefits of using the underlying fabric prim.

These are the schemas currently supported in USDRT:

USD Schemas

  • UsdGeom

  • UsdLux

  • UsdMedia

  • UsdRender

  • UsdShade

  • UsdSkel

  • UsdVol

Generated from schema.usda files in USD

Nvidia Physics Schemas

  • UsdPhysics

  • DestructionSchema

  • ForceFieldSchema

  • PhysxSchema

Generated from schema.usda files in usd-ext-physics.

usdGenSchema Command

USDRT provides a code generator script ‘usdGenSchema’ for creating new schema classes. The script functionality is nearly identical to the USD usdGenSchema tool. It is driven by a USD layer (typically named schema.usda) and generates the necessary C++ classes and supporting Python code for all the schema classes defined in it.

The USD layer must meet the same pre-requisites defined for USD.

The tool supports reusing the same USD file already in place to the USD schema, and the USDRT tool will automatically adjust the library paths and target directories to fit the USDRT conventions.

This tool makes it easy to maintain and update existing schema classes, and add new schemas. It’s also easy to regenerate all supported schemas wholesale after adding new functionality to the templates.

What is currently supported?

Supported Schema Types:

  • Concrete Typed Schemas

  • API Schemas

    • Single apply

    • Multiple apply

Supported Feature Set:

  • Codegen templates using Jinja2 template syntax

  • Custom code support (Changes at the bottom of a generated schema file are preserved when regenerated.)

  • Tokens

  • GetAttribute and CreateAttribute API calls

  • GetRelationship and CreateRelationship API calls

Possible Future Support:

  • Schema type identification and registry

  • Integrating this gen schema tool into the repo toolset to sync with USD team

Additional Steps

After generating the schema code by running usdGenSchema, there are a few additional steps to get everything set up and building in the repo.

  • Add the new library to the schema library file for python bindings (see example).

  • Add the new library to the documentation build file

  • Add the new library import to this test

Example: UsdGeom

Source schema.usda file from nv_usd.

Tokens are generated to include/usdrt/scenegraph/usd/usdGeom/tokens.h

Usage Example

C++:

#include "usdrt/scenegraph/usd/usdGeom/tokens.h"
TfToken sizeToken = UsdGeomTokens->size;

Python:

from usdrt import UsdGeom
sizeToken = UsdGeom.Tokens.size

UsdGeomCube

The schema class is generated to include/usdrt/scenegraph/usd/usdGeom/cube.h

Python bindings using pybind11 are generated in source/bindings/python/usdrt/UsdGeom/cube.h

The library wrapper is generated alongside the bindings: source/bindings/python/usdrt/UsdGeom/UsdGeom.cpp

Usage Example

This is an example of a concrete typed schema and getting and setting attributes.

C++:

#include <usdrt/scenegraph/usd/usd/prim.h>
#include <usdrt/scenegraph/usd/usd/stage.h>
#include <usdrt/scenegraph/usd/usdGeom/cube.h>
#include <usdrt/scenegraph/usd/usdGeom/tokens.h>

using namespace usdrt;

UsdStageRefPtr stage = UsdStage::CreateInMemory("test.usda");
UsdPrim prim = stage->DefinePrim("/cube", TfToken("Cube"));

// create attribute using schema api
UsdGeomCube cube = UsdGeomCube(prim);
UsdAttribute attr = cube.CreateSizeAttr();

// get attribute using usdgeom api
UsdGeomCube cube = UsdGeomCube(prim);
UsdAttribute attr = cube.GetSizeAttr();

// get attribute value
double value = 0.0;
attr.Get(&value, 0);

Python:

from usdrt import Sdf, Usd, UsdGeom

stage = Usd.Stage.CreateInMemory("test.usda")
prim = stage.DefinePrim(Sdf.Path("/cube"), "Cube")

# create attribute using schema api
cube = UsdGeom.Cube(prim)
attr = cube.CreateSizeAttr()

# get attribute using schema api
cubeAttr = cube.GetSizeAttr()
val = cubeAttr.Get()

More detailed usage examples can be found in the C++ tests and python tests for UsdGeomCube.

Example: UsdCollectionAPI

The schema class is generated to [include/usdrt/scenegraph/usd/usd/collectionAPI.h]https://gitlab-master.nvidia.com/omniverse/usdrt/-/blob/develop/include/usdrt/scenegraph/usd/usd/collectionAPI.h)

Python bindings using pybind11 are generated in [source/bindings/python/usdrt/Usd/collectionAPI.h]https://gitlab-master.nvidia.com/omniverse/usdrt/-/blob/develop/source/bindings/python/usdrt/Usd/collectionAPI.h)

Usage Example

This is an example of a multiple apply API schema and relationship APIs.

C++:

#include <usdrt/scenegraph/usd/usd/collectionAPI.h>
#include <usdrt/scenegraph/usd/usd/prim.h>
#include <usdrt/scenegraph/usd/usd/stage.h>
#include <usdrt/scenegraph/usd/usd/tokens.h>

using namespace usdrt;

UsdStageRefPtr stage = UsdStage::Open("./data/usd/tests/test_collection.usda");

UsdPrim testPrim = stage->GetPrimAtPath(SdfPath("/CollectionTest"));
UsdPrim sphere = stage->GetPrimAtPath(SdfPath("/CollectionTest/Geom/Shapes/Sphere"));

UsdCollectionAPI explicitColl = UsdCollectionAPI(testPrim, "test");

// create rel using schema api
UsdRelationship rel = explicitColl.CreateIncludesRel();
// testPrim.HasRelationship("collection:test:includes") == true

// get relationahip using schema api
 UsdRelationship rel = explicitColl.GetIncludesRel();
// rel.GetName() == TfToken("collection:test:includes");

Python:

from usdrt import Sdf, Usd

stage = Usd.Stage.Open(TEST_DIR + "/data/usd/tests/test_collection.usda")

testPrim = stage.GetPrimAtPath("/CollectionTest")
sphere = stage.GetPrimAtPath("/CollectionTest/Geom/Shapes/Sphere")

explicitColl = Usd.CollectionAPI(testPrim, "test")

# create rel using schema api
rel = explicitColl.CreateIncludesRel()

# verify get relationship using schema api
inclRel = coll.GetIncludesRel()
# inclRel.GetName() == "collection:test:includes"

More detailed usage examples can be found in the C++ tests and python tests for UsdCollectionAPI.