Your Ad Here

File Referencing

File referencing tips

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.

Namespaces

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.

Note Differences between namespaces, prefixes, and sets 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:

• All files are uniquely named: the same file name should not be used more than once in any project. When Maya doesn't find a file that it is looking for, it will look in other places relative to the current project, and as specified by the current environment variables that may have been set. For example, a project could have numerous files called light.ma; a desk light, a streetlight, and a low resolution (light poly count) version of a character. To prevent any file referencing ambiguities, these files should be more explicitly named: deskLight.ma, streetLight.ma, and lightCharRig.ma.
• The Use Namespaces option is turned on when first referencing a file to ensure all nodes within a file are explicitly and uniquely named. For example, an object named tree1 within a file called mapleTree will have a node named mapleTree:tree1 when the file is referenced into the parent scene. The other nodes associated with that object will also be named in a similar manner. For more information, see Namespaces and namespace.

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 (e.g. Channel Box, Outliner, Layer Editor, etc.) 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.

Note If you create a reference with the namespace option, a namespace is created. This is ensures that none of the referenced nodes have name clashes with any existing nodes. Removing that reference should remove the associated namespace. 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.

Note Namespaces are the preferred method for managing naming when working with file references in Maya. It is not recommended that you employ Maya's renaming prefix convention when using file referencing. While the DAG path or long name of a node may make it unique when using renaming prefixes they do not work consistently within file referencing and will complicate the hierarchical DAG changes which causes problems later on.

Editing a namespace

Namespaces can be edited from within the Reference Editor. For more information see Reference Editor overview and Work with file references.

Display of namespaces

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

With the Outliner opened, click Display > Show Namespace.

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

With the Channel Box opened, do one of the following:

• Click Channels > Settings > Show Namespace.
• Right-click in the Channel Box and select Settings > Show Namespace from the pop-up menu that appears.

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

In the Layer Editor, click Options > Show Namespace.

When this menu item is turned on, the display of namespaces is turned on in the Outliner. Turn off this item to turn the display of namespaces off for the Layer Editor.

Removing a namespace

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 imported the reference file directly into your parent scene and will subsequently export selected nodes to a new file or reference.
• You need to clear a namespace currently in use so the file can be referenced by other users without introducing namespace conflicts. This is a good practice if you are exporting a file that may contain unwanted reserved namespaces.

You can do this using the namespace MEL command.

Example:

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

1. Determine the namespace for a node by selecting any object/node that uses the namespace.

The namespace for the object/node will appear in the Channel Box, Outliner etc when its selected. An object’s name with an assigned namespace would appear as follows:

lowRes:pSphere

In this example, the namespace is called lowRes.

2. In the Command Line, type the following text string to move any nodes that reside within the lowRes namespace so they reside in the default namespace.

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 from a file

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.

1. You should know the name of the reserved namespace prior to removing it. For more information on determining the namespaces in the scene, see namespaceInfo in the Maya Help. In this example, the namespace to be removed is called lowRes.
2. In the Command Line, type the following text string to remove the reserved lowRes namespace from the scene.

namespace -rm “lowRes”

Note Namespaces cannot be named so they conflict with any existing namespaces currently in use within the scene.

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.

Note It is not recommended that you reference files in other file formats (for example, dxf, obj, wire, and so on) when using file referencing. When possible convert files to a native Maya format by loading and resaving files in the .ma format.

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):

scenes/street.ma

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

File hierarchy assembly

When planning to use file referencing in your production environment, consider your team’s workflow practices (i.e. modelers, riggers, animators, materials etc.), 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 (i.e. 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.

Data filtering

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.

Exporting file references

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 file references

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.

Note Proxies will only instance the active file reference. If a file reference is instanced and the proxy is switched, the instances will not display.

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:

• The nodes in each proxy file must have identical names (and DAG paths where necessary).
• We suggest that you create a character set in the parent scene. This protects your animation from changes to the underlying reference files.
• The character set contain the attributes to be animated from each node for each proxy. With each proxy active, add its attributes to the character set. See also Character sets below.

Note If you used the group node when creating the reference, any animation on the group node will be shared between proxies.

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.

Example

The following workflow describes one method for switching between proxy references before and after rendering:

• Determine the name of the proxy manager node by viewing the name in the Reference Editor. In this example, the proxy manager is named treePM.
• Select the proxy manager node, so you can determine the individual proxy nodes by viewing the dependency graph for the selected node within the Hypergraph. You can select the proxy manager node by typing select -replace treePM in the command line. In this example, the nodes that appear downstream of treePM are called treeRN and treeloRN (where treeRN is the original high resolution file reference, and treeloRN is the low resolution proxy).
• Create simple pre and post render MEL scripts to switch between the low and high resolution versions as follows:

Pre-render script:

//switch to the high res version

proxySwitch treeRN;

Post-render script:

//switch to the low res version

proxySwitch treeloRN;

Note Multiple proxy references can be switched using the above technique. That is, multiple proxySwitch lines could be added to each script to load or unload several proxies at once.

File reference locator

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

Editing referenced files

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:

DAG hierarchy

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.

Dependency graph connections

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.

Keyframes

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.

Character rigs

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.

Character sets

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.

Polygon history

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 Polygons > Move Component.

Keying attribute values

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.

Grouping

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.

Removing edits from the parent scene

See Removing unwanted reference node edits below.

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:

• Determine the name of the reference node in the currently open parent scene. You can determine this information using the reference and file MEL commands. See Example 1 below.
• Remove the edits. You can selectively remove unwanted edits from a reference node using the file command. See Example 2 below:

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.

1. In the scene view, select an object from the referenced file whose reference node name you want to determine.
2. From the Channel Box, determine the object name for the selected object. In this example, the name of the object is world:planet. Planet is the name of the object, and world is the namespace assigned to it.
3. In the Command Line, type the following string to determine the reference file name associated with that object:

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.

4. Next, type the following string to determine the reference node name for the world reference file within the parent scene:

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.

5. Unload the reference file in the scene, using the reference editor, or by typing the following string:

file -unloadReference worldRN

6. Query all setAttr edits on the reference node so you know what modifications have been made to the reference.

reference -editCommand “setAttr” -rfn worldRN -q

7. Type the following string to remove all setAttr edits from the reference node.

file -cleanReference worldRN -editCommand “setAttr”

The setAttr edits are removed from the reference node worldRN.

8. You can reload the reference file using the reference editor, or by typing the following string:

file -loadReference worldRN

Note Subsequent references of a file that is already referenced in the parent scene get differentiated from the first reference by the addition of a unique copy number on their filename. For example, the file named world.ma would get named world.ma{1}, world.ma{2}, and so on, in the parent scene each time it was subsequently referenced.

Shared shader networks

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:

• networks that include DAG objects (such as those that include the place3dTexture node)
• networks with animation applied to a node
• networks with an expression applied to a node

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.

Note All edits to referenced nodes that are shared are stored on one common shared reference node. Shared references can only be deleted from the Reference Editor using the Remove Reference menu item. The shared reference node remains for any references that were shared and is only removed when the last shared reference is removed.

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.

Related topics

• Work with file references
• Shading networks in the Shading guide

Shared display layers

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.

Note All edits to referenced nodes that are shared are stored on one common shared reference node. Shared references can only be deleted from the Reference Editor using the Remove Reference menu item. The shared reference node remains for any references that were shared and is only removed when the last shared reference is removed.

Related topics

• Work with file references
• Layer Editor in the Basics guide
• Organize objects on display layers in the Basics guide

Unknown reference nodes

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:

delete “_UNKNOWN_REF_NODE_”

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

1. In Maya, select Help > Download Bonus Tools from the Web.

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.

Related topics

	About file referencing
	About proxy references
	About the Reference Editor
	Reference Editor overview
	Work with file references
	Work with proxy references
	Edit reference paths in the Reference Editor
	Locking a file reference