UsdExport

✨ 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

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
  • 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.

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 plugins 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 envrionment variable.

UsdExport

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
Parameters:
  • 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.
Returns:

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
Parameters:
  • 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.
Returns:

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

Parameters:
  • 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.

Parameters:
  • 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.

Parameters:
  • 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.

Parameters:
  • 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
Parameters:
  • 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 (SdfTypeIndicator) – 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.
Returns:

The shader input created by this method or None if no shader input was created.
UsdExport.material.ConvertParameterValueToGfType(value, sdfType)

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

Return type:

Gf
Parameters:
  • value (PyFnAttribute) – The value to be cast to a Gf equivalent.
  • sdfType (Sdf.ValueTypeNames) – The type to cast to.
Returns:

The Gf type casted value.
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.

Parameters:
  • 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.

Parameters:
  • 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.

Parameters:
  • 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:

Sdf.ValueTypeNames
Parameters:
  • 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.
Returns:

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)

Uses the UsdShade.MaterialBindingAPI to bind the material to the overridePrim.

Parameters:
  • material (UsdShade.Material) – The material to bind.
  • overridePrim (Usd.OverridePrim) – The Prim to bind to.
UsdExport.material.GetShaderNodeFromRegistry(shaderType)

Method required to get the SdrShadingNode from the SdrRegistry in different ways, depending on the usdPlugin.

Return type:Sdr.ShaderNode
Parameters:shaderType (str) – The type of the shader to search for in the shading registry.
Returns:The shader from the shader registry which matches the provided type.

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.