Maya USD Plugins

Maya USD Plugins

Configure Environment

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

  • Ensure that you built the Maya plugins, this is enabled in the build with -DPXR_BUILD_MAYA_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
MAYA_PLUG_IN_PATH This is a path list which Maya uses to find plugins. $MAYA_PLUGIN_PATH:USD_INSTALL_ROOT/third_party/maya/plugin/
MAYA_SCRIPT_PATH This is a path list which Maya uses to find mel scripts. $MAYA_SCRIPT_PATH:USD_INSTALL_ROOT/third_party/maya/share/usd/plugins/usdMaya/resources/
PYTHONPATH This is a path list which Python uses to find modules. $PYTHONPATH:USD_INSTALL_ROOT/lib/python/
XBMLANGPATH This is a path list which Maya uses to find icon images. $XBMLANGPATH:USD_INSTALL_ROOT/third_party/maya/share/usd/plugins/usdMaya/resources/

For more information see our page on  Advanced Build Configuration .


Loading the Maya USD plugins

To import, export and reference USD files in Maya we provide a plugin called pxrUsd. The plugin can be loaded with the following command: loadPlugin pxrUsd;

The plugin creates two commands: usdImport and usdExport, and will also register USD import and export as MPxFileTranslator's, so that USD will appear as an option in Maya's "File > Export..." and "File > Import..." menu commands.

Some clients have reported errors when loading the USD plugins that result in the plugin failing to load. The errors look like:

dlopen: cannot load any more object with static TLS (pxrUsd)

The workaround, for now, is to disable auto-loading of the bifrost plugin. More details available in the usd-interest forum.

The Maya Viewport and OpenGL

Beginning with Maya versions 2016 extension 2 and 2017, the default rendering engine (at least on Linux) was changed from Legacy OpenGL to OpenGL Core Profile. However, currently parts of the implementations of both Hydra and the Maya USD plugin still depend on legacy OpenGL. We are working to remove this dependency, but for now if you encounter issues viewing USD in the Maya viewport with these or later versions of Maya, we suggest setting your rendering engine preference to "OpenGL - Legacy". This preference is available in the "Display" section of the Preferences editor, or alternatively it can be overridden when Maya launches by setting the environment variable MAYA_VP2_DEVICE_OVERRIDE=VirtualDeviceGL. More information about the environment variable is available from Autodesk here.


usdImport command flags

ShortFlag LongFlag Type Default Description
-ar -assemblyRep string Collapsed

If the import results in the creation of assembly nodes, this value specifies the assembly representation that will be activated after creation. If empty, no representation will be activated. Valid values are:

  • Collapsed
  • Expanded
  • Full

See "Importing as Assemblies" below for more detail on assembly node creation.

-f -file string   Name of the USD being loaded
-p -parent string   Name of the Maya scope that will be the parent of the imported data
-pp -primPath string  

Name of the USD scope where traversing will being. The prim at the specified primPath (including the prim) will be imported.

"/" means you want to import everything in the file.

If it is empty, it will first try to import the defaultPrim for the rootLayer if it exists.  Otherwise, it will behave as if "/" were passed in.

-ani -readAnimData bool 0

Read animation data from prims while importing the specified USD file. If the USD file being imported specifies startTimeCode and/or endTimeCode, Maya's MinTime and/or MaxTime will be expanded if necessary to include that frame range.

Note that while some types of animation are currently supported, for example:

  • animated visibility
  • animated transforms
  • animated cameras
  • mesh and NURBS surface animation via blend shape deformers

Others are not yet supported, for example:

  • time-varying curve points
  • time-varying mesh points/normals
  • time-varying NURBS surface points
-shd -shadingMode string displayColor

Enable importing of Looks according to a defined shading mode. Allowed values are:

    • none - extract no shading data from the USD
    • displayColor - if there are bound Looks in the USD, create corresponding Lambertian shaders and bind them to the appropriate Maya geometry nodes
    • pxrRis - attempt to reconstruct a Maya shading network from (presumed) Renderman RIS shading networks in the USD
-var -variant string[2]   Set variant key value pairs

usdImport return value

This command will return an array containing the fullDagPath of the highest prim imported.  This is generally the fullDagPath that corresponds to the imported primPath but could be multiple if primPath="/".

usdImport behavior

Importing as Assemblies

If you use USD to construct aggregates of other models, then usdImport can preserve your referencing structure as assemblies.  Typically, we want to avoid reasoning about the precise referencing structure of a scene.  Instead, we use kind (whether or not  the kind IsA model - i.e. kind is "group", "assembly", "component" or a site-customized specialization of one of those types) and assetInfo to guide the import.  We plan to make the import behavior customizable via plugin, but for now, it behaves as follows:

    • All USD assembly nodes created by an import will have their file path set to the file being imported. Their prim paths will be set accordingly based on their path in that file. This ensures that opinions in stronger layers doing the referencing will retain their effect on prims in weaker layers being referenced.
    • If kind IsA model and we have assetInfo['identifier'], we generate a new USD assembly node.
    • if kind IsA model and we do not have assetInfo['identifier'], we fall back to checking for any references on the prim. If a reference is found, we generate a new USD assembly node.
    • In all other cases, we continue to import the scene description as if there was no kind specified.

Import and Playback of Animation with USD Assemblies

USD assembly and proxy nodes have a "time" attribute to support referencing USD that contains animation. When a representation of an assembly is activated, we create a connection from the assembly node's time attribute to the time attribute(s) on any/all of its immediate proxies. We do NOT, however, create a connection between Maya's global time and the assembly's time. While doing so is necessary for animation to be displayed with assemblies in Collapsed and Expanded representations, having large numbers of assembly nodes with connections to Maya's global time incurs significant overhead within Maya. As a result, these connections should be created manually if animation is desired for Collapsed or Expanded representations. The following bit of Python code provides an example of how these connections can be made:

Connecting Maya's global time to all assembly nodes in a scene
assemblyNodes ='pxrUsdReferenceAssembly')
for assemblyNode in assemblyNodes:
    cmds.connectAttr('time1.outTime', '%s.time' % assemblyNode)

Currently, edits on reference models do not get imported into maya.  We are working with Autodesk to get a better handle on this.


usdExport command flags

ShortFlag LongFlag Type Default Description
-a -append bool   Appends into an existing USD file
-chr -chaser string(multi)   Specify the export chasers to execute as part of the export. See "Export Chasers" below.
-cha -chaserArgs  string[3](multi)   Pass argument names and values to export chasers. Each argument to -chaserArgs should be a triple of the form: (<chaser name>, <argument name>, <argument value>). See "Export Chasers" below.
-dc -defaultCameras noarg   Export the 4 Maya default cameras
-dms -defaultMeshScheme string catmullClark

Sets the default subdivision scheme for exported Maya meshes, if the usdSdScheme attribute is not present on the Mesh. Valid values are:

    • none 
    • catmullClark 
    • loop 
    • bilinear
-cls -exportColorSets bool 1 Enable or disable the export of color sets
-eri -exportRefsAsInstanceable bool 0 Will cause all references created by UsdAssembly nodes or explicitly tagged reference nodes to be set to be instanceable (UsdPrim::SetInstanceable(true))
-uvs -exportUVs bool 1 Enable or disable the export of UV sets
-vis -exportVisibility bool 1 Export any state and animation on Maya 'visibility' attributes
-f -file string   The name of the file being exported
-fr -frameRange double[2] [1, 1] Sets the Min and Max frame for an anim export
-fs -frameSample

double (multi)

0.0 Specifies sample times used to multi-sample frames during animation export, where 0.0 refers to the integer frame time. For example, specifying frameSamples of -0.1 and 0.2 and a frameRange of [1, 3] will export animation at times 0.9, 1.2; 1.9, 2.2; 2.9, 3.2. Note that the integer frame is not itself included; if you specify frameSamples of -0.1, 0.0, and 0.2, and a frameRange of [1, 3], then you would get animation samples at times 0.9, 1.0, 1.2; 1.9, 2.0, 2.2; 2.9, 3.0, 3.2. Specifying only a frameSample of 0.0 is equivalent to not specifying any frameSamples, in which case you would only get integer frames in the frameRange, e.g. for a frameRange of [1, 3], you would just get 1.0; 2.0; 3.0.
-k -kind string none

Specifies the required USD kind for root prims in the scene. (Does not affect kind for non-root prims.) If this flag is non-empty, then the specified kind will be set on any root prims in the scene without a USD_kind attribute (see the "Maya Attributes" table below). Furthermore, if there are any root prims in the scene that do have a USD_kind attribute, then their USD_kind values will be validated to ensure they are derived from the kind specified by the -kind flag. For example, if the -kind flag is set to "group" and a root prim has USD_kind="assembly", then this is allowed because assembly derives from group. However, if the root prim has USD_kind="subcomponent" instead, then usdExport would stop with an error, since "subcomponent" does not derive from "group".

The validation behavior understands custom kinds that are registered using the USD KindRegistry, in addition to the built-in kinds.

-mt -mergeTransformAndShape bool 1 Combine Maya transform and shape into a single USD prim that has transform and geometry, for all "geometric primitives" (gprims). This results in smaller and faster scenes. Gprims will be "unpacked" back into xform and shape nodes when imported into Maya from USD.
-nuv -normalizeUVs string none

Normalize UV values to the range [0, 1]. Valid values are:

    • none
    • all
    • nurbs
    • mesh
-pr -preRollRange double[2](multi)   Sample USD at given time intervals
-ro -renderableOnly noarg   When set, only renderable prims are exported to USD
-rlm -renderLayerMode string defaultLayer

Specify which render layer(s) to use during export. Valid values are:

    • defaultLayer - Makes the default render layer the current render layer before exporting, then switches back after. No layer switching is done if the default render layer is already the current render layer.
    • currentLayer - The current render layer is used for export and no layer switching is done.
    • modelingVariant - Generates a variant in the 'modelingVariant' variantSet for each render layer in the scene. The default render layer is made the default variant selection.
-shd -shadingMode string  

Set the shading schema to use. Valid values are:

    • none - export no shading data to the USD
    • displayColor - unless there is a colorset named "displayColor" on a Mesh, export the diffuse color of its bound shader as displayColor primvar on the USD Mesh
    • pxrRis - export the authored Maya shading networks, applying the same translations applied by RenderMan for Maya to the the shader types.
-sl -selection noarg   When set, only selected trees will be exported
-suf -skipUnwrittenFrames bool   Produces a continuous list of frames

usdExport Behavior

Model Hierarchy and kind

usdExport currently attempts to make each root prim in the exported USD file a valid model, and may author a computed kind on one or more prims to do so.  In the future, we plan to support annotating desired kind in the Maya scenegraph, and possibly make further kind/model inference optional.  The current behavior is:

    • We initially author the kinds on prims based on the -kind flag in usdExport (see the USD export flags above) or the USD_kind attribute on individual Maya nodes (see the "Maya Attributes" table below).
    • For each root prim in the scene, we validate the kind if it has been specified.  Otherwise, we compute a kind for the root prim:
      • If the root prim is specified to be an assembly (or type derived from assembly), then we check to make sure that Maya has not created any gprims (UsdGeomGprim-derived prim-type) below the root prim.  If there are any gprims below the root prim, then usdExport will halt with an error.
      • If the root prim has no kind, then we will compute a value for the kind to ensure that all root prims have a kind. We determine whether a root prim represents a component (i.e. leaf model) or assembly (i.e. aggregate model of other models, by reference) by determining whether Maya directly created any gprims (UsdGeomGprim-derived prim-type).  If Maya has created gprims, model is a component, else it is an assembly.
    • Once we have validated or set the kind on each root prim, we go through each root prim's sub-hierarchy to make sure that it is a valid model:
      • If model is a component, but also has references to other models contained (nested) within it, override the kind of the nested references to subcomponent, since component models cannot contain other models according to USD's model-hierarchy rules.
      • Else, if model is an assembly, insure that all the intermediate prims between the root and the locations at which other assets are referenced in get kind=group so that there is a contiguous hierarchy of models from the root down to the "leaf" model references.

UV Name Translation: map1 becomes st

Currently, for Mesh export (and similarly for NurbsPatch, also), we rename the uvset map1 to st.  "st" is the primary uvset for RenderMan, so this is very convenient for a Renderman-based pipeline.  We understand this behavior is not desirable for all, and do plan to allow this translation (or none) to be specifiable.  The translation is reversed on importing USD into Maya. 


Maya Attributes That Guide Usd Export

We reserve the prefix "USD_" for attributes that will be used by the USD exporter.

Token Type Value Description
All DAG Nodes
USD_hidden bool true/false

Will call UsdPrim::SetHidden(true) for the exported prim corresponding to the node on which the attribute is authored. Note that the USD hidden metadata is only authored if the Maya attribute is set to true. Note: in USD, "hidden" is a GUI property intended to be meaningful only to hierarchy browsers, as a complexity management feature indicating whether prims and properties so-tagged should be displayed, in a similar fashion to how Maya allows you to specify whether to show shape nodes or not.

Maya's "Hide Selection" GUI operation will cause UsdGeomImageable::CreateVisibilityAttr() to be authored to "invisible" on export when the "-exportVisibility" option is specified to usdExport.

USD_instanceable bool true/false Will call UsdPrim::SetInstanceable() with the given value for the exported prim corresponding to the node on which the attribute is authored, overriding the fallback behavior specified via the -exportRefsAsInstanceable export option.
USD_kind string e.g. "component", "assembly", or any other custom kind Will call UsdModelAPI::SetKind() with the given value for the exported prim corresponding to the node on which the attribute is authored. Note that setting the USD kind on root prims may trigger some additional model hierarchy validation. Please see the "Model Hierarchy and kind" section above.
USD_UserExportedAttributesJson string JSON dictionary Specifies additional arbitrary attributes on the Maya DAG node to be exported as USD attributes. See "Specifying arbitrary attributes for export" below.
Mesh (MFn::kMesh) attributes
USD_EmitNormals bool true/false Determines if mesh normals should be emitted. NOTE: Currently Maya reads/writes face varying normals. Only valid when subdivisionScheme = none.
USD_faceVaryingLinearInterpolation string none, cornersOnly, cornersPlus1, cornersPlus2, boundaries, all Determines the FaceVarying Interpolation rule. Used for texture mapping/shading purpose. Defaults to cornersPlus1. See the OpenSubdiv documentation for more detail.
USD_interpolateBoundary string none, edgeAndCorner, edgeOnly Determines the Boundary Interpolation rule. Valid for Catclark and Loop SDs. Default to edgeAndConer
USD_subdivisionScheme string none, bilinear, catmullClark, loop Determines the Mesh subdivision scheme. Default can be configured but we currently default to catmullClark

Specifying arbitrary attributes for export

Attributes on a Maya DAG node that are not part of an existing schema or are otherwise unknown to USD can still be tagged for export using the User Exported Attributes Editor UI. Here is an example of how to bring up the widget in a style that looks like Maya's channel box:

Launching the User Exported Attributes UI
from pxr.UsdMaya import userExportedAttributesUI
userExportedAttributesUI.UserExportedAttributeWidget().show(dockable=True, area='right', floating=False)

Attributes tagged using this UI will be added to the Maya attribute "USD_UserExportedAttributesJson" as a JSON dictionary. During export, this attribute is used to find the names of additional Maya attributes to export as USD attributes, as well as any additional metadata about how the attribute should be exported. Here is example of what the JSON in this attribute might look like after tagging:

Example USD_UserExportedAttributesJson Value
    "myMayaAttributeOne": {
    "myMayaAttributeTwo": {
        "usdAttrName": "my:namespace:attributeTwo"
    "attributeAsPrimvar": {
        "usdAttrType": "primvar"
    "attributeAsVertexInterpPrimvar": {
        "usdAttrType": "primvar",
        "interpolation": "vertex"
    "attributeAsRibAttribute": {
        "usdAttrType": "usdRi"
    "doubleAttributeAsFloatAttribute": {
        "translateMayaDoubleToUsdSinglePrecision": true

If the attribute metadata contains a value for "usdAttrName", the attribute will be given that name in USD. Otherwise, the Maya attribute name will be used, and for regular USD attributes, that name will be prepended with the "userProperties:" namespace. Note that other types of attributes such as primvars and UsdRi attributes have specific namespacing schemes, so attributes of those types will follow those namespacing conventions. Maya attributes in the JSON will be processed in sorted order. Any USD attribute name collisions will be resolved by using the first attribute visited, and a warning will be issued about subsequent attribute tags for the same USD attribute. The attribute metadata can also contain a value for "usdAttrType" which can be set to "primvar" to create the attribute as a UsdGeomPrimvar, or to "usdRi" to create the attribute using UsdRiStatements::CreateRiAttribute(). Any other value for "usdAttrType" will result in a regular USD attribute. Attributes to be exported as primvars can also have their interpolation specified by providing a value for the "interpolation" key in the attribute metadata.

There is not always a direct mapping between Maya-native types and USD/Sdf types, and often it's desirable to intentionally use a single precision type when the extra precision is not needed to reduce size, I/O bandwidth, etc. For example, there is no native Maya attribute type to represent an array of float triples. To get an attribute with a VtVec3fArray type in USD, you can create a "vectorArray" data-typed attribute in Maya (which stores an array of MVectors, which contain doubles) and set the attribute metadata "translateMayaDoubleToUsdSinglePrecision" to true so that the data is cast to single precision on export. It will be up-cast back to double precision on re-import.

Export Chasers

Export chasers are plugins that run as part of the export and can implement prim post-processing that executes immediately after prims are written (and/or after animation is written to a prim in time-based exports). Chasers are registered with a particular name and can be passed argument name/value pairs in an invocation of usdExport.  There is no "plugin discovery" method here – the developer/user is responsible for making sure the chaser is registered.

We provide one such chaser plugin called AlembicChaser to try to make integrating USD into Alembic-heavy pipelines easier. One of its features is that it can export all Maya attributes whose name matches a particular prefix (e.g. "ABC_") as USD attributes by using its "attrprefix" argument. Here is an example of what that call to usdExport might look like:

Invoking usdExport with an Export Chaser
       ('alembic', 'attrprefix', 'ABC_'),

The export chasers to run are passed by name to the -chaser option, and then an argument to a chaser is passed as a string triple to the -chaserArgs option. Each chaser argument triple should be composed of the name of the chaser to receive the argument, the name of the argument, and the argument's value.

Alembic Chaser Arguments
Argument Format Description
attrprefix mayaPrefix1[=usdPrefix1],mayaPrefix2[=usdPrefix2],...

Exports any Maya custom attribute that begins with mayaPrefix1, mayaPrefix2, ... as a USD attribute. usdPrefix# specifies the substitution for mayaPrefix# when exporting the attribute to USD. The usdPrefix can contain namespaces, denoted by colons after the namespace names. If the [=usdPrefix] component isn't specified for any mayaPrefix, the usdPrefix is assumed to be "userProperties:" by default.

For example, if attrprefix = "ABC_,ABC2_=customPrefix_,ABC3_=,ABC4_=customNamespace:", then the following custom attributes will be transformed:

  • ABC_attrName -> userProperties:attrName
  • ABC2_attrName -> customPrefix_attrName
  • ABC3_attrName -> attrName
  • ABC4_attrName -> customNamespace:attrName
primvarprefix mayaPrefix1[=usdPrefix1],mayaPrefix2[=usdPrefix2],...

Exports any Maya custom attribute that begins with mayaPrefix1, mayaPrefix2, ... as a USD primvar. usdPrefix# specifies the substitution for mayaPrefix# when exporting the attribute to USD. The usdPrefix cannot contain namespaces; any term that specifies a namespace in the usdPrefix component will be skipped. If the [=usdPrefix] term isn't specified for any mayaPrefix, the usdPrefix is assumed to be "" (empty) by default.

For example, if attrprefix = "ABC_,ABC2_=customPrefix_,ABC3_=", then the following custom attributes will be transformed:

  • ABC_attrName -> attrName

  • ABC2_attrName -> customPrefix_attrName

  • ABC3_attrName -> attrName

The interpolation of the primvar is based on the _AbcGeomScope attribute corresponding to an attribute (e.g. myCustomAttr_AbcGeomScope for myCustomAttr). Supported interpolations are "fvr" (face-varying), "uni" (uniform), "vtx" (vertex), and "con" (constant).

The type of the primvar is automatically deduced from the type of the Maya attribute. (We currently ignore _AbcType hint attributes.)