pymel.core.system.referenceEdit

referenceEdit(*args, **kwargs)

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 -failedEditsand -successfulEditsflags). 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.

Flags:

Long Name / Short Name Argument Types Properties
applyFailedEdits / afe bool ../../../_images/create.gif
  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 unicode, unicode ../../../_images/create.gif
  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.
editCommand / ec unicode ../../../_images/create.gif ../../../_images/query.gif
  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, lockand unlock. In some contexts, this flag may be specified more than once to specify multiple edit types to consider.
failedEdits / fld bool ../../../_images/create.gif
  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.
onReferenceNode / orn unicode ../../../_images/create.gif ../../../_images/query.gif
  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 exportEditscommand. Flag can have multiple arguments, passed either as a tuple or a list.
removeEdits / r bool ../../../_images/create.gif
  Remove edits which affect the specified unloaded commandTarget.
successfulEdits / scs bool ../../../_images/create.gif
  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.

Derived from mel command maya.cmds.referenceEdit

Example:

import pymel.core as pm

#
# 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.
pm.referenceEdit( 'midRN', removeEdits=True )
pm.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.
pm.referenceEdit( 'midRN', editCommand='setAttr', removeEdits=True )
pm.referenceEdit( 'mid.ma', editCommand='setAttr', removeEdits=True )
# Remove all the "parent" edits which apply to mid:pSphere1.
pm.referenceEdit( 'mid:pSphere1', editCommand='parent', removeEdits=True )
# Remove all the "connectAttr" edits which apply to mid:pSphere1.translateX.
pm.referenceEdit( 'mid:pSphere1.translateX', 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 you had previously opened mid.ma and made
# modifications to bot.ma, those edits can only be removed by opening
# mid.ma and issuing a referenceEdit command.
#
pm.referenceEdit( 'mid:botRN', removeEdits=True )
pm.referenceEdit( 'bot.ma', removeEdits=True )
#
# EXAMPLE FOR -changeEditTarget
#
tempDir = pm.internalVar(utd=True)
# Create a reference containing pSphere1.
#
pm.file( f=True, new=True )
pm.polySphere( ch=1, r=1, sx=20, sy=20, ax=(0, 1, 0) )
newFileName = '%sref.ma' % tempDir
pm.file( rename=newFileName )
pm.file( f=True, s=True, type='mayaAscii')
# Reference the file in and position pSphere1
#
pm.file( f=True, new=True )
pm.file( newFileName, r=True, ns='ref' )
pm.select( 'ref:pSphere1', r=True )
pm.move( 5, 5, 5 )
topFileName = '%stop.ma' % tempDir
pm.file( rename=topFileName )
pm.file( f=True, s=True, type='mayaAscii')
# Later on its determined that pSphere1 is actually
# BobMrozowski.
#
pm.file( newFileName, f=True, o=True )
pm.rename( 'pSphere1', 'BobMrozowski' )
pm.file( f=True, s=True, type='mayaAscii')
# Now go to open your main scene again...
#
pm.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...
#
pm.referenceEdit( 'refRN', changeEditTarget=('ref:pSphere1','ref:BobMrozowski') )
# ... and then force all previously failing edits affecting
# refRN to be re-applied.
#
pm.referenceEdit( 'refRN', applyFailedEdits=True )
# BobMrozowski should now be back at 5 5 5.
#