Go to: Synopsis. Return value. Keywords. Related. Flags. Python examples.
referenceQuery([child=boolean], [dagPath=boolean], [editAttrs=boolean], [editCommand=string], [editNodes=boolean], [editStrings=boolean], [failedEdits=boolean], [filename=boolean], [isExportEdits=boolean], [isLoaded=boolean], [isNodeReferenced=boolean], [isPreviewOnly=boolean], [liveEdits=boolean], [namespace=boolean], [nodes=boolean], [onReferenceNode=string], [parent=boolean], [parentNamespace=boolean], [referenceNode=boolean], [shortName=boolean], [showDagPath=boolean], [showNamespace=boolean], [successfulEdits=boolean], [topReference=boolean], [unresolvedName=boolean], [withoutCopyNumber=boolean])
Note: Strings representing object names and arguments must be separated by commas. This is not depicted in the synopsis.
referenceQuery is NOT undoable, NOT queryable, and NOT editable.
Use this command to find out information about references and referenced nodes.
A valid target is either a reference node, a reference file, or a referenced node.
Some flags don't require a target, see flag descriptions for more information
on what effect this has.
When a scene contains multiple levels of file references, those edits which
affect a nested reference may be stored on several different reference nodes.
For example:
A.ma has a reference to B.ma which has a reference to C.ma which contains
a poly sphere (pSphere1).
If you were to open B.ma and translate the sphere, an edit would be stored
on CRN which refers to a node named "C:pSphere1".
If you were then to open A.ma and parent the sphere, an edit would be
stored on BRN which refers to a node named "B:C:pSphere1".
It is important to note that when querying edits which affect a nested
reference, the edits will be returned in the same format that they were
applied. In the above example, opening A.ma and querying all edits which affect
C.ma, would return two edits a parent edit affecting "B:C:pSphere1", and a
setAttr edit affecting "C:pSphere1". Since there is currently no node named
C:pSphere1 (only B:C:pSphere1) care will have to be taken when interpreting the
returned information.
The same care should be taken when referenced DAG nodes have been parented or
instanced. Continuing with the previous example, let's say that you were to
open A.ma and, instead of simply parenting pSphere1, you were to instance it.
While A.ma is open, "B:C:pSphere1" may now be an amibiguous name, replaced by
"|B:C:pSphere1" and "group1|B:C:pSphere1". However querying the edits which
affect C.ma would still return a setAttr edit affecting "C:pSphere1" since it
was applied prior to B:C:pSphere1 being instanced.
Some tips:
1. Use the '-topReference' flag to query only those edits which were applied
from the currently open file.
2. Use the '-onReferenceNode' flag to limit the results to those edits where
are stored on a given reference node. You can then use various string
manipulation techniques to extrapolate the current name of any affected
nodes.
string[] | For query execution. |
reference, attribute, node
file, referenceEdit
child, dagPath, editAttrs, editCommand, editNodes, editStrings, failedEdits, filename, isExportEdits, isLoaded, isNodeReferenced, isPreviewOnly, liveEdits, namespace, nodes, onReferenceNode, parent, parentNamespace, referenceNode, shortName, showDagPath, showNamespace, successfulEdits, topReference, unresolvedName, withoutCopyNumber
Long name (short name) |
Argument types |
Properties |
filename(f)
|
boolean
|
|
|
Returns string.
A main flag used to query the filename associated with the target reference.
|
|
parentNamespace(pns)
|
boolean
|
|
|
A main flag used to query and return the parent namespace of the target reference.
|
|
shortName(shn)
|
boolean
|
|
|
This flag modifies the '-f/-filename' and '-ns/-namespace' flags.
Used with the '-f/-filename' flag indicates that the file name returned will be the short name
(i.e. just a file name without any directory paths). If this flag is not present, the full name
and directory path will be returned.
Used with the '-ns/-namespace' flag indicates that the namespace returned will be the base name of the namespace.
(i.e. the base name of the full namespace path ":AAA:BBB:CCC" is "CCC" )
|
|
unresolvedName(un)
|
boolean
|
|
|
This flag modifies the '-f/-filename' flag to indicate that the file name
returned will be unresolved (i.e. it will be the path originally
specified when the file was loaded into Maya; this path may
contain environment variables and may not exist on disk). If this
flag is not present, the resolved name will be returned.
|
|
withoutCopyNumber(wcn)
|
boolean
|
|
|
This flag modifies the '-f/-filename' flag to indicate that the file name
returned will not have a copy number (e.g. '{1}') appended to the end. If this
flag is not present, the file name returned may have a copy number
appended to the end.
|
|
dagPath(dp)
|
boolean
|
|
|
This flag modifies the '-n/-nodes' flag to indicate that the names of
any dag objects returned will include as much of the dag path as is
necessary to make the names unique. If this flag is not present, the
names returned will not include any dag paths.
|
|
isNodeReferenced(inr)
|
boolean
|
|
|
Returns boolean.
A main flag used to determine whether or not the target node comes
from a referenced file.
true if the target node comes from a referenced file, false if not.
|
|
isPreviewOnly(ipo)
|
boolean
|
|
|
Returns boolean.
This flag is used to determine whether or not the target reference node is
only a preview reference node.
|
|
referenceNode(rfn)
|
boolean
|
|
|
Returns string.
A main flag used to query the reference node associated with the target
reference.
|
|
namespace(ns)
|
boolean
|
|
|
Returns string.
This flag returns the full namespace path of the target reference, starting from the root namespace ":".
It can be combined with the shortName flag to return just the base name of the namespace.
|
|
nodes(n)
|
boolean
|
|
|
Returns string array.
A main flag used to query the contents of the target reference.
|
|
parent(p)
|
boolean
|
|
|
This flag modifies the '-rfn/-referenceNode' and '-f/-filename' flags
to indicate the the parent of the target reference will be returned.
|
|
topReference(tr)
|
boolean
|
|
|
This flag modifies the '-rfn/-referenceNode' flag
to indicate the top level ancestral reference of the target reference will be
returned.
|
|
editStrings(es)
|
boolean
|
|
|
Returns string array.
A main flag used to query the edits that have
been applied to the target. The edit will be returned
as a valid MEL command. A valid target is either
a reference node, a reference file, or a referenced node.
If a referenced node is specified, only those edits which
affect that node will be returned. If a reference file
or reference node is specified any edit which affects
a node in that reference will be returned. If no target is
specified all edits are returned. This command can be used
on both loaded and unloaded references. By default it will
return all the edits, formatted as MEL commands,
which apply to the target.
This flag cannot be used with either the '-en/-editNodes'
or '-ea/-editAttrs' flags.
|
|
editNodes(en)
|
boolean
|
|
|
Returns string array.
A main flag used to query the edits that have
been applied to the target. Only the names of
the nodes involved in the reference edit will be
returned. If an edit involves multiple nodes (e.g. "connectAttr"
edits) the nodes will be returned as separate,
consecutive entries in the string array. A valid target is either
a reference node, a reference file, or a referenced node.
If a referenced node is specified, only those edits which
affect that node will be returned. If a reference file
or reference node is specified any edit which affects
a node in that reference will be returned. If no target is
specified all edits are returned. This command can
be used on both loaded and unloaded references. By default
it will return all the edits, formatted as MEL commands,
which apply to the target.
This flag can be used in combination with the
'-ea/-editAttrs' flag to indicate that the names
of both the involved nodes and attributes will be
returned in the format 'node.attribute'.
|
|
editAttrs(ea)
|
boolean
|
|
|
Returns string array.
A main flag used to query the edits that have
been applied to the target. Only the names of
the attributes involved in the reference edit will be
returned. If an edit involves multiple attributes (e.g. "connectAttr"
edits) the nodes will be returned as separate,
consecutive entries in the string array. A valid target is either
a reference node, a reference file, or a referenced node.
If a referenced node is specified, only those edits which
affect that node will be returned. If a reference file
or reference node is specified any edit which affects
a node in that reference will be returned. If no target is
specified all edits are returned. This command can
be used on both loaded and unloaded references. By default
it will return all the edits, formatted as MEL commands,
which apply to the target.
This flag can be used in combination with the
'-ea/-editAttrs' flag to indicate that the names
of both the involved nodes and attributes will be
returned in the format 'node.attribute'.
|
|
failedEdits(fld)
|
boolean
|
|
|
This is a secondary flag used to indicate whether or not failed
edits should be acted on (e.g. queried, removed, etc...). A failed
edit is an edit which could not be successfully applied the last
time its reference was loaded.
An edit can fail for a variety of reasons (e.g. the referenced
node to which it applies was removed from the referenced file).
By default failed edits will not be acted on.
|
|
successfulEdits(scs)
|
boolean
|
|
|
This is a secondary flag used to indicate whether or not successful
edits should be acted on (e.g. queried, removed, etc...). A successful
edit is any edit which was successfully applied the last time its
reference was loaded.
By default successful edits will be acted on.
|
|
showDagPath(sdp)
|
boolean
|
|
|
Shows/hides the full dag path for edits. If false only displays the
node-name of reference edits. Must be used with the -editNodes,
-editStrings or -editAttrs flag.
|
|
showNamespace(sns)
|
boolean
|
|
|
Shows/hides the namespaces on nodes in the reference edits.
Must be used with the -editNodes, -editStrings or -editAttrs flag
|
|
liveEdits(le)
|
boolean
|
|
|
Specifies that the edits should be returned based on the live edits
database. Only valid when used in conjunction with the editStrings flag.
|
|
child(ch)
|
boolean
|
|
|
This flag modifies the '-rfn/-referenceNode' and '-f/-filename' flags
to indicate the the children of the target reference will be returned.
Returns a string array.
|
|
isLoaded(il)
|
boolean
|
|
|
Returns a boolean indicating whether the specified reference node or
file name refers to a loaded or unloaded reference.
|
|
isExportEdits(iee)
|
boolean
|
|
|
Returns a boolean indicating whether the specified reference node or file
name is an edits file (created with the Export Edits feature)
|
|
editCommand(ec)
|
string
|
|
|
This is a secondary flag used to indicate which type of reference edits should
be considered by the command.
If this flag is not specified all edit types will be included.
This flag requires a string parameter. Valid values are: "addAttr",
"connectAttr", "deleteAttr", "disconnectAttr", "parent", and "setAttr".
In some contexts, this flag may be specified more than once to specify multiple
edit types to consider.
|
|
onReferenceNode(orn)
|
string
|
|
|
This is a secondary flag used to indicate that only those edits which are stored
on the indicated reference node should be considered. This flag only supports
multiple uses when specified with the "exportEdits" command.
|
|
Flag can appear in Create mode of command
|
Flag can appear in Edit mode of command
|
Flag can appear in Query mode of command
|
Flag can have multiple arguments, passed either as a tuple or a list.
|
import maya.cmds as cmds
# Build a sample scene:
# main scene contains a reference to mid.ma.
# mid.ma contains a reference to bot.ma.
# Create bot.ma with a poly sphere.
#
cmds.polySphere()
cmds.file( rename='bot.ma' )
cmds.file( f=True, s=True, type='mayaAscii')
# Create mid.ma with a poly cone.
# Reference bot.ma into mid.ma and group
# the sphere in bot.ma
#
cmds.file( f=True, new=True )
cmds.file( 'bot.ma', r=True,ns='bot' )
cmds.polyCone()
cmds.group( 'bot:pSphere1' )
cmds.file( rename='mid.ma' )
cmds.file( f=True, s=True, type='mayaAscii')
# Create a poly plane.
# Reference mid.ma into the main scene,
# move the cone in mid.ma, and connect
# the plane to the sphere in bot.ma.
#
cmds.file( f=True, new=True )
cmds.file( 'mid.ma', r=True, ns='mid' )
cmds.select( 'mid:pCone1', r=True )
cmds.move( 5, 5, 5, r=True )
cmds.polyPlane()
cmds.connectAttr( 'pPlane1.ty', 'mid:bot:polySphere1.radius' )
# Now perform some queries:
#
cmds.referenceQuery( 'midRN',filename=True )
# Result: C:/Documents and Settings/user/My Documents/maya/projects/default/scenes/mid.ma
cmds.referenceQuery( 'mid:pCone1', filename=True, shortName=True )
# Result: mid.ma
cmds.referenceQuery( 'mid:botRN', filename=True, parent=True )
# Result: C:/Documents and Settings/user/My Documents/maya/projects/default/scenes/mid.ma
cmds.referenceQuery( 'mid.ma', referenceNode=True )
# Result: midRN
cmds.referenceQuery( 'C:/Documents and Settings/user/My Documents/maya/projects/default/scenes/bot.ma', referenceNode=True)
# Result: mid:botRN
cmds.referenceQuery( 'bot.ma', referenceNode=True, parent=True )
# Result: midRN
cmds.referenceQuery( 'bot.ma', referenceNode=True, topReference=True )
# Result: midRN
cmds.referenceQuery( 'mid:botRN',nodes=True )
# Result:[u'mid:bot:pPlane1', u'mid:bot:pPlaneShape1', u'mid:bot:outputCloth1', u'mid:bot:nCloth1', u'mid:bot:nClothShape1', u'mid:bot:dynamicConstraint1', u'mid:bot:dynamicConstraintShape1', u'mid:bot:nurbsSphere1', u'mid:bot:nurbsSphereShape1', u'mid:bot:pSphere1', u'mid:bot:pSphereShape1', u'mid:bot:lightLinker1', u'mid:bot:layerManager', u'mid:bot:defaultLayer', u'mid:bot:renderLayerManager', u'mid:bot:defaultRenderLayer', u'mid:bot:polyPlane1', u'mid:bot:nucleus1', u'mid:bot:nComponent1', u'mid:bot:uiConfigurationScriptNode', u'mid:bot:sceneConfigurationScriptNode', u'mid:bot:nClothShape1Cache1Start', u'mid:bot:cacheBlend1', u'mid:bot:nClothShape1Cache2', u'mid:bot:nClothShape1Cache1End', u'mid:bot:makeNurbSphere1', u'mid:bot:polySphere1'] #
cmds.referenceQuery( 'pPlane1', isNodeReferenced=True )
# Result: 0
cmds.referenceQuery( 'mid:pCone1', isNodeReferenced=True )
# Result: 1
cmds.referenceQuery( 'mid:botRN', parentNamespace=True )
# Result: mid
cmds.referenceQuery( 'mid:bot:pSphere1', parentNamespace=True )
# Result: mid
cmds.referenceQuery( 'C:/Documents and Settings/user/My Documents/maya/projects/default/scenes/bot.ma', parentNamespace=True )
# Result: mid
print cmds.referenceQuery( 'bot.ma', namespace=True )
# Result: :mid:bot
print cmds.referenceQuery( 'mid:botRN', namespace=True )
# Result: :mid:bot
print cmds.referenceQuery( 'bot.ma', namespace=True, shortName=True )
# Result: bot
print cmds.referenceQuery( 'mid.ma', namespace=True )
# Result: :mid
print cmds.referenceQuery( 'mid.ma', namespace=True, shortName=True )
# Result: mid