You can use the Maya Metadata API to create an arbitrary number of metadata structures that can be attached directly to any Maya node as well as the components (vertices, faces, and edges, and vertex faces) of Maya mesh objects. Metadata can be also added the Maya scene as a whole, meaning it does not need to be attached to any particular node. A small set of MEL commands provide access to the metadata from within Maya.
Using the Metadata classes, you can create data structures for the component-level metadata, and combine it into a single data stream that lets the metadata flow through operations in the Maya DG, while maintaining its attachment to the nodes. This includes adding component-level metadata to mesh node that have construction history. Since metadata can be attached to any node with an arbitrary named association, you can extend the API for uses such as attaching metadata to points in a point cloud, particles in a simulation, or a vertex on a NURBS surface. The metadata can later be examined or modified by MEL commands or through the API, and is preserved in Maya files across sessions. An example in the adsk::Data::Association class reference shows how to store vertex velocity and acceleration data on a simulated mesh. See the Maya Developer Help.
Metadata index values do not change through construction history. If the mesh topology is altered, the mesh component metadata may no longer be associated with its original component. The editMetadata command can help insert tweaks into construction history to fix any problems this might create.
Metadata should not be added to a deformed mesh.
In general, any operation that changes the topology of a polyShape’s inMesh attribute (that is, the input attribute of the polyShape node), for example, hard edge modification, will not modify the incoming metadata in the same way and may lead to unexpected results.
Metadata API classes
The Metadata API includes the following most commonly used classes: adsk::Data::Association, adsk::Data::Channel, adsk::Data::Stream, adsk::Data::Structure, and adsk::Data::Handle.
- The adsk::Data::Association class is used to create the date structures for the per-component data. For example, you define the data to attach to every vertex on a surface of a mesh object.
- The adsk::Data::Channel class is used to amalgamate the data streams to a single data block.
- The adsk::Data::Stream class manages an indexed list of data and is optimized for typical operations, such as deleting from the middle of the list and duplicating entries.
- The adsk::Data::Structure class defines and manages the metadata data structure.
- The adsk::Data::Handle class provides the interface to access the metadata values within the adsk::Data::Stream.
Association, Channel, Stream, and Structure each have equivalent XXIterator classes to facilitate walking through all members of the class.
Metadata MEL commands
From Maya, you can use the following MEL commands to access and manipulate data structures created from Metadata API. For a full command reference, see the "MEL Commands" section in Technical Documentation.
- Use dataStructure to create an unattached metadata structure.
- Use addMetadata to apply members of the structure to components in Maya.
- Use
editMetadata to assign values to the members of the metadata stream to selected components.
This command can be used on nodes with construction history. For mesh nodes with construction history, editMetadata nodes are created to contain the modifications to existing metadata rather than applying them directly to the mesh node.
You still have the option of editing the metadata on the history node. When you do this, the edits are directly applied to the mesh node and an editMetadatanode is not created.
- Use hasMetadata to query for the existence of metadata on a node.
- Use getMetadata to query metadata values.
If you want to use other index types, they can be implemented via plug-in through the Maya API. The metadata commands can use those types everywhere the native index types appear.