pymel.core.general.instance

instance(*args, **kwargs)

Instancing is a way of making the same object appear twice in the scene. This is accomplished by creation of a new transform node that points to an exisiting object. Changes to the transform are independent but changes to the “instanced” object affect all instances since the node is shared. If no objects are given, then the selected list is instanced. When an object is instanced a new transform node is created that points to the selected object. The smart transform feature allows instance to transform newly instanced objects based on previous transformations between instances. Example: Instance an object and move it to a new location. Instance it again with the smart transform flag. It should have moved once again the distance you had previously moved it. Note: changing the selected list between smart instances will cause the transform information to be deleted. It returns a list of the new objects created by the instance operation. See also:duplicate

Modifications:
  • returns a list of PyNode objects
Flags:
Long name (short name) Argument Types Properties
leaf (lf) bool ../../../_images/create.gif
 
Instances leaf-level objects. Acts like duplicate except leaf-level objects are instanced.
name (n) unicode ../../../_images/create.gif
 
Name to give new instanceFlag can appear in Create mode of commandFlag can have multiple arguments, passed either as a tuple or a list.
smartTransform (st) bool ../../../_images/create.gif
 
Transforms instances item based on movements between transforms

Derived from mel command maya.cmds.instance

Example:

import pymel.core as pm

# Create a hierarchy
pm.sphere( n='sphere1' )
# Result: [nt.Transform(u'sphere1'), nt.MakeNurbSphere(u'makeNurbSphere1')] #
pm.move( 3, 0, 0 )
pm.sphere( n='sphere2' )
# Result: [nt.Transform(u'sphere2'), nt.MakeNurbSphere(u'makeNurbSphere2')] #
pm.move( -3, 0, 0 )
pm.group( 'sphere1', 'sphere2', n='group1' )
# Result: nt.Transform(u'group1') #
pm.group( 'group1', n='group2' )
# Result: nt.Transform(u'group2') #

# Create an instance of one of the spheres
pm.instance( 'sphere1' )
# Result: [nt.Transform(u'sphere3')] #

# Duplicate the hierarchy except for the shapes which are
# instanced.instances of all leaf level shapes
pm.instance( 'group1', leaf=True )
# Result: [nt.Transform(u'group3')] #

# Create a row of 4 instanced circles which are equally spaced
pm.circle( n='circle1' )
# Result: [nt.Transform(u'circle1'), nt.MakeNurbCircle(u'makeNurbCircle1')] #
pm.instance()
# Result: [nt.Transform(u'circle2')] #
pm.move( 3, 0, 0 )
pm.instance( smartTransform=True )
# Result: [nt.Transform(u'circle3')] #
pm.instance( smartTransform=True )
# Result: [nt.Transform(u'circle4')] #

Previous topic

pymel.core.general.inheritTransform

Next topic

pymel.core.general.instanceable

Core

Core Modules

Other Modules

This Page