Katana USD Plugins

Katana USD Plugins


The Katana USD plugin was removed from the USD distribution in version 20.05 in favor of the Foundry-supported plugin located at https://github.com/TheFoundryVisionmongers/KatanaUsdPlugins. This documentation remains here for historical reference.


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-related nodes


PxrUsdIn

Parameter

Description

fileName

The asset path to the USD stage. This value is first resolved via the active asset plugin-in.

location

The katana scenegraph location from which the stage will be loaded. The location will be created if it does not yet exist.

isolatePath

Optional path to a USD prim within the stage to use as the root of the read -- omitting the enclosing scopes from the hierarchy.

variants

Deprecated field for specifying variant selections. Use downstream PxrUsdInVariantSelect node instead. Existing values are respected but it's not recommended to author new data in this (intentionally omitted from description here) form.

ignoreLayerRegex

USD layers with matching names will be disabled. While this suppresses inclusion of a layer's opinions, it will not prevent it from being read as the set of layer names is not known in advance. Please note that changes to this value can affect stages in memory besides the one loaded by this PxrUsdIn instance. Flushing caches ensures that this stage will be in the expected state.

motionSampleTimes

Specify motion sample times to load. The default behavior is no motion samples (only load relative frame time 0 – the current katana frame number as seen by the graph State of the PxrUsdIn node).

A space-delimited list of frame-relative sample times to use when motion blur is requested. When more than one sample is specified, all samples present for a given property which contribute to the active shutter window will be used (instead of the motionSampleTimes values directly). This can be overridden with either PxrUsdInDefaultMotionSamples or PxrUsdInMotionOverrides nodes downstream. When not overridden, the temporal direction of the motionSampleTimes is still used to determine whether samples are flipped around the whole frame as a pivot (a convention specific to the Pixar studio).

For the common case, a value of...

0 1

...will load all samples which contribute to the current katana shutter window.

instanceMode

1) "expanded"

In this mode, PxrUsdIn will traverse through instanced references as though they are normal references. This provides direct access to the sub-scopes. The trade-off is that, while USD composition and read benefits from instancing, there's no compression of the katana scenegraph. An "info.usd.masterPrimPath" attribute is deposited at the root location of each expanded instance -- which can be used by downstream instancing techniques.

 2) "as sources and instances"

In this mode, PxrUsdIn will pre-traverse the USD stage to gather the full set of masters. It must find modelName and variant information from the instance scopes in order to produce stable display names for the masters -- which have otherwise neither stable nor human-friendly names.

In this mode, PxrUsdIn will pre-traverse the USD stage to gather the full set of masters. It must find modelName and variant information from the instance scopes in order to produce stable display names for the masters -- which have otherwise neither stable nor human-friendly names.

A location named "Masters" will be made as an immediate child of the value of the "location" parameter. Its children will have three levels of hierarchy:

  1. modelName
  2. concatenation of variant set names and active selections
  3. one or more children following the naming pattern ("m0", "m1", ...) of location type "instance source". In most cases, this will be a single child named "m0". As it's possible (via uncommon composition techniques) for multiple USD masters to produce the same names for hierarchy levels (1) and (2), this pragmatic convention produces an accurate scene. Note that the specific order of the "mXXX" masters is not guaranteed to be stable. It is possible via CEL to match against children of all of them in the rare cases for which this ambiguity arises.

Within the standard scene hierarchy, instanced USD scopes become locations of type "instance" with "geometry.instanceSource" aimed back at the locations within Masters.
If "prePopulate" is not enabled and payloads are present, the "Masters" location will be created at each payload boundary.



usePurposeBasedMaterialBinding
If enabled, material bindings will be queried via UsdShadeMaterialBindingAPI. These bindings are not directly applied to katana's "materialAssign" but rather are placed within a "usd.materialBindings" group attribute to be resolved downstream. The attributes within that group will be named for the mtaching binding purpose. This is to allow for selective application of purposes and optimization of binding granularity. (See PxrUsdInResolveMaterialBindings node.) By default, the "allPurpose" binding is included.
additionalBindingPurposeNames When "usePurposeBasedMaterialBinding" is enabled, this array specifies additional binding purposes should be queried and added to the "usd.materialBindings" group. For example, if you'd like both "preview" and "render" bindings to be present, you'd add them to this list. The PxrUsdInResolveMaterialBindings node can resolve to the specified binding desired for a given context.
prePopulate When enabled, the USD stage will be composed all at once -- reading through any payloads present. Otherwise, payloads are loaded and composed on demand. It's often more efficient (from a threading perspective) to compose every up front. While that can unappealing for cases in which only a portion of the scene is read on the katana side, downstream nodes like PxrUsdInActivationSet and PxrUsdInIsolate can narrow the scope of the composed scene.

verbose

Output additional info during USD scene composition and scenegraph generation.

Graph State Conventions

In addition to its parameter values, PxrUsdIn also supports graphState conventions for overriding behaviors (and populating the USD session layer) from downstream. This can be useful both for altering behavior down branches of the graph and for concatenating contributions from multiple sources (such as downstream LiveGroups managed by different departments).

Note that most of these conventions make use of GroupAttribute-based graph state variables. While that's supported by the underlying graph state architecture, katana's UI and built-in nodes deal only with string-based graph state variables (which are represented by StringAttributes internally). That means that custom node types (defined via the NodeTypeBuilder API) are currently necessary in order to edit or inspect any non-string variables. PxrUsdIn has a suite of companion nodes for making these edits. While those nodes are documented separately, the underlying graph state conventions can be used by custom nodes.


Variable Description
var:pxrUsdInArgs The contents of this GroupAttribute attribute align (in name and type) with the PxrUsdIn node parameters. Anything present will override values on the PxrUsdIn node itself.
var:usdExtraAttributesOrNamespaces This is a StringAttribute in which each value in the array is the name of an USD attribute or namespace to be read independent of properties managed by schema type/kind registered sub-ops of PxrUsdIn. The resulting katana attributes have one-to-one names with namespaces converted to equivalent enclosing GroupAttributes.
var:pxrUsdInSession

The contents of this group describe contributions to the session layer applied atop the USD stage. This allows for edits within the USD stage -- both for optimization (as with activation/deactivation and population masks) and for configuration which is only possible during stage composition (such as variant selection). While not all entries are strictly part of the session layer (population masks are not), they all contribute to the uniqueness of the resulting stage in the cache.

These entries use encoded scenegraph attribute paths. These paths are derived from the resulting katana scenegraph location paths -- and are compared against the root location path of the stage root (so that multiple PxrUsdIn nodes rooted at different locations can distinguish relevant entries).

From python, these encoded path strings (to be valid as attr names) are made via:
FnAttribute.DelimiterEncode('/root/world/geo/some/path')
(Equivalents are available in C++ and lua as well)

Child attrs are in these forms:

Variant selection (typically set via PxrUsdInVariantSelect)

variants.<encoded katana scengraph path>.<variant set name> = StringAttribute(variantSelection)

Scope activation and deactivation  (typically set by PxrUsdInActivationSet)

activations.<encoded katana scengraph path> = IntAttribute(0 or 1)
Attribute overrides (typically set by PxrUsdInAttributeSet)

attrs.<encoded katana scengraph path>.<USD attr name>.value = (Int|Float|Double|String)Attribute


For single element attrs above...

.forceArray = IntAttribute(0 or 1)

...can be added as a peer of value.


Population mask (typically set via PxrUsdInIsolate) mask -> StringAttribute in which each array element is a katana scenegraph location path
Sub-layer references (typically set via PxrUsdSessionSublayer) subLayers -> StringAttribute with tuple size of 2 <katana stage scene root location>, <name or file path of the layer>, ...]






PxrUsdInVariantSelect

Specifies a single variant selection via the session layer of stage loaded via an upstream PxrUsdIn node.


Parameter Description
location A katana scenegraph location which represents a USD prim containing one or more variant sets. These are typically (but not required to be) at the model level. Once selected, the "variantSetName" widget options are filled with the names of the available variant sets.
variantSetName The variant set (e.g. "modeling", "shading") to operate on. While a value can be manually entered, the pop-up options will be automatically filled by what's present on the specified location.
variantSelection The chosen variant selected. While a value can be manually entered, the pop-up options will be automatically filled in by what's present on the current location for the variant set specified with "variantSetName"


PxrUsdInActivationSet

Activates or deactivates scopes within the USD stage via the session layer. Because deactivated scopes (and their children) aren't include in stage composition, it's often more efficient to deactivate something unused there instead of via katana Prune or Isolate nodes. Katana won't read the USD data from locations which are removed due to Prune or Isolate -- but USD stage composition will still consider them

 

Parameter Description
locations One or more katana scenegraph locations loaded from a PxrUsdIn
active

Sets whether the scope will be activated or de-activated.


PxrUsdInDefaultMotionSamples

PxrUsdIn's "motionSampleTimes" parameter allows for manual specification of the frame-relative times at which to sample animated properties. However, the default behavior is include all samples relevant to the shutter window. This allows for automatic recognition of the presence of sub-frame samples for multi-segment motion blur.

For cases in which the value provided to "motionSampleTimes" is desired regardless of what samples are present, the PxrUsdInDefaultMotionSamples can be targeted at one or more locations. The value is inherited by all locations beneath.

Parameter Description
locations

One or more katana scenegraph locations loaded via upstream PxrUsdIn. 

PxrUsdInMotionOverrides

This node allows for per-scope (and below) overrides of the input values used to determine which samples will be read for animated properties. It is a more powerful version of earlier PxrUsdInDefaultMotionSamples node -- which let you revert to using PxrUsdIn's "motionSampleTimes" times explicitly. In addition to being able to directly override "motionSampleTimes" per scope, you can override the current frame and shutter value to guide the otherwise default behavior of adding all available samples which are relevant to the shutter.

The initial use case was for loading samples outside of the active camera shutter for motion effects on Incredibles 2's Dash character. It could also be used to alter or freeze the frame number for an asset or prim (with the trade-off of potentially inaccurate enclosing bounds)

Parameter Description
locations

One or more katana scenegraph locations loaded via upstream PxrUsdIn. 

overrides.motionSampleTimes A space-delimited list of frame-relative sample times to use when motion blur is requested. When specified here, these sample times will be used explicitly – without regard to shutter or sampling of animated attributes

overrides.currentTime

Overrides the frame time. Be aware that this will not be factored into the bound attrs of enclosing scope. It can still be useful as times as an alternative to TimeOffset/Isolate/Merge nodes in katana.
overrides.shutterOpen

Overrides shutterOpen as used for defining the window in which relevant samples are discovered.

overrides.shutterClose

Overrides shutterClose as used for defining the window in which relevant samples are discovered.


PxrUsdInAttributeSet

Because some schemas use USD attribute values directly as part of their computation or interpretation, it can be useful to set attributes within the USD stage rather than only in the katana scene. PxrUsdInAttributeSet mimics the interface of katana's AttributeSet node but sets the value on the stage's session layer instead.

Parameter Description
location

one or more katana location paths on which to set attributes for corresponding USD prim paths.

attrName

the full USD name of the attribute (using ":" for namespaces rather than katana "." for group-delimiters)

type

scalars or arrays of int, float, double and string attributes are currently supported

numberValue When "type" is set to any value besides "string", this parameter array becomes the attribute value. When the parameter array has one element, the attribute is inferred to be scalar. While PxrUsdIn supports forcing the type to be a single element array, this is not yet exposed on the node.
stringValue When "type" is set to "string", this parameter array becomes the attribute value. When the parameter array has one element, the attribute is inferred to be scalar. While PxrUsdIn supports forcing the type to be a single element array, this is not yet

PxrUsdInIsolate

While using a built-in Isolate node allows katana to load a portion of a USD stage, the full stage hierarchy is composed by USD itself. When loading a small portion of a very large USD stage, it can be beneficial to memory and start-up time to use a USD "population mask" to inform composition of what will be used. PxrUsdInIsolate roughly mirrors the interface and behavior of the built-in Isolate node by opening the stage with a population mask.

Parameter Description
locations

one more katana scenegraph location paths

mode Because PxrUsdInIsolate sends its values upstream, you may choose to any replace or append to values provided by upstream PxrUsdInIsolate nodes.

PxrUsdInResolveMaterialBindings

When "usePurposeBasedBindings" is enabled on PxrUsdIn, the bindings available per-purpose will be present in the "usd.materialBindings" attribute. This node will transfer the value for a specified purpose onto the standard "materialAssign" attribute. It will also optionally optimize redundant hierarchical bindings. There is also a Geolib Op with the same name and parameters. It could be registered as a terminal op of the Viewer in order to use a different purpose for display there.

Parameter Description
purpose

The name of the purpose to transfer to katana's standard "materialAssign" attribute.

omitIfParentValueMatches If enabled, a binding will be ignored it its hierarchically inherited value would be equivalent. This is to avoid unnecessary MaterialResolve overhead.


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. 

declareOps.h

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)
 PXRUSDKATANA_USDIN_PLUGIN_DECLARE(PxrUsdInSite_MeshOp)

register.cpp

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)
DEFINE_GEOLIBOP_PLUGIN(PxrUsdInSite_MeshOp) 
 
void registerPlugins()
{
	REGISTER_PLUGIN(PxrUsdInSite_MeshOp, "PxrUsdInSite_MeshOp", 0, 1);
	PxrUsdKatanaUsdInPluginRegistry::RegisterUsdType<UsdGeomMesh>("PxrUsdInSite_MeshOp");
}

<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();
	
	/* YOUR CUSTOM MESH READING CODE */
}

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