pymel.core.animation.choice

static animation.choice(*args, **kwargs)

The choice command provides a mechanism for changing the inputs to an attribute based on some (usually time-based) criteria. For example, an object could be animated from frames 1 to 30 by a motion path, then from frames 30 to 50 it follows keyframe animation, and after frame 50 it returns to the motion path. Or, a revolve surface could change its input curve depending on some transform’s rotation value.The choice command creates a choice node (if one does not already exist) on all specified attributes of the selected objects. If the attribute was already connected to something, that something is now reconnected to the i’th index of the choice node’s input (or the next available input if the -in/index flag is not specified). If a source attribute is specified, then that attribute is connected to the choice node’s i’th input instead.The choice node operates by using the value of its selector attribute to determine which of its input attributes to pass through to its output. The input attributes can be of any type. For example, if the selector attribute was connected by an animation curve with keyframes at (1,1), (30,2) and (50,1), then that would mean that the choice node would pass on the data from input[1] from time 1 to 30, and after time 50, and the data from input[2] between times 30 and 50.This command returns the names of the created or modified choice nodes, and if a keyframe was added to the animation curve, it specifies the index (or value on the animation curve).

Flags:

Long name (short name)		Argument Types	Properties
attribute (at)		unicode
	specifies the attributes onto which choice node(s) should be created. The default is all keyable attributes of the given objects. Note that although this flag is not queryable, it can be used to qualify which attributes of the given objects to query.
controlPoints (cp)		bool
	Explicitly specify whether or not to include the control points of a shape (see -sflag) in the list of attributes. Default: false. Flag can have multiple arguments, passed either as a tuple or a list.
index (index)		int
	specifies the multi-input index of the choice node to connect the source attribute to. When queried, returns a list of integers one per specified -t/time that indicates the multi-index of the choice node to use at that time.
name (n)		unicode
	the name to give to any newly created choice node(s). When queried, returns a list of strings.
selector (sl)		PyNode
	specifies the attribute to be used as the choice node’s selector. The value of the selector at a given time determines which of the choice node’s multi-indices should be used as the output of the choice node at that time. This flag is only editable (it cannot be specified at creation time). When queried, returns a list of strings.
shape (s)		bool
	Consider all attributes of shapes below transforms as well, except controlPoints. Default: true
sourceAttribute (sa)		PyNode
	specifies the attribute to connect to the choice node that will be selected at the given time(s) specified by -t/time.
time (t)		time
	specifies the time at which the choice should use the given source attribute, or the currently connected attribute if source attribute is not specified. The default is the curren time. Note that although this flag is not queryable, it can be used to qualify the times at which to query the other attributes.

Derived from mel command maya.cmds.choice

Example:

import pymel.core as pm

# This example animates an object airplane along a motion path
# from frames 1 to 30, then continues with keyframe animation until
# frame 50, then returns to the motion path at frame 50.
path = pm.curve(d=3,p=[(-10, 0, 0),(-6, 0, 10),(-3, 0, -10),(10, 0, 0)],k=[0, 0, 0, 1, 1, 1])
pm.polyPlane()
# Result: [nt.Transform(u'pPlane1'), nt.PolyPlane(u'polyPlane1')] #
pm.pathAnimation('pPlane1',c=path,stu=1,etu=100)
# Result: u'motionPath1' #

# Set a choice node on the path animation, ensuring that the choice
# selects path animation from 1 to 30, and then returns at 50.
pm.choice( 'pPlane1', at='ty', t=[1,30,50] )
# Result: [Attribute(u'choice1.input[0]')] #

# Start a new kind of choice at time 31
pm.choice( 'pPlane1', at='ty', t=31 )
# Result: [Attribute(u'choice1.input[1]')] #

# Create some keyframe animation between times 31 and 49
pm.currentTime( 31 )
# Result: 31.0 #
pm.setKeyframe( 'pPlane1', at="ty" )
# Result: 1 #
pm.move( 1, 2, 3, r=True )
pm.setKeyframe( 'pPlane1', at="ty", t=40 )
# Result: 1 #
pm.move( 4, 5, 6, r=True )
pm.setKeyframe( 'pPlane1', at="ty", t=49 )
# Result: 1 #

# Note that the -at/attribute and -t/time flags are not
# queryable in themselves, but they can be used to
# modify the choice nodes to query.

# What is the attribute that is connected to the pPlane1.ty choice node's
# selector attribute?
pm.choice( 'pPlane1', at='ty', query=True, sl=True)
# Result: [u'choice1_selector.output'] #

# Which indices will be evaluated for the choice node to pPlane1.ty
# at the given times?
pm.choice( 'pPlane1', at='ty', t=[1,30,50], query=True, index=True)
# Result: [0, 0, 0] #