New in Katana 4

This page documents how we export Katana Attributes to USD.

To make the UsdMaterialBake node and the UsdExport plug-in available, ensure you have followed the GettingStarted page for Katana USD Plug-ins. In particular How do I Enable the Katana USD Plug-ins?.


UsdMaterialBake is implemented as a SuperTool, and has been designed to provide an example of the new ability to write custom nodes for export using extensions in the existing LookFileBakeAPI and Nodes3DAPI: LookFileBakeAPI.LookFileBaker and Nodes3DAPI.LookFileBaking. The node type is designed to provide an override layer that needs to be applied back in USD over the asset that is being look-developed.

The UsdMaterialBake will write out differences in the output scene graph between the cooked op at the original (first input) and each of the other inputs in turn, each written out as separate variants. Assigned materials under /root/materials will also be written; a process much like the LookFileBake node.

UsdExport Architecture

The UsdExport codebase has been designed to be extensible to more than just the Materials and shading data we already provide. The LookFileBakeAPI provides us the construct of scene graph differences between the first and each other port. This fits with the USD layering ideas, where the base USD asset is imported, some edits are performed in Katana’s node graph in a non-destructive manner, and a layer is written out containing the difference back to Usd. This layer can then be passed to other applications or back into Katana itself.

The modules to support writing out attributes to USD are located in the /Usd/lib/python folder, and any additional modules which could be used in Katana, (externally to the baking process) should be added here. This allows us to import modules such as UsdExport.material, to gain easy access to writing out the material attributes to USD for other purposes, for example, shelf scripts.

Supported Behavior Out-of-the-Box

The out-of-the-box experience with UsdExport supports the following behaviors
  • Material and shader writing to UsdShade

  • UsdLux Light writing including geometry and shadow linking

  • External renderer light writing through the Sdr Registry

  • Material assignments

  • Material interfaces

  • Multiple variants

  • Conversion from child materials to sibling materials.

Katana to USD Differences

Due to differences in design there are some sections of Katana where we have had to make adjustments to ensure the Katana attributes and locations exported work in a USD file loaded into any other application by default. This section will go over these changes.

Child Materials

USD does not use the concept of parent-child inheritance of attributes, as Katana does. Materials are also not meant to be nested within each other. This means we must change the hierarchy of child materials to being sibling materials. To try to ensure we do not name clash, we rebuild the name as the concatenation of the parent and child name, separated by an underscore _. We then use the specializes USD composition arc by use of the UsdShade.Material SetBaseMaterial method. This then ensures our child material, which is now a sibling, still inherits its base attributes from its original parent. We also apply the LookAPI schema, shipped with the Katana USD Plug-ins, which also saves the original name of the child location. This is ready to be used to re-build the parent-child relationship when re-importing.

Material and Shader Writing

UsdExport uses UsdShade to write out the material and shader information. This means in order to write out a material and its shaders, the shaders themselves need to be registered in the Shader Registry (Sdr). You can quickly check which shaders you have available in your USD setup by running the following the python code below.

# Replace fnpxr with pxr if not using the Usd Shipped with Katana
from fnpxr import Sdr
print Sdr.Registry().GetNodeNames()

The reason this information is required is to ensure that we can write the correct type information onto the Shader, since the types in USD and the types in Katana differ. For example, a file path in USD can be represented by the Asset type, whereas in Katana, it is the String type.

Light Writing

UsdExport uses the UsdLux Lighting Schema to write out UsdLux light shaders with the light prim type, parameter names and parameter types. Katana attribute names are matched against the UsdLux concrete prim, shaping API and shadow API parameters and where matches are found, the value is written with the corresponding parameter name and type.

The UsdExport.lightLinking module allows writing of Light and Shadow linking to a prim location. This uses the attributes found in the light list at the /root/world scene graph location.

Lights from External Renderers

Lights added by external renderers are written through an included UsdExport plug-in. In order for this plugin to write out these lights, the light must be registered in the Shader Registry (Sdr). Any lights written through this plugin will have the prim type of Light, this is due to a limitation in the USD 21.05 Shader Registry whereby shaders are not linked to a concrete prim type. Where both a external renderer light shader and a UsdLux light shader exist on the same location, the concrete prim type will be set to that matching the UsdLux shader type. If you wish to set the prim type yourself based on the light attributes, this can be done through the UsdExport Plug-ins system.

Registering Renderer Shaders

To register more renderer shaders you must build that Renderer’s USD NdrParserPlugin. These are usually in the same source code as the render delegates, although can be separate. As stated in the GettingStarted page, there are two ways to use USD in Katana, either using your own USD and Katana USD Plug-ins, or those shipped with Katana by default.

If you are using your own USD, you must build the Katana USD Plug-ins against your own USD, and then also build the renderer’s NdrParserPlugin against your own USD. You will then have to add the plugin folder to the PXR_PLUGINPATH_NAME environment variable.

If you wish to continue using the plug-ins and the USD we ship with Katana, you must build the NdrParserPlugin’s against our USD. See the section Building Katana USD Plug-ins for more information on building the Katana USD Plug-ins. You will then have to add the installed plugin folder to the FNPXR_PLUGINPATH environment variable.


UsdExport.light.WriteLight(stage, lightSdfPath, materialAttrs)

Converts the given light material GroupAttribute into a Usd.Prim. If the Sdf.Path does not exist, it will be created. Any existing prim type will be overwritten with with either the corresponding UsdLux light type or ‘Light’ if a non-UsdLux light type is being written.

Return type:


  • stage (Usd.Stage) – The USD stage to write the light to.

  • lightSdfPath (Sdf.Path) – The path to write the UsdLux.Light to.

  • materialAttrs (FnAttribute.GroupAttribute) – The light attribute from Katana’s scenegraph for the light location.


The Usd.Prim created by this function

UsdExport.light.WriteLightList(stage, prim=None)

Computes the light list on the given stage with compute mode of UsdLux.ListAPI.ComputeModeIgnoreCache. The light list will be written to the provided prim, or the stage’s default prim if not provided.

  • stage (Usd.Stage) – The Usd.Stage to write data to.

  • prim (Usd.Prim) – Optional prim to write the Usd List to, if not provided, the stage’s default prim will be used.


Creates a dictionary mapping shaders to light attributes for the given material attributes. The dictionary key is a tuple of str for the renderer name and str for the shader name, for example ("prman", "PxrDiskLight) or ("usd", "UsdLuxRectLight)

Return type:

dict of (tuple of str) : FnAttribute.GroupAttribute


materialAttrs (FnAttribute.GroupAttribute) – The material group attribute to read from.


A dictionary mapping the renderer prefixed shader name to the attributes for that light.

UsdExport.lightLinking.WriteLightLinking(stage, sdfLocationPath, lightListAttribute, lightDict, rootName)

Write Resolved Light Linking information onto the light linked to this location.

  • stage (Usd.Stage) – The Usd.Stage to write data to.

  • sdfLocationPath (Sdf.Path) – The translated relative path for where this prim would be in the Usd Stage.

  • lightListAttribute (FnAttribute::GroupAttribute) – The Katana attribute containing lightList.

  • lightDict (dict of str : Sdf.Path) – A dictionary containing a mapping between the light location paths from Katana, and the SdfPath in the USD Stage.

  • rootName (str) – The root name from the overrideDictList, see LookFilePassData for more details.

UsdExport.lightLinking.AppendLightLinkToLight(sdfLocationPath, lightLinkEnableAttr, shadowLinkEnableAttr, lightPrim)

Appends light linking information for the sdfLocationPath to the provided lightPrim

  • sdfLocationPath (Sdf.Path) – The translated relative path for where the light linking applies to.

  • lightLinkEnableAttr (FnAttribute::IntAttribute or None) – The lightList.<lightName>.enable attribute

  • shadowLinkEnableAttr (FnAttribute::IntAttribute or None) – The lightList.<lightName>.geoShadowEnable attribute

  • lightPrim (Usd.Prim) – The prim for the light to write the light linking relation to.

UsdExport.lightLinking.CreateCollectionAttribute(prim, collectionName, paramFunc, location)

Helper method to write collection data given the function and name of link.

  • prim (Usd.Prim) – The prim to write the collection to.

  • collectionName (str) – The name of the collection to write.

  • paramFunc (function) – The collection api function to use.

  • location (Sdf.Path) – The location to write into the collection.

UsdExport.material.WriteChildMaterial(stage, materialSdfPath, materialAttribute, parentMaterialSdfPaths)

Writes a Katana child material as a sibling material, inheriting from the parent material paths (the whole hierarchy stored in order) by use of BaseMaterials.

Return type:

UsdShade.Material or None

  • stage (Usd.Stage) – The USD stage to write the material to.

  • materialSdfPath (Sdf.Path) – The SdfPath to write this new child material to. Child materials should use the name of the parent material and the name of the child material separated by an underscore, e.g: GrandParentMaterial_ParentMaterial_ChildMaterial. Where the hierarchy of Katana Material locations was: GrandParentMaterial –ParentMaterial —-ChildMaterial

  • materialAttribute (FnAttribute.GroupAttribute) – The material attribute. Usually a sparse group attribute, with the change from the parent’s material Attribute.

  • parentMaterialSdfPaths (list) – A list of the parent SdfPaths, in order from youngest parent, to oldest. Used to read the attribute types from the oldest parent, but specialize/inherit from the youngest parent.


The material created by this method or None if no child material was created.

UsdExport.material.WriteMaterial(stage, materialSdfPath, materialAttribute)

Converts the given material GroupAttribute into a UsdShade.Material along with all the shaders and their connections.

Return type:

UsdShade.Material or None

  • stage (Usd.Stage) – The USD stage to write the material to.

  • materialSdfPath (Sdf.Path) – The path to write the UsdShade.Material to.

  • materialAttribute (FnAttribute.GroupAttribute) – The material attribute from Katana’s scenegraph for the material location.


The UsdShade.Material created by this function or None if no material was created.

UsdExport.material.AddShaderLayout(shaderLayoutAttr, shader)

Adds UsdUI.NodeGraphNodeAPI attributes to shader prim such as: * Position * Color * View State

  • shaderLayoutAttr (FnAttribute.GroupAttribute) – Layout group attribute of the shader.

  • shader (Sdf.Path) – The UsdShader shader object from the Usd Stage.

UsdExport.material.CreateEmptyShaders(stage, materialNodes, materialPath)

Creates all the shader prims for the current material but only fills in the type. This is because the connections require both materials to be present. The parameters are populated at a later stage, once all shaders for this material are created. Called by WriteMaterial.

  • stage (Usd.Stage) – The Usd.Stage to write the shaders to.

  • materialNodes (FnAttribute.GroupAttribute) – The material.nodes FnAttribute.GroupAttribute from the attributes of the current location.

  • materialPath (Sdf.Path) – The path to the material in the Usd Stage.

UsdExport.material.AddTerminals(stage, terminals, material)

Adds the terminals onto the USD material. Called by WriteMaterial.

  • stage (Usd.Stage) – The Usd.Stage to write to.

  • terminals (FnAttribute.GroupAttribute) – The material.terminals attribute

  • material (The Material to write the terminals to.) – The Material to write the terminals to.

UsdExport.material.AddMaterialParameters(parametersAttr, shaderId, shader)

Iterates through all the parameters in parametersAttr. Adds the parameters onto the shader, calls AddParameterToShader. Called by WriteMaterial.

  • parametersAttr (FnAttribute.GroupAttribute) – The GroupAttribute relating to material.nodes.<nodeName>.parameters.

  • shaderId (str) – The str ID of the shader (its type).

  • shader (Usd.Shader) – The UsdShader shader object from the Usd Stage.

UsdExport.material.AddParameterToShader(shaderParamName, paramAttr, shader, shaderId=None, paramName=None, sdfType=None)

Adds a parameter as an input onto a given Shader or Material prim.

Return type:

Usd.Shader.Input or None

  • shaderParamName (str) – The parameter name as it appears on the shader. This is used to determine the type of the shader attribute.

  • paramAttr (FnAttribute.GroupAttriute) – The Katana attribute to read the value from, as well as timesamples.

  • shader (UsdShade.Shader) – The shader or material to add the shaderInput onto. If this is not the shader the parameter originally belongs to, and is part of a material interface, the shaderId should also be provided for the shaderId of the shader the param would have originally be set to. This is in order to retrieve the correct SdfType.

  • shaderId (str) – The Id of the shader to search for the SdrShadingNode to search for the parameters sdfType. This should be provided if the shader provided is not the shader you want to write to is not the SdrShaderNode you want to read the inputs and therefore sdfTypes from.

  • paramName (str) – Optional argument. The name to be given to the attribute on the shader. This can differ from the shaderParamName in cases of material parameter interfaces.

  • sdfType (NdrSdfTypeIndicator) – Optional argument, This can override any retrieval of sdfType from the shader, or shaderId from the Usd SdrRegistry. This is useful if you want to use the sdfType from connected attributes; this is used for material interfaces.


The shader input created by this method or None if no shader input was created.

UsdExport.material.AddShaderConnections(stage, connectionsAttr, materialPath, shaderPath)

Adds the connections between the shaders from the material.nodes.<nodeName>.connections attribute. The shaders must be written first in order to connect to the current shader. The types will be read from the Usd shader info from the GetShaderAttrSdfType method. Both shaders must be part of the same material. Called by WriteMaterial.

  • stage (Usd.Stage) – The Usd stage to write to.

  • connectionsAttr (FnAttribute.GroupAttribute) – The material.nodes.<nodeName>.connections Katana attribute to read the connection information from.

  • materialPath (Sdf.Path) – The USD path for the material for this shader and the shader it will connect to.

  • shaderPath (Sdf.Path) – The USD path for the shader to add the connection to.

UsdExport.material.OverwriteMaterialInterfaces(parametersAttr, material, parentMaterial)

For child materials, this method overwrites the material interface values rather than creating anything new from the attributes. Called by WriteChildMaterial.

  • parametersAttr (FnAttribute.GroupAttribute) – The material.parameters attribute from the current Katana location.

  • material (UsdShade.Material) – The child material to write the new values for the material interface

  • parentMaterial (UsdShade.Material) – The parent material to read the interface attribute information from, including its type. This must be the highest level parent material.

UsdExport.material.AddMaterialInterfaces(stage, parametersAttr, interfacesAttr, material)

Adds the parameter interface attributes onto the material, and add connections from the shader to these values. Called by WriteMaterial.

  • stage (Usd.Stage) – The Usd Stage to write the new prims and parameters to

  • parametersAttr (FnAttribute.GroupAttribute) – The attribute from materials.parameters. If no parametersAttr is provided, this is assumed to then be the default value.

  • interfacesAttr (FnAttribute.GroupAttribute) – The attribute from materials.interface

  • material (UsdShade.Material) – The material prim to add the parameter interface to.

UsdExport.material.GetShaderAttrSdfType(shaderType, shaderAttr, isOutput=False)

Retrieves the SdfType of the attribute of a given Shader. This is retrieved from the Usd Shader Registry Sdr.Registry. The shaders attempted to be written must be registered to Usd in order to write correctly. If not found in the Shader Registry, try to do our best to find the type from the RenderInfoPlugin.

Return type:


  • shaderType (str) – The name of the shader.

  • shaderAttr (str) – The name of the attribute on the shader.

  • isOutput (bool) – Whether the attribute is an input or output. False by default. Set to True if the attribute is an output.


The Usd Sdf Type for the attribute of the provided shader or None if the shaderType cannot be found or the shaderAttr cannot be found.

UsdExport.material.WriteMaterialAssign(material, overridePrim)

Apply the UsdShade.MaterialBindingAPI to the overridePrim and bind the material.

  • material (UsdShade.Material) – The material to bind.

  • overridePrim (Usd.OverridePrim) – The Prim to bind to.

UsdExport.prmanStatements.WritePrmanStatements(prmanStatementsAttributes, prim)

This function will write out ‘prmanStatements’ to a prim using UsdRi.StatementsAPI schema. Currently we are only writing out ‘prmanStatements.attribute’.

  • prmanStatementsAttributes ((str, FnAttribute.Attribute)) – A 2-element tuple with the first element being the name of the attribute and the second the attribute itself.

  • prim (Usd.Prim) – A prim to write prmanStatements to.

UsdExport.prmanStatements.WritePrmanGeomGprims(prmanStatementsAttributes, prim)

This function will write out prmanStatements to a prim using UsdGeom.Gprim schema. Currently it only writes out: “prmanStatements.sides” “prmanStatements.attributes.Sides” “prmanStatements.orientation”

  • prmanStatementsAttributes ((str, FnAttribute.Attribute)) – A 2-element tuple with the first element being the name of the attribute and the second the attribute itself.

  • prim (Usd.Prim) – A prim to write prmanStatements to.

UsdExport.prmanStatements.WritePrmanModel(prmanStatementsAttributes, prim)

This function will make the prim a ‘model’ kind depending on the value of ‘scopedCoordinateSystemAttr’.

  • prmanStatementsAttributes ((str, FnAttribute.Attribute)) – A 2-element tuple with the first element being the name of the attribute and the second the attribute itself.

  • prim (Usd.Prim) – A prim to write prmanStatements to.

UsdExport.transform.WriteTransform(stage, xformSdfPath, xformAttrs)

Writes transform attributes to the specified location. If the location does not exist, it will be created. Any existing prim type will be overwritten with with ‘Xform’.

Return type:


  • stage (Usd.Stage) – The USD stage to write the transform to.

  • xformSdfPath (Sdf.Path) – The path in the stage to write the attributes to.

  • xformAttrs (FnAttribute.GroupAttribute) – The Katana attributes to write to the Usd Stage.


Returns the prim with the transform attributes applied.

Module containing some helpful conversion maps to assist in type conversions.


Converts the given tags from the relevant Katana RenderInfoPlugin into SdfTypes.

Return type:

Sdf.ValueTypeNames or None


tags (list or str) – a list of tags, or a string of tags separated by “or”.


The closest Sdf type, or None if no match can be found.


Converts an array into Vt.Vec3fArray.

Return type:



array (List or PyFnAttribute.ConstVector) – A array to convert to Vt.Vec3fArray.


The resulting Vt.Vec3fArray or an empty Vt.Vec3fArray.

UsdExport.typeConversionMaps.ConvertParameterValueToGfType(value, sdfType)

Converts the Katana attribute into its equivalent Gf type based on the sdfType provided.

Return type:


  • value (PyFnAttribute) – The value to be cast to a Gf equivalent.

  • sdfType (Sdf.ValueTypeNames) – The type to cast to.


The Gf type casted value.

UsdExport Plug-ins

A new type of plug-in has been added to allow further customization of the USD Export process without the need to rebuild the Katana USD plug-ins. The USD Export plug-in system is implemented with its own dedicated plug-in registry, whose API is accessible via the new UsdExport.pluginAPI and UsdExport.pluginRegistry Python modules.

USD Export plug-ins are registered during application startup using the standard Katana plug-in registry mechanism, by adding a UsdExportPlugins folder to a directory whose file system location path is referenced in the KATANA_RESOURCES environment variable, and defining a PluginRegistry module variable in a Python module in that folder.

Here’s a simple example of defining and registering an export plug-in using such

a plug-in Python module:

from UsdExport.pluginAPI import BaseUsdExportPlugin

class MyUsdExportPlugin(BaseUsdExportPlugin):

    priority = 1000

    def WritePrim(stage, sdfLocationPath, attrDict):
        print('MyUsdExportPlugin.WritePrim(): Exporting "{}"...'.format(sdfLocationPath))

PluginRegistry = [
    ('UsdExport', 1, 'MyUsdExportPlugin', (['light'], MyUsdExportPlugin)),

The plug-in’s WritePrim() function will be called as part of exporting USD on each location which matches the location types for which the plug-in is registered. In the example above, the WritePrim() function will be called for light locations.

Using the new UsdExport.pluginRegistry APIs, it is also possible to register and deregister an export plug-in interactively at runtime, for example in a Python tab. This can be used for quickly iterating over a new plug-in that in in development. Here’s an example:

from UsdExport.pluginAPI import BaseUsdExportPlugin
import UsdExport.pluginRegistry

class MyUsdExportPlugin(BaseUsdExportPlugin):

    priority = 1000

    def WritePrim(stage, sdfLocationPath, attrDict):
        print('MyUsdExportPlugin.WritePrim(): Exporting "{}"...'.format(sdfLocationPath))

UsdExport.pluginRegistry.RegisterUsdExportPlugin('MyUsdExportPlugin', ['light'], MyUsdExportPlugin)
UsdExport.pluginRegistry.RegisterUsdExportPlugin(pluginName, locationTypes, pluginClass)

Registers the plugin with the provided unique pluginName, locationType combination into the global UsdExport plugin registry. If a plugin was already found with the same pluginName and locationType, this plugin will not be registered.

Return type:


  • pluginName (str) – The name of the plug-in to register

  • locationTypes (list of str) – The types of katana location, matching the katana type attribute on the location to run this plug-in during a UsdMaterialBake. Providing an empty string as this argument will allow writing to locations which do not have a type attribute on the location, to which we will write an OverridePrim.

  • pluginClass (BaseUsdExportPlugin) – The pluginClass deriving from BaseUsdExportPlugin and implementing WritePrim, and optionally overriding the priority class variable to run at the given locationType.


Returns True if registering the plug-in was a success, otherwise False.

UsdExport.pluginRegistry.UnregisterUsdExportPlugin(pluginName, locationType)

Removes a plug-in from the UsdExport plug-ins, preventing it from running whilst performing a UsdExport.

  • pluginName (str) – The name of the plug-in to find.

  • locationType (str) – The location type of the registered plug-in.


Function to retrieve the BaseUsdExportPlugin’s by type. It will return the list sorted by the priority value on the plug-in classes.

Return type:

list of UsdExport.pluginAPI.BaseUsdExportPlugin


locationType (str) – This method returns all the UsdExport plug-ins we need to run at this provided locationType; matching the katana locations type attribute.


A list of plug-ins which have been registered to that type. Ordered in descending order based on the priority class member of BaseUsdExportPlugin

UsdExport.pluginRegistry.GetUsdExportPluginClass(pluginName, locationType)

Function to return the unique BaseUsdExportPlugin (or derivative) based on the provided arguments.

Return type:

BaseUsdExportPlugin or None

  • pluginName (str) – The name of the plugin to find.

  • locationType (str) – The location type of the registered plugin.


The BaseUsdExportPlugin registered with this unique pluginName and locationType. Returns None if the Plugin with the provided name cannot be found.


Searches the registered plugins to find all the location types which have a plugin matching the name provided by the pluginName argument

Return type:

list of str


pluginName (str) – The name of the plugin to find within multiple locationTypes


A list of all the locationTypes plugins with the name matching the pluginName argument are registered to. Returns an empty list if no plugins are registred with the provided pluginName


Loads the plugins from the UsdExportPlugins subfolder of all folders registered to the KATANA_RESOURCES environment variable.


reloadCached (bool) – Decides whether it should reload modules this plugin system has already searched and added. By default this is set to False.

class UsdExport.pluginAPI.BaseUsdExportPlugin

Bases: object

A plug-in class to assist in setting up your USD Export custom logic. Use this as a base class and ensure that you override WritePrim(). You may register a plug-in to multiple types of locations if it applies to many location types. See the RegisterUsdExportPlugin() function for more details.


priority – An optional value to allow overriding where in the plug-in list your plug-in will be run. Specifically useful if you know there is an order you wish your own subset of plug-ins to run in. Your value must be defined as the default argument to priority. Must be strictly lower than sys.maxint.

priority = 0
static WritePrim(stage, sdfLocationPath, attrDict)

The method which must be overridden in order to write out your own custom Usd.Prim information for any custom UsdExport logic.

  • stage (Usd.Stage) – The stage to which the prim belongs.

  • sdfLocationPath (Sdf.Path) – The SdfPath relating to where this Katana location is to be written in the provided stage. This may already contain a valid Usd.Prim, or Usd.OverridePrim or a derivative of the two. You may override the type and manipulate, the stage and USD file as required.

  • attrDict (dict of str:FnAttribute.Attribute) – A dictionary containing as the keys, the primary attribute name, with the value being an FnAttribute, which may be any of the derived types, GroupAttribute, IntAttribute etc. This attrDict contains the local attributes which differ between the orig input of the UsdMaterialBake node, and the input currently being written.

Optimizations to be Considered

The LookFileBakeAPI provides us a way of de-duplicating data. As presented, UsdExport is not utilizing this in order to keep the initial designs as simple as possible before starting to optimize further. However, this in combination with USD referencing could be used to create singular UsdPrim definitions, which are then referenced multiple times throughout the full location hierarchy. This will become more important once we start writing geometry location types.

Variants are also written with no referencing between each variant. There is often lots of shared information between variants which we could deduce and write out more sparse USD files.