Go to: Synopsis. Return value. Keywords. Related. Flags. Python examples.
referenceQuery([dagPath=boolean], [editAttrs=boolean], [editNodes=boolean], [editStrings=boolean], [failedEdits=boolean], [filename=boolean], [isNodeReferenced=boolean], [nodes=boolean], [parent=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
dagPath, editAttrs, editNodes, editStrings, failedEdits, filename, isNodeReferenced, nodes, parent, 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.
|
|
shortName(shn)
|
boolean
|
|
|
This flag modifies the '-f/-filename' flag to indicate 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.
|
|
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.
|
|
referenceNode(rfn)
|
boolean
|
|
|
Returns string.
A main flag used to query the reference node associated with the target
reference.
|
|
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
|
|
|
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