Katana USD Plugins

Katana USD Plugins

Configure Environment

There are a couple of prerequisites to using the Katana plugins.

  • Ensure that you built the Katana plugins, this is enabled in the build with -DPXR_BUILD_KATANA_PLUGIN passed as an option to cmake. 
  • Ensure that the following environment variables are configured. We'll refer to the install location of your USD build with USD_INSTALL_ROOT, this is determined in the build with the cmake flag, -DCMAKE_INSTALL_PREFIX.
Name Meaning Value
PYTHONPATH This is a path list which Python uses to find modules, needed for usdview. $PYTHONPATH:USD_INSTALL_ROOT/lib/python/
KATANA_RESOURCES This is a path list which Katana uses to find plugins. $KATANA_RESOURCES:USD_INSTALL_ROOT/third_party/katana/plugin
KATANA_POST_PYTHONPATH This is a path list which Katana uses to find python modules. $KATANA_POST_PYTHONPATH:USD_INSTALL_ROOT/third_party/katana/lib


For more information see our page on Advanced Build Configuration.


Reading USD into Katana: PxrUsdIn

To read your USD files into Katana, we provide a PxrUsdIn node.  Here are the available parameters you'll find on the node:




The USD file to read.


The Katana scenegraph location to load the USD contents.


Load only the USD contents below the specified USD prim path.


Specify variant selections. Variant selections are specified via whitespace-separated variant selection paths. Example: /Foo{X=Y} /Bar{Z=w}


Ignore matching USD layers during USD scene composition.


Specify motion sample times to load. The default behavior is no motion samples (only load current time 0).


When using expanded USD instances will be unrolled as though the children of their masters were naturally present.

When using  as sources and instances , masters will be created under a sibling of World named /Masters. Instanced USD prims will be of type "instance" and have no children.


Output additional info during USD scene composition and scenegraph generation.

Customizing PxrUsdIn

PxrUsdIn Op

This is the primary Op that is added to the op chain by the PxrUsdIn node which you'll find in USD_INSTALL_ROOT/third_party/katana/plugin/op/pxrUsdIn/pxrUsdIn.cpp.  It will parse the PxrUsdIn arguments and read the USD file accordingly.  As the USD stage is traversed, each prim is checked against the various plugin registries to determine which sub Op should be executed to process the prim on it's way to becoming a scenegraph location.

Plugin Registries

Out of the box, we provide you with registered plugins for all standard USD types and USD Model kinds (i.e. group, component, subcomponent, etc).  You may choose to customize by adding additional plugins that should run on those standard types and kinds, or ones that run on your own custom types or kinds.  What's important to note is the order in which these plugins are executed on a prim.  This dictates the strength of opinions.  If two plugins author the same attribute, the one running latest will win.  The PxrUsdIn Op checks the registries and will run on any matching plugins in the following order (where Site-specific means your own plugins):

  • Shipped Usd Type Plugins
  • Site-specific Usd Type Plugins
  • Shipped Kind Plugins
  • Site-specific Kind Plugins

Overriding Motion Values

We provide you with two nodes for overriding the motion-related values that PxrUsdIn uses when fetching USD data. Such values include: motion sample times, current time, shutter open, and shutter close. Both nodes have a "locations" parameter to specify the root location(s) at which the overrides should start to take effect. Child locations hierarchically inherit the overrides. The PxrUsdInDefaultMotionSamples node ensures that the default motion sample times (the ones specified by the PxrUsdIn node's motionSampleTimes parameter) will be used, regardless of how USD attribute data is sampled. The PxrUsdInMotionOverrides node permits specification of arbitrary values for motion sample times, current time, shutter open, and shutter close. Again, these values will be used regardless of how USD attribute data is sampled. Motion sample times are space delimited and should be specified in order from open to close.

Time Scaling

PxrUsdIn honors a UsdStage's authored timeCodesPerSecond and framesPerSecond.

When framesPerSecond differs from timeCodesPerSecond, the current time, motion samples, and shutter window (specifically, shutter close) will be scaled appropriately when fetching data from the UsdStage. The ratio of timeCodesPerSecond to framesPerSecond (tcps/fps) is used for this scaling.

Note that time scaling is not applied to values specified via the override nodes described above.

Katana's timeline will still display unscaled frame numbers. For example, if the UsdStage's startTimeCode is 101, then selecting frame 105 in Katana will be equivalent to pulling in UsdStage data at time 101 + ( (105 - 101) * (tcps / fps) ). This in turn means that the Katana timeline needs to be stretched or compressed by the ratio of framesPerSecond to timeCodesPerSecond (fps/tcps) in order to accommodate the UsdStage's full frame range.

Writing Your Own Plugins

For examples of how to write and register your own plugins, we direct you to USD_INSTALL_ROOT/third_party/katana/plugin/op/pxrUsdInShipped/.  There you'll find all of the shipped plugins for the standard USD types and Model kinds. 


This is where the shipped plugin class declarations live.  When writing your own plugins, you'll want to declare them following the pattern you find here.  We've provided you with a PXRUSDKATANA_USDIN_PLUGIN_DECLARE macro that, given a plugin name, declares the GeolibOp subclass with that name, as well as it's standard setup and cook functions.  If, for example, you wanted to declare your own plugin for handling UsdGeomMesh types, you would write:

Plugin Class Declaration (see USD_INSTALL_ROOT/third_party/katana/plugin/op/pxrUsdInShipped/declareCoreOps.h)


This is where the shipped plugins are defined and registered, both with Geolib and the PxrUsdIn plugin registries.  When writing your own plugins, you'll want to define and register them following the pattern you find here.  In following our current example, here's what you would need if you were registering your own plugin for handling UsdGeomMesh types:

Register Plugin (see USD_INSTALL_ROOT/third_party/katana/plugin/op/pxrUsdInShipped/register.cpp)
void registerPlugins()
	REGISTER_PLUGIN(PxrUsdInSite_MeshOp, "PxrUsdInSite_MeshOp", 0, 1);

<plugin name>.cpp

Lastly you'll need to implement your plugin.  We've provided you with a PXRUSDKATANA_USDIN_PLUGIN_DEFINE macro that handles and abstracts away all of the required Op function definitions so that you can simply fill in your plugin implementation.  The arguments to the macro are:

  • plugin name: This should match the previously declared and registered name.
  • private data name: This is the name assigned to the PxrUsdKatanaUsdInPrivateData object that you will use to access the UsdPrim and PxrUsdKatanaUsdInArgs (for more info, see USD_INSTALL_ROOT/third_party/katana/lib/usdKatana/usdInPrivateData.h).
  • interface name: This is the name assigned to the Foundry::Katana::GeolibCookInterface object that you will use to set Katana attributes.

In following with our current example, here's what you would need if you were implementing your own plugin for handling UsdGeomMesh types:

Plugin Implementation (see USD_INSTALL_ROOT/third_party/katana/plugin/op/mesh.cpp)
PXRUSDKATANA_USDIN_PLUGIN_DEFINE(PxrUsdInSite_MeshOp, privateData, interface)
	const UsdPrim& prim = privateData.GetUsdPrim();

UsdKatana Library

This is the core library used for reading USD types and Model kinds into Katana attributes (see USD_INSTALL_ROOT/third_party/katana/lib/usdKatana/).  You may want to make use of this when writing plugins to read your own custom types or kinds.


Graphics Home