Show frames

Go to: Synopsis. Return value. Flags. Python examples.

Synopsis

choice( [objects] , [attribute=string], [controlPoints=boolean], [index=uint], [name=string], [selector=name], [shape=boolean], [sourceAttribute=name], [time=time])

Note: Strings representing object names and arguments must be separated by commas. This is not depicted in the synopsis.

choice is undoable, queryable, and editable.

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

Return value

string[]The newly created and/or modified choice nodes, with the attribute for which a selector keyframe was created.
For example: choice1.input[3] choice2.input[3]

In query mode, return type is based on queried flag.

Flags

attribute, controlPoints, index, name, selector, shape, sourceAttribute, time
Long name (short name) Argument types Properties
attribute(at) string createmultiuse
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.

In query mode, this flag needs a value.
controlPoints(cp) boolean create
Explicitly specify whether or not to include the control points of a shape (see "-s" flag) in the list of attributes. Default: false.
index(index) uint createquery
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) string createquery
the name to give to any newly created choice node(s). When queried, returns a list of strings.
selector(sl) name createquery
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) boolean create
Consider all attributes of shapes below transforms as well, except "controlPoints". Default: true
sourceAttribute(sa) name create
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 createmultiuse
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.

In query mode, this flag needs a value.
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.

Python examples

import maya.cmds as cmds

# 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 = cmds.curve(d=3,p=[(-10, 0, 0),(-6, 0, 10),(-3, 0, -10),(10, 0, 0)],k=[0, 0, 0, 1, 1, 1])
cmds.polyPlane()
cmds.pathAnimation('pPlane1',c=path,stu=1,etu=100)

# Set a choice node on the path animation, ensuring that the choice
# selects path animation from 1 to 30, and then returns at 50.
cmds.choice( 'pPlane1', at='ty', t=[1,30,50] )

# Start a new kind of choice at time 31
cmds.choice( 'pPlane1', at='ty', t=31 )

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

# 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?
cmds.choice( 'pPlane1', at='ty', query=True, sl=True)

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