Go to: Synopsis. Return value. Keywords. Related. Flags. Python examples.
referenceEdit([applyFailedEdits=boolean], [changeEditTarget=[string, string]], [editCommand=string], [failedEdits=boolean], [onReferenceNode=string], [removeEdits=boolean], [successfulEdits=boolean])
Note: Strings representing object names and arguments must be separated by commas. This is not depicted in the synopsis.
referenceEdit is NOT undoable, NOT queryable, and NOT editable.
Use this command to remove and change the modifications which have
been applied to references. A valid commandTarget is either a reference node,
a reference file, a node in a reference, or a plug from a reference.
Only modifications that have been made from the currently open scene can
be changed or removed. The 'referenceQuery -topReference' command can be used
to determine what modifications have been made to a given commandTarget.
Additionally only unapplied edits will be affected. Edits are unapplied
when the node(s) which they affect are unloaded, or when they could
not be successfully applied. By default this command only works on failed
edits (this can be adjusted using the "-failedEdits" and
"-successfulEdits" flags).
Specifying a reference node as the command target is equivalent to
specifying every node in the target reference file as a target. In this
situation the results may differ depending on whether the target
reference is loaded or unloaded. When it is unloaded, edits that affect both
a node in the target reference and a node in one of its descendant references
may be missed (e.g. those edits may not be removed). This is because when a
reference is unloaded Maya no longer retains detailed information about which
nodes belong to it. However, edits that only affect nodes in the target reference
or in one of its ancestral references should be removed as expected.
When the flags -removeEdits and -editCommand are used together, by default
all connectAttr edits are removed from the specified source object. To remove
only edits that connect to a specific target object, the target object can be
passed as an additional argument to the command. This narrows the match criteria,
so that only edits that connect the source object to the provided target in this
additional argument are removed. See the example below.
NOTE:
When specifying a plug it is important to use the appropriate long attribute
name.
None
reference, attribute, node
file, referenceQuery
applyFailedEdits, changeEditTarget, editCommand, failedEdits, onReferenceNode, removeEdits, successfulEdits
| Long name (short name) |
Argument types |
Properties |
applyFailedEdits(afe)
|
boolean
|
|
|
Attempts to apply any unapplied edits. This flag is useful if previously
failing edits have been fixed using the -changeEditTarget flag. This flag
can only be used on loaded references. If the command target is a referenced
node, the associated reference is used instead.
|
|
changeEditTarget(cet)
|
[string, string]
|
|
|
Used to change a target of the specified edits.
This flag takes two parameters: the old target of the edits, and the
new target to change it to. The target can either be a node name ("node"), a
node and attribute name ("node.attr"), or just an attribute name (".attr").
If an edit currently affects the old target, it will be changed to affect
the new target.
Flag 'referenceQuery' should be used to determine the format of the edit targets.
As an example most edits store the long name of the attribute
(e.g. "translateX"), so when specifying the old target, a long name must also
be used. If the short name is specified (e.g. "tx"), chances are the edit
won't be retargeted.
|
|
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 be acted on.
|
|
removeEdits(r)
|
boolean
|
|
|
Remove edits which affect the specified unloaded commandTarget.
|
|
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. This flag will have no affect if the
commandTarget is loaded.
By default successful edits will not be acted on.
|
|
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", "setAttr",
"lock" and "unlock". 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
#
# EXAMPLE FOR -removeEdits
#
# Assume:
# main.ma contains a reference to mid.ma.
# mid.ma contains a reference to bot.ma.
# NOTE: The target reference must be unloaded for the
# following commands to work.
# Remove all the edits which apply to mid.ma.
# This can be done by specifying either the reference
# node or the reference file.
cmds.referenceEdit( 'midRN', removeEdits=True )
cmds.referenceEdit( 'mid.ma', removeEdits=True )
# Remove all "setAttr" edits which apply to mid.ma.
# This can be done by specifying either the reference
# node or the reference file.
cmds.referenceEdit( 'midRN', editCommand='setAttr', removeEdits=True )
cmds.referenceEdit( 'mid.ma', editCommand='setAttr', removeEdits=True )
# Remove all the "parent" edits which apply to mid:pSphere1.
cmds.referenceEdit( 'mid:pSphere1', editCommand='parent', removeEdits=True )
# Remove all the "connectAttr" edits which apply to mid:pSphere1.translateX.
cmds.referenceEdit( 'mid:pSphere1.translateX', editCommand='connectAttr', removeEdits=True )
#Remove the "connectAttr" edit having mid:pSphere1.translateX as a source and mid:pSphere2.translateX as a destination.
cmds.referenceEdit( ["|mid:pSphere1.translateX", "|mid:pSphere2.translateX"], failedEdits = True, successfulEdits = True, editCommand = 'connectAttr', removeEdits = True )
# Remove all the edits which apply to bot.ma and are stored on midRN.
# The referenceEdit command is only capable of removing edits which
# are stored on a top level reference node. The only edits which
# are stored on a top level reference node are those which were made
# from the main scene. If the file mid.ma was previously opened and
# modifications were made to bot.ma, those edits can only be removed
# by opening mid.ma and issuing a referenceEdit command.
#
cmds.referenceEdit( 'mid:botRN', removeEdits=True )
cmds.referenceEdit( 'bot.ma', removeEdits=True )
#
# EXAMPLE FOR -changeEditTarget
#
tempDir = cmds.internalVar(utd=True)
# Create a reference containing pSphere1.
#
cmds.file( f=True, new=True )
cmds.polySphere( ch=1, r=1, sx=20, sy=20, ax=(0, 1, 0) )
newFileName = '%sref.ma' % tempDir
cmds.file( rename=newFileName )
cmds.file( f=True, s=True, type='mayaAscii')
# Reference the file in and position pSphere1
#
cmds.file( f=True, new=True )
cmds.file( newFileName, r=True, ns='ref' )
cmds.select( 'ref:pSphere1', r=True )
cmds.move( 5, 5, 5 )
topFileName = '%stop.ma' % tempDir
cmds.file( rename=topFileName )
cmds.file( f=True, s=True, type='mayaAscii')
# Later on its determined that pSphere1 is actually
# BobMrozowski.
#
cmds.file( newFileName, f=True, o=True )
cmds.rename( 'pSphere1', 'BobMrozowski' )
cmds.file( f=True, s=True, type='mayaAscii')
# Now go to open your main scene again...
#
cmds.file( topFileName, f=True, o=True )
# ... and notice that BobMrozowski is back at
# the origin.
#
# So remap all edits so that anything that used to
# affect ref:pSphere1 now affects ref:BobMrozowski...
#
cmds.referenceEdit( 'refRN', changeEditTarget=('ref:pSphere1','ref:BobMrozowski') )
# ... and then force all previously failing edits affecting
# refRN to be re-applied.
#
cmds.referenceEdit( 'refRN', applyFailedEdits=True )
# BobMrozowski should now be back at 5 5 5.
#