Writing Custom Attributes to USD

With Multiverse you can easily write USD files which contain your own custom attributes on shape nodes such as mesh, curves like pfxHair, stroke and nParticle nodes (while custom attributes on transform nodes are not written). Writing can be performed both from the UI and from Python API. Once read back into Maya as Multiverse Compounds, you can easily query such attributes and use them for many purposes in your pipeline such as identification, tagging, shading etc.

There are two categories of attributes that you can write to USD:

1. Maya-typed attributes
2. USD-typed attributes

One particular use for USD-typed attributes, as you will see below, is to use them to recover primitive variables ("primvars") for look-dev and rendering, note that this is valid exclusively for USD-typed Attributes.

TIP

Attributes are visible in the MEOW via MMB over a selected item, this will pop the "item info" inspection UI listing attribute names, types and values.

Maya-typed Attributes

These are the "classic" Maya attributes types that can be added e.g. via "AE> Attributes> Add Attributes" (and in many other ways such as Python) on Maya shape nodes.

Maya types maps to USD types according to the following table:

Maya Type	USD Type
Vector	Float3
Float	Double
Integer	Integer
Boolean	Integer
String	String
Enum	Integer

Because there can be many Maya custom attributes on your assets, including attributes that you do not need/want in USD, we let the user specify which attributes to write as a comma-separated value list when writing.

USD-typed Attributes

These are the USD attributes types that you can add via the Multiverse section of Maya shape nodes. You can also add USD attributes on Multiverse USD Compounds (being shape nodes), and write them as overrides, see the section further below to achieve this. Writing can be performed both from the UI and from the Multiverse Python API.

The USD types you can add are:

• Int
• Float
• String
• Token
• Color

There are two peculiarities about USD attributes:

• There is a USD type called "token": you can consider it at all effects a "string".
• Attributes can be also named as "primitive variables" by using the primvars: prefix in the attribute name (note that this is not possible for Maya-typed attributes since the : character is considered illegal for Maya attributes). Primvars are very useful for lookdev and rendering purposes as they can be recovered in shading networks and be leveraged for conditional variations.

Note

All custom attributes, whether Maya ones or USD ones, can be animated.

Writing Assets with Custom Attributes

• Maya-typed custom attributes added on Maya geometry:

  1. For the supported Maya shape node go to "AE: Attributes> Add Attribute" and add your attributes type name, and values.
  2. Select a node and perform a Multiverse Write Asset operation.
  3. Turn on "Write Custom Attributes".
  4. Specify a comma-separated list of attribute names.

• USD-typed custom attributes added on Maya geometry

  1. For the supported Maya shape nodes go to their Multiverse section and click on "Add USD Attribute" button, then add your attributes type name, and values.

     TIP

     Make sure to use the primvars: prefix if you want to recover that attribute at shading.

  2. Select a node and perform a Multiverse Write Asset operation.
  3. Turn on "Custom USD Attributes": all custom USD attributes found will be written.

Note

You can write attributes in assets and also you can write attributes as sparse data, both via the Multiverse Write USD Asset UI and Python API.

Note

You can add USD attributes via the Multiverse Python API, see the AddUsdAttributeToNode function. Attributes added on Maya geometry and transform nodes are then written as Assets.

Writing Overrides with Custom Attributes

It is also possible to add USD attributes to existing USD files that are read in Maya as Multiverse Compounds: they are added as MEOW overrides via the mvSet node and they can be written with a Multiverse Write USD Override action:

1. Select a Multiverse Compound, and in MEOW add a Attribute Set on the desired item(s): an mvSet node will be created and assigned to that location.
2. In the relative mvSet node, open the Attribute Editor and click on the "Add USD Attributes" button.
3. Start adding your USD attributes with the "Add New Item" button.
4. Select the Compound and perform a Multiverse Write Override:
   • Make sure the "Attribute Set" option is active.
   • Optionally use the "Sync" option to automatically reload the override as a layer in your Multiverse Compound.

Note

You can add USD attributes via the Multiverse Python API, see the AddUsdAttributeToNode function. Attributes added on mvSet nodes assigned to items in MEOW are then written as Overrides.

Recover Primvars for Lookdev and Rendering

As mentioned earlier, it is possible to write USD-typed attributes with the primvars: prefix on the attribute name. In USD this becomes a primitive variable.

A primitive variable can be queried and used into a shading network via each supported renderer's dedicated "attribute reading" node, as per the table below:

Renderer	Node	Types
3Delight	dlPrimitiveAttribute	Float, Color, Point, UV, Integer
Arnold	aiUserData*	Color, Float Int, String
Redshift	rsUserData*	Color, Integer, Scalar, Vector
Renderman	pxrPrimVar	Normal, Vector, Color, Point, Float, Float2
VRay	vrayUser*	Color, Integer, Scalar

TIP

When recovering the attribute you must not type the primvars: prefix of your attribute as the prefix is only needed in the USD data. So, for example, if in USD you have an attribute called primvars:mycolor you just need to type mycolor in 3Delight's dlPrimitiveAttribute.

This means you can do things like:

• Feed a shader with a value stored in a primvar.
• Create variations using logic and math nodes based on the values of a primvar.
• etc.

For mote information have a look also at the Querying Attribute Variants in Shading Networks documentation.