keyingGroup

Go to: Synopsis. Return value. Related. Flags. MEL examples.

Synopsis

keyingGroup [-activator string] [-addElement name] [-afterFilters boolean] [-category string] [-clear name] [-color int] [-copy name] [-edges boolean] [-editPoints boolean] [-empty] [-excludeDynamic] [-excludeRotate] [-excludeScale] [-excludeTranslate] [-excludeVisibility] [-facets boolean] [-flatten name] [-forceElement name] [-include name] [-intersection name] [-isIntersecting name] [-isMember name] [-layer boolean] [-minimizeRotation boolean] [-name string] [-noSurfaceShader boolean] [-noWarnings] [-nodesOnly] [-remove name] [-removeActivator string] [-renderable boolean] [-setActiveFilter string] [-size] [-split name] [-subtract name] [-text string] [-union name] [-vertices boolean] objects

keyingGroup is undoable, queryable, and editable.

Return value

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

Related

Flags

Long name (short name)	Argument types	Properties
-name(-n)	string
Assigns string as the name for a new set. This flag is only valid for operations that create a new set.
-text(-t)	string
Defines an annotation string to be stored with the set.
-empty(-em)
Indicates that the set to be created should be empty. That is, it ignores any arguments identifying objects to be added to the set. This flag is only valid for operations that create a new set.
-color(-co)	int
Defines the hilite color of the set. Must be a value in range [-1, 7] (one of the user defined colors). -1 marks the color has being undefined and therefore not having any affect. Only the vertices of a vertex set will be displayed in this color.
-layer(-l)	boolean
OBSOLETE. DO NOT USE.
-vertices(-v)	boolean
Indicates the new set can contain vertices only. This flag is for use in creation or query mode only. The default value is false.
-edges(-eg)	boolean
Indicates the new set can contain edges only. This flag is for use in creation or query mode only. The default value is false.
-facets(-fc)	boolean
Indicates the new set can contain facets only. This flag is for use in creation or query mode only. The default value is false.
-editPoints(-ep)	boolean
Indicates the new set can contain editPoints only. This flag is for use in creation or query mode only. The default value is false.
-renderable(-r)	boolean
This flag indicates that a special type of set should be created. This type of set (shadingEngine as opposed to objectSet) has certain restrictions on its membership in that it can only contain renderable elements such as lights and geometry. These sets are referred to as shading groups and are automatically connected to the "renderPartition" node when created (to ensure mutual exclusivity of the set's members with the other sets in the partition). This flag is for use in creation or query mode only. The default value is false which means a normal set is created.
-noSurfaceShader(-nss)	boolean
If set is renderable, do not connect it to the default surface shader. Flag has no meaning or effect for non renderable sets. This flag is for use in creation mode only. The default value is false.
-copy(-cp)	name
Copies the members of the given set to a new set. This flag is for use in creation mode only.
-size(-s)
Use the size flag to query the length of the set.
-subtract(-sub)	name
An operation between two sets which returns the members of the first set that are not in the second set.
-union(-un)	name
An operation that returns a list of all the members of all sets listed.
-intersection(-int)	name
An operation that returns a list of items which are members of all the sets in the list.
-clear(-cl)	name
An operation which removes all items from the given set making the set empty.
-flatten(-fl)	name
An operation that flattens the structure of the given set. That is, any sets contained by the given set will be replaced by its members so that the set no longer contains other sets but contains the other sets' members.
-nodesOnly(-no)
This flag is usable with the -q/query flag but is ignored if used with another queryable flags. This flag modifies the results of the set membership query such that when there are attributes (e.g. sphere1.tx) or components of nodes included in the set, only the nodes will be listed. Each node will only be listed once, even if more than one attribute or component of the node exists in the set.
-isIntersecting(-ii)	name
An operation which tests whether the sets in the list have common members.
-isMember(-im)	name
An operation which tests whether all the given items are members of the given set.
-split(-sp)	name
Produces a new set with the list of items and removes each item in the list of items from the given set.
-noWarnings(-nw)
Indicates that warning messages should not be reported such as when trying to add an invalid item to a set. (used by UI)
-addElement(-add)	name
Adds the list of items to the given set. If some of the items cannot be added to the set because they are in another set which is in the same partition as the set to edit, the command will fail.
-include(-in)	name
Adds the list of items to the given set. If some of the items cannot be added to the set, a warning will be issued. This is a less strict version of the -add/addElement operation.
-remove(-rm)	name
Removes the list of items from the given set.
-forceElement(-fe)	name
For use in edit mode only. Forces addition of the items to the set. If the items are in another set which is in the same partition as the given set, the items will be removed from the other set in order to keep the sets in the partition mutually exclusive with respect to membership.
-afterFilters(-af)	boolean
Default state is false. This flag is valid in edit mode only. This flag is for use on sets that are acted on by deformers such as sculpt, lattice, blendShape. The default edit mode is to edit the membership of the group acted on by the deformer. If you want to edit the group but not change the membership of the deformer, set the flag to true.
-excludeTranslate(-et)
When creating the keying group, exclude translate attributes from transform-type nodes. For example, if your keying group contains joints only, perhaps you only want to include rotations in the keying group.
-excludeRotate(-er)
When creating the keying group, exclude rotate attributes from transform-type nodes.
-excludeScale(-es)
When creating the keying group, exclude scale attributes from transform-type nodes.
-excludeVisibility(-ev)
When creating the keying group, exclude visibility attribute from transform-type nodes.
-excludeDynamic(-ed)
When creating the keying group, exclude dynamic attributes.
-activator(-act)	string
Sets the selected node(s) as activators for the given keying group. In query mode, returns list of objects that activate the given keying group
-removeActivator(-rac)	string
Removes the selected node(s) as activators for the given keying group.
-setActiveFilter(-fil)	string
Sets the global, active keying group filter, which will affect activation of keying groups. Only keying groups with categories that match the filter will be activated. If the setActiveFilter is set to "NoKeyingGroups", keying groups will not be activated at all. If the setActiveFilter is set to "AllKeyingGroups", we will activate any keying group rather than just those with matching categories.
-category(-cat)	string
Sets the keying group's category. This is what the global, active keying group filter will use to match.
-minimizeRotation(-mr)	boolean
This flag only affects the attribute contained in the immediate keyingGroup. It does not affect attributes in sub-keyingGroups. Those will need to set minimizeRotation on their respective keyingGroups

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 be used more than once in a command.

MEL examples

// Create a keying group with the keyable attrs of the currently
// selected object
//
file -f -new;
polySphere -name "sphere1";
keyingGroup -name sphereKG;
// Query the members: should be sphere1's TRS and visibility
//
string $members[] = `keyingGroup -q sphereKG`;
// create a keying group which contains another keying group
//
keyingGroup -n parentKG sphereKG;
// keying the parent KG should automatically key the sub KGs as well
//
select parentKG;
setKeyframe -t 1;
// Add 2 other spheres to the sphereKG
//
polySphere -n sphere2;
polySphere -n sphere3;
keyingGroup -e -add sphereKG sphere2 sphere3;
// Make another object the activator for the sphereKG. So if
// this object is keyed, the sphereKG will be keyed. Note
// that the activator itself does not have to be part of the
// keying group. If it is not part of the keyingGroup, it
// will not be keyed. So only the spheres will be keyed below.
// If the cube is to be keyed as well, execute:
// keyingGroup -e -add sphereKG cube1;
//
polyCube -n cube1;
keyingGroup -e -activator sphereKG cube1;
select cube1;
setKeyframe -t 10;