File referencing allows you to manage complex scene hierarchies. To gain the most benefit from file referencing, use the following tips to ensure a more efficient workflow. As well, a basic understanding of namespaces will help your workflow.
A namespace is a scoping mechanism for naming objects. You create a namespace, and within that namespace, all object names must be unique.
This gives you a way of handling multiple objects with the same name, by putting each in a distinct namespace.
The full, most complete name for any object begins with its namespace (possibly nested), followed by its name, or full DAG path (if the object is a DAG object).
Every object is in some namespace (usually the default one, named ":")
The namespace nesting hierarchy and the DAG parenting hierarchy are independent.
You can use a namespace in another namespace; that is, have a hierarchy of namespaces.
A prefix is a string applied when generating a name. Prefixes are mainly used as an option for renaming objects coming from a referenced file, and for the past few releases we have been strongly encouraging users to avoid the use of renaming prefixes in favor of namespaces.
A set is a Maya object that collects other objects. You can perform a variety of operations using sets to manipulate all the objects in a set. For example, Some Maya editors let you keep a bookmark that is really just a set listing the objects to display in that editor.
File and node naming for file referencing
Pre-planning the file and node naming conventions for the parent scenes and referenced files is important and will greatly add to the success of the implementation of file referencing in your production environment. In particular plan to ensure that:
Alternatively, you can specify namespaces of shorter length than the default file name when it makes sense. A shorter node name streamlines your workflow when working with Maya's editors (Channel Box, Outliner, Layer Editor, and so on). You create a custom namespace by typing the desired text string in the Create Reference option window. For example, you could select to use a custom namespace called mt instead of the word mapleTree. The tree1 node name in the above example would be called mt:tree1. This reduces the length of the name (and any typing) that may be required when working in Maya.
If you add non-referenced nodes to the reference namespace, this can cause name clashes with referenced nodes (for example, if the reference is unloaded when a node is added to the namespace), and prevents the namespace from being deleted when the reference is removed.
Namespaces can be edited from within the Reference Editor. For more information see Reference Editor overview and Work with file references.
You can turn the display of namespaces on or off in the Outliner, Channel Box, and Layer Editor.
When using namespaces, object names can sometimes get very long. This can make it difficult to differentiate objects by name. Turning off the display of namespaces replaces the namespace portion of a node’s name (if any) with “...:”. The shortened name makes it easier to distinguish between different objects in your scene.
To turn on/off the display of namespaces in the Outliner
When this menu item is turned on, the display of namespaces is turned on for the Outliner. Turn this item off to turn the display of namespaces off for the Outliner.
To turn on/off the display of namespaces in the Channel Box
When this menu item is turned on, the display of namespaces is turned on in the Channel Box. Turn off this item to turn the display of namespaces off for the Channel Box.
To turn on/off the display of namespaces in the Layer Editor
There may be situations where you need to remove nodes from a particular namespace and subsequently remove the reserved namespace altogether from the scene. These situations might be as follows:
You can do this using the namespace MEL command.
The next two procedures show you how to remove nodes from an existing namespace in a scene, and then remove the reserved namespace from the scene using the namespace MEL command.
To remove a specified namespace for all nodes in a scene
The namespace for the object/node appears in the Channel Box, Outliner, or other editor when it is selected. An object’s name with an assigned namespace would appear as follows:
lowRes:pSphere
namespace -mv “lowRes” “:” -f
Any nodes that had the lowRes namespace now have no namespace specified. That is, the : specifies the default namespace and the -f flag forces the command even if it produces naming conflicts. As a result, nodes with identical names will be assigned an incremental number.
To remove a reserved namespace, you must first ensure that no nodes in the scene currently reside within that namespace. For more information, see the above procedure.
To remove a reserved namespace from a file
namespace -rm “lowRes”
File formats for file referencing
Saving files in the Maya ascii file format (.ma) is preferred when using file referencing. Maya ascii files can be opened and edited in your favorite text editor, and are easier to troubleshoot if the file or some components of the file do not load as expected.
File paths for file referencing
File referencing only supports absolute paths and paths with environment variables. Relative path names are not supported when using file referencing. An environment variable can be used as a superior alternative to a relative path as it is explicit and customizable to each user's file structure.
Relative path (not supported):
Absolute path (supported): C:/projects/cityscene/scenes/street.ma
Environment variable path (supported): $myProject/scenes/street.ma
For more information on environment variables see Setting environment variables using Maya.env
For more information, see Edit reference paths in the Reference Editor
When planning to use file referencing in your production environment, consider your team’s workflow practices (modelers, riggers, animators, materials and so on), as well as the overall requirements for the project before you determine your scene’s hierarchy.
In general, you should reference files in a bottom up manner (that is, reference small items into bigger items). This bottom up structure allows you to easily load or unload any segments of the scene that are not required by the user. For example, when creating a city parent scene, a door and other related components should first be referenced into a building file. Then reference the building into the street file, and then reference the street file into the city parent scene.
When building a character, reference the model into the rigged file. Then reference the rigged file into the environment where the character will be animated. This ensures that a change to the rig is correctly propagated to all environment files that may use the character.
When referencing many files into a scene, the amount of data can rapidly become complex to manage. The Outliner and Hypergraph overview editors have filtering options that allow you to limit the amount of data that gets displayed.
The Display Layer editor allows for sorting of layers alphabetically which will help with organization.
You can extract segments of a normal scene as a referenced file if it becomes more complex than originally anticipated. Specific components of the scene can be selected and then exported as a separate referenced child scene file using the Export Selection as a Reference command. Exported referenced child scene files are automatically referenced and loaded into the currently open scene. It is not possible to use the Export Selection as a Reference command using a file reference.
A nice benefit of creating file references in this manner is that each region of the scene is in the correct worldspace position and does not need to be repositioned when referenced into the parent scene.
Instancing of objects can be used to aid scene management by further reducing the amount of data in a scene. For example, if a street scene is to be filled with streetlights, the streetlight file can be referenced in once and then the remaining streetlights instanced. If the streetlight file is unloaded, all the streetlights in the scene will disappear because of their instancing relationship to the original streetlight file.
If you have a reference file and instance an object within it and then later remove the reference file, both versions of the objects will be removed in the parent scene. A transform node will be left behind in the parent scene for the instance. This node remains in case other changes have been applied to the instance by the user in the parent scene.
Do not rename a node or change a hierarchy in a referenced file if the parent scene contains objects that are instanced. Such a change will make the instance disappear; Maya will be looking for an object that no longer exists. Maya’s instancing is name-based. By renaming the object in the reference file, you make the original go away such that the parent scene can no longer find it.
Replace reference vs. proxy references
The Reference Editor provides two methods for substituting file references within the parent scene. Each method has its advantages and limitations.
The Replace Reference command opens a file browser to replace the current reference with another you select. The group node and/or locator remains the same. Any edits that exist for the file reference at the parent scene level will be applied to the substituted file reference because the reference node is not modified. While this works well in situations where the file reference being substituted has exactly the same node names and DAG hierarchy as the original file reference, it has limited applications. If the node names and DAG hierarchy are not identical, you may encounter errors when Maya tries to apply the reference edits to the substituted reference and data loss could result. Maya doesn’t track the substitutions that occur when using the Replace Reference command and is not recommended when nested file references exist in the referencing hierarchy.
Proxy References allow you to substitute one or more file references by creating a set of possible substitute references (proxies) for a given file reference. A new node is created to keep track of the multiple proxies. Proxy references let you globally substitute many proxy references at a time by selecting the proxy references and reloading them based on their proxy tag. This is advantageous when you quickly need to substitute from a low resolution version of the scene to a high resolution version, and vice versa.
Sharing animation between proxy references
If you want to share animation between proxy references for a particular file reference you must ensure that a state of equivalency exists between the various proxy files for a particular file reference and their parent scene. That is, when you keyframe within the parent scene, you want to ensure that the animation can be applied to the correct nodes regardless of which proxy file is loaded. To achieve this equivalency, the proxy files must be set up as follows:
Rendering with proxy references
When rendering a scene that contains file and proxy references, only the currently loaded file and proxy references will render in the image unless you specify otherwise. You must ensure you load any references you want to appear in the rendering prior to rendering. You can switch proxies for the purposes of rendering using Pre Render MEL and Post Render MEL scripts.
For example, a low resolution proxy is currently displayed in the scene and needs to be switched to the high resolution version prior to rendering and then back to the low resolution version after the rendering is complete. By determining the name of the proxy manager in the Reference Editor, you can then determine the names of the related proxy set nodes for each proxy, and then create a simple script for switching between the low and high resolution versions of the proxies before and after rendering.
The following workflow describes one method for switching between proxy references before and after rendering:
//switch to the high res version
proxySwitch treeRN;
//switch to the low res version
proxySwitch treeloRN;
The file reference locator option is useful when you need to move a file reference in the scene view via its group node. The locator also acts as a visual cue for the reference whenever the reference is unloaded. The locator option is only available in the Reference Options window when the Group option is selected. The locator option groups the contents of the referenced file under a locator, annotated with the reference node name. You can load or unload a reference within the scene by right-clicking on the locator and selecting from the context sensitive menu.
For more information, see File > Create Reference
A parent scene file can be adversely affected by edits that are made at the referenced child scene file level of the hierarchy. That is, an edit made at the parent scene level could become unresolvable if node names and connections are changed at the child scene file level. The following are examples of edits that can affect the parent scene’s ability to resolve previously made edits:
It is possible that a DAG node can be non-uniquely named within its particular namespace. This means that two objects in a scene can be named the same provided they exist in separate DAG hierarchies whose path name is unique. If modifications are made to a DAG hierarchy in a referenced child scene file after it has been referenced into a parent scene, such that the DAG paths change from what the parent scene’s edits specify, the edits may no longer be possible, or may be applied in a fashion that was unexpected.
If you rename a node in a referenced child file after it has been referenced into a parent scene, any edits that were made to that node in the parent scene will no longer be possible. For example, two nodes exist separately in a referenced child file, and have an edit that connects them in the parent scene. If either of the nodes are subsequently renamed at the child file level, the parent scene will be unable to apply its edits, because of the name change, and display an error message.
A keyframe on an attribute connects the attribute being keyframed to a new node. If the parent scene file cannot find the node (because its name has been changed), the animation may break.
It is common practice to add, delete, and rename attributes in a character rig. Creating a specific character node can work as a safeguard for any successive changes. The character node should be created in the rig file that will be referenced - not in the parent scene file that references the rig.
When referencing character sets, renaming a member of that set or renaming the character itself is not permitted if the referenced file modifies or connects to the renamed object. This could result in the animation not affecting the character set or affecting the wrong member of the character set.
In situations where the surface geometry in a referenced file must be edited, the user can add history to the referenced model. One example of this is pre-lighting, an effect used to store the shading and lighting information from the rendered look of a mesh in its vertex colors. As long as the poly geometry in the referenced file has history, new history can be added in the parent scene. A simple way to add history in the reference child scene file is to select the mesh and then select Edit Mesh > Transform Component.
If you change the value of an attribute in a referenced child scene file, there is no way, other than an immediate Undo, to set the attribute back. If it is important to return to that value, consider storing that value by setting a keyframe, Trax pose, or Trax clip. Another option is to store the value as a node preset in the Attribute Editor.
When you create file references with the group option, some objects in the hierarchy may receive a double transformation when the new group node is translated, rotated, or scaled when working in the parent scene. That is, when you translate an object, the object receives two commands to transform based on its location in the hierarchy. This can readily occur with rigged characters where a relationship already exists between the skeleton and the skinned character. In these situations you must either turn off the Inherit Transforms attribute for the item in the referenced file, or determine an alternate approach to grouping the hierarchy.
Updating a reference in the parent scene
When multiple users are working on a project, and one user is editing a referenced file that is also referenced by other users, the other users will not see the modifications made by the first user in their own parent scene until they reload the file reference. See Reference Editor overview.
Saving edits from the parent scene to a file reference
If you require nodes to be written out as part of the save reference edits operation, you can import the referenced file so all of the items reside in the scene, and then select only those imported items, and export the selection as a reference again. In this way, all of the edits to the nodes and attributes will get written to the exported file reference.
Removing unwanted reference node edits
There may be situations where you want to remove unwanted edits from the reference node. For example, you have been applying and removing animation from a file reference while working within the parent scene. You’ve finalized the animation, but now want to ensure there are no unwanted setAttr edits on attributes that should not animated in the final version.
In order to remove unwanted edits you must:
Example: Removing all edits of a particular type
This example shows you how to determine the name of the reference node associated with a file referenced into your currently open scene.
reference -q -f world:planet
Maya displays the directory path and name of the reference file. In this example, the reference file name is world.
file -q -rfn world.ma
Maya displays the name of the reference node as follows:
worldRN
Once you have determined the name of the reference node, you must unload the reference file in order to remove the reference edits.
file -unloadReference worldRN
reference -editCommand “setAttr” -rfn worldRN -q
file -cleanReference worldRN -editCommand “setAttr”
The setAttr edits are removed from the reference node worldRN.
file -loadReference worldRN
If you reference a file into your current scene with shared shading networks enabled, the shading networks from the referenced scene are combined with those in the current scene (including those of any references). This avoids creating duplicate shading networks when you want the same ones used throughout your scene, including the reference.
Shading networks can only be shared if the shading networks are identical. Maya considers two shading networks to be identical only if all the nodes included in it have both the same name and type while traveling upstream from the shading group.
While the name and type of each node in the shading network must be identical in order for the shading network to be shared, the actual values in each node are not considered. So, a node in a child scene with one value (for example, blue) is considered identical to a node in the parent scene with a different value (for example, red) as long as its name and type match.
However, certain shading networks cannot be shared. They are:
If any of these items appear in the shading network, the network is not shared when the file is referenced with shared shading networks enabled.
Any items that exist downstream of the shading network are also not shared. The only items shared are those items upstream of the shading network.
Dynamic attributes that are added to a shading network that is subsequently shared may be lost unless the same attributes are created on each of the shading networks to be shared prior to sharing.
If you reference a file into your current scene with shared display layers enabled, the display layers from the referenced scene are combined with those in the current scene (including those of any references). This avoids creating duplicate display layers when you want the same ones used throughout your scene, including the reference.
Maya uses the display layer name to determine how the referenced display layer is added to the current scene. If a display layer name already exists in the parent scene, any objects assigned to an identically-named display layer in a child scene are added to the original parent display layer when they are referenced.
If a child scene contains a display layer that does not exist in the parent scene, the display layer from the child scene appears in the Display Layer editor of the parent scene when the child scene is referenced. If these child scenes are later removed from the parent scene, their associated display layers are removed from the Display Layer editor as well.
Shared display layers are automatically placed in the default namespace.
When a pre-Maya 6.5 file that contains references is converted to a later version Maya file, a reference node named "_UNKNOWN_REF_NODE_" may be created and/or a special "_UNKNOWN_REF_NODE_" entry may be added to existing reference nodes.
This node type was used to store any edits that were made prior to 6.5 until those edits could be applied.
Once all references in the scene have been loaded, all edits should be applied and the _UNKNOWN_REF_NODE_ areas and nodes should disappear. If there are any edits which can not be applied (for example, nodes in the original reference file that were renamed or deleted), the _UNKNOWN_REF_NODE_ will remain in the file.
If you need to remove these reference nodes, you can do so by querying for the _UNKNOWN_REF_NODE_ and deleting it. That is, this specific node type cannot be deleted using the Reference Editor. In the Script Editor:
File reference optimization and errors
By default, if you reference the same file twice, on file open Maya copies the existing nodes instead of re-reading them from disk. Occasionally, using this built-in multiple reference optimization feature of file referencing can cause errors. The MAYA_FORCE_REF_READ environment variable turns off the file referencing optimization and forces reference files to be explicitly read in all cases. This fixes Maya's behavior in some situations that would otherwise be evaluated incorrectly.
For more information, see General variables.
File referencing helper scripts
A number of file referencing helper scripts are available as part of the Maya Bonus Tools. Bonus Tools is a free collection of useful Maya scripts and plug-ins that are available from the Autodesk Web site (www.autodesk.com/maya-bonustools).
To download the Bonus Tools from the Autodesk web site
You will need to register in order to obtain access to some areas of the Autodesk Web site. Once installed, the Bonus Tools appear within Maya in their own drop-down menu.
