MEL How-To #100

How do I store a value or string such that it is saved and restored with the current scene?

There are myriad ways to store custom data in a scene file. The only specific thing that you need to remember is this:

Over the years there have been several suggestions from Maya users on this topic. Each has its own merits and possible limitations; you'll need to decide which is best for your application.

Custom Attributes

The easiest method is to simply pick a node and create a custom dynamic attribute. This attribute can be of numeric or string form and you can save your data in any form you choose, provided its a valid form for Maya's attribute types.

The key limitation to this method is that it is prone to user deletion. If the node to which you add your data is a DAG node then it will appear in Maya's Outliner, Hypergraph and camera views. If the user can select it, then the user can delete it.

Note: Maya 5.0 introduced functions within the API to lock nodes or attributes so as to make them read-only.

The "Unknown" Node

Another popular method is to use an "unknown" node. (No, I'm not kidding - Maya allows you to create a node of type "unknown".)

This is similar to the "Custom Attributes" method above, except that this node will not appear in Maya's DAG and will be a less obvious target for a tired artist to blow away during crunch time. The flip-side to this is that it requires more effort to find if the data needs to be edited; you'll likely want to offer a custom UI for the user's convenience.

// Create an "unknown" node.
string $unknown = `createNode -name "_sceneNotes" "unknown"`;

// Add two attributes.
addAttr -dt "string" -ln "rigComment" $unknown;
addAttr -at "float" -ln "strideDistance" $unknown;

// Assign values to the attributes.
setAttr -type "string" ( $unknown + ".rigComment" ) "This rig is ready for animating.";
setAttr ( $unknown + ".strideDistance" ) 0.65;

Note: There is no way to distinguish one "unknown" node from another (other than by name). Maya uses this node type to preserve node information when a scene is loaded containing data of an unknown type (from a plug-in, for example). Be sure to identify your own data node using a unique name rather than relying on finding any "unknown" node in the scene.

The Camera Hack

A common hack to prevent user data from being inadvertantly deleted is to use one of Maya's default cameras - persp, top, front or side - and add a custom attribute with which to store your data. This is reasonably safe because the default cameras are read-only and Maya does not allow them to be deleted.

// Find Maya's default camera.
string $camera = findStartUpCamera( "persp" );

// Add two attributes.
addAttr -dt "string" -ln "rigComment" $camera;
addAttr -at "float" -ln "strideDistance" $camera;

// Assign values to the attributes.
setAttr -type "string" ( $camera + ".rigComment" ) "This rig is ready for animating.";
setAttr ( $camera + ".strideDistance" ) 0.65;

Note: The "findStartUpCamera" command returns the name for the camera's transform and not the shape.

The Custom Node

By using the API to create a custom node type you can define the attribute structure which will store your data. These attributes are part of the node's definition and cannot be changed. Nor do they need to be added as dynamic attributes using the "addAttr" MEL command. Simply create your custom node and all of the necessary attributes are immediately available.

This also offers the convenience of identification. There is no ambiguity in the purpose for the node, and you don't need to rely on naming schemes.

string $myCustomNodes[] = `ls -type "myCustomNode"`;

The ".notes" Attribute

Maya 4.5 added the ability to assign notes to each node from the Attribute Editor. These notes are stored on the '.notes' attribute for each node (imagine that!).

Be aware that this attribute is added dynamically, and does not exist until a non-empty note has been assigned to the node. If you are managing this attribute yourself you'll need to determine if the attribute exists, and add it if necessary.

string $targetNode = "someNodeInYourScene";

// Add the ".notes" attribute if it doesn't exist.
if ( !`attributeQuery -node $targetNode -exists "notes"` )
{
  addAttr -sn "nts" -ln "notes" -dt "string" $targetNode;
}

// Assign the note.
setAttr -type "string" ( $targetNode + ".notes" )
  "This rig is ready for animating. The stride distance should be 0.65m";

The "fileInfo" Command

In Maya 5.0 there's a new MEL command which may be used to - ta da! - "provides a mechanism for keeping information related to a Maya scene file." The "fileInfo" command allows you to define keyword/value pairs that will be saved with the scene file.

// Assign two keyword/value pairs for the current scene.
fileInfo "rigComment" "This rig is ready for animating.";
fileInfo "strideDistance" "0.65";

Note that the "value" in this case is always a string, but you can store numerical data in this string as well, if desired.

The "scriptNode"

If you wish to associate an action along with the value you may consider defining a "scriptNode" in the scene. This node allows you to define MEL commands which execute when a scene is loaded. These commands could, for example, assign values to a common UI, or could generate their own UI.

// The command will prompt the user loading the scene...
string $command = "confirmDialog -message \"This rig is ready for animating.\" -button \"OK\";";
// ... and will update a value in an artist's control panel.
$command = $command + "if ( `floatField -q -exists strideDistanceUI` ) " +
                      "floatField -e -value 0.65 strideDistanceUI;";

// Create a scriptNode to execute when this scene is loaded.
scriptNode -scriptType 2 -beforeScript $command -name "_sceneConfig";

Blind Data

You can use blind data to store custom data values directly to individual polygon components, or to any DAG object.

This has the advantage of allowing your geometry to carry your custom data with it when imported or referenced, without interfering with, nor overwriting, any custom data you may have already applied in your working scene.

Using blind data carries more of a burden, however. The commands to apply blind data are more complex than for simple attributes, and you'll need a custom UI for your artists to manage the application of blind data. Also, in contrast to attributes, blind data is applied partly via construction history, which means its use will potentially impact the complexity of the dependency graph for your scene. Finally, blind data queries can be painfully slow (particularly the selection and false colouring mechanism).

Warning! A unfortunate limitation of blind data arises from the fact that it is stored as attributes - either on the geometry itself, or on polyBlindData nodes connected to the object. One of Maya's scene optimizations is to not store attributes whose current value is equal to its default value. Thus, if you apply blind data using its default value, Maya will not save this data. Always define your blind data using default values that are not intended to be applied to your scene.

13 Jul 2004