Overview

This manual lists and describes the global procedures of the DPK_animUISetup.mel script. They are used by the animUI to create, query, and edit animation setups for use in the UI. These descriptions might help when you want to automate such setups e.g. in rigging scripts.

Sourcing

As said above, the DPK_animUISetup.mel is a procedure collection with several global procs. Before you use such collections, you usually source them.

You don’t have to do so with this script! Instead, simply call DPK_animUISetup; at the beginning of your script (not within a proc). This procedure doesn’t do anything—it just ensures Maya knows the script and sources it when necessary.

Creating/Editing Procedures

ReturnProcedure NameArgument(s)

 

DPK_animUI_create

( string $node )

Sets up the given $node as an animUI node. After this step, attrs can be added to it, presets can be created, etc..

 

DPK_animUI_removeSetup

( string $node )

Removes the complete animUI setup from the given $node. All custom attributes and connections that were created by this script will be removed and the original state is restored.

 

DPK_animUI_convertToNew

( string $node )

Converts a setup on the $node for the old DPK_animationInterface script into a setup that can be read by this new script. After this, both scripts can be used with the object. You should know, however, that the two setups are independent. This means that changes to one do not affect the other.

int[]

DPK_animUI_addAttrs

( string $node, string $attrs[], int $section )

Adds all given $attrs to the animUI $node so that they can be used in presets and are visible in the animUI. $section is the section into which the attrs will be added. Returns the IDs of the new attrs.

 

DPK_animUI_removeAttrs

( string $node, int $attrs[] )

Removes the specified $attrs from the animUI setup.

int

DPK_animUI_createSection

( string $node, string $name )

Creates a new section with the given $name. Returns the ID of the new section.

 

DPK_animUI_deleteSection

( string $node, int $section )

Removes the specified $section and all its attrs from the animUI setup.

string

DPK_animUI_renameSection

( string $node, int $section, string $newName )

Renames the specified $section to the $newName. Returns the new and possibly changed name (due to name clashing) of the section.

 

DPK_animUI_moveSection

( string $node, int $section, string $dir )

Reorders the specified $section and moves it in the given $dir. The direction is a string and can either be "up" or "down". When moving up, the section will be listed earlier in the array (i.e. on a lower index).

 

DPK_animUI_moveAttrs

( string $node, int $section, int $attrs[], string $dir )

Reorders the attrs of the specified $section. All attributes in the $attrs array should be in this section. $dir specifies the direction to move the attrs in and can be either "up" or "down".

 

DPK_animUI_moveAttrsToSection

( string $node, int $attrs[], int $section )

Moves the specified $attrs (specified using their IDs) into the $section. This has no influence on their values in presets.

 

DPK_animUI_autoSyncPairs

( string $node, int $attrs[], int $side )

Takes the given $attrs, removes all their left-right or top-bottom settings (depending on the value of $side), and re-configures them using the integrated auto-matching.

int

DPK_animUI_createPreset

( string $node, string $name )

Creates a new preset with the given $name. It will contain the current values of the attributes of the setup. Returns the ID of the new preset.

 

DPK_animUI_deletePresets

( string $node, int $presets[] )

Removes the specified $presets from the animUI setup.

string

DPK_animUI_renamePreset

( string $node, int $preset, string $newName )

Renames the specified $preset to the $newName. Returns the new and possibly changed name (due to name clashing) of the preset.

 

DPK_animUI_updatePreset

( string $node, int $preset )

Removes all values of the specified $preset and replaces them with the current values of the attributes of the animUI setup. The ignore list (the attributes that are ignored by this preset) isn’t changed.

 

DPK_animUI_ignoreAttrs

( string $node, int $preset, int $attrs[] )

Edits the given $preset so that it ignores the specified $attrs. The previous ignore list will be removed and replaced by the $attrs.

 

DPK_animUI_setPresetOrder

( string $node, int $allPresets[] )

Sets the order of the presets as listed in the $allPresets array. Any presets not listed there will be appended after the others.

Querying Procedures

ReturnProcedure NameArgument(s)

string[]

DPK_animUI_getOldSetups

( int $hasNew[] )

Returns a string array containing all nodes in the current scene that have a setup for the old DPK_animationInterface script. The $hasNew argument is an implicit return and will have one element for each returned object on corresponding indices. The value will be 0 for a node that has no setup for the new script and 1 for nodes that have.

int

DPK_animUI_numUnconverted

()

Returns the number of nodes with an old setup that don’t have a new setup.

int

DPK_animUI_isSetup

( string $node )

Returns 1 if the given $node is set up as an animUI node, 0 otherwise.

string[]

DPK_animUI_getNodes

()

Returns a string array containing all existing animUI nodes in the scene.

string[]

DPK_animUI_getPresets

( string $node, int $IDs[] )

Returns a string array containing all presets of the given animUI setup node ($node). The $IDs array will be filled with the ids of the presets. Each element of the return array has an id in this array.

float[]

DPK_animUI_getPresetAttrValues

( string $node, int $presets[], string $attrs[], int $attrIDs[], float $current[] )

Returns a float array containing a value for each attr (specified by their name in $attrs, ID in $attrIDs, and value in $current). The value will be the average value the attr has in the specified $presets. When a preset ignores a certain attribute, the other presets don’t get more influence. Instead, the attribute will be handled as if the preset contained its current value.

float[]

DPK_animUI_getAttrValues

( string $node )

Returns a float array containing a value for each attr in the animUI setup. Taking the ID of an attribute and multiplying it by 2 results in the index at which the usual value will be stored in the return array. Adding one to this index gets us to the right value of a bilateral bcs weight. This is only relevant for bilateral bcs weights, as these have one ID but two values.

string[]

DPK_animUI_getSections

( string $node, int $IDs[] )

Returns a string array containing all sections of the given animUI setup node ($node). The $IDs array will be filled with the ids of the sections. Each element of the return array has an id in this array.

string[]

DPK_animUI_getAttrs

( string $node, int $type, int $section, int $skipMissing, int $expandBcs, int $IDs[] )

Returns a string array with all attributes in the setup. $type specifies what string will be returned for an attr:

  • $type == 0: returns the path to the attr in the scene

  • $type == 1: returns the alt1 name this attr has in the setup

  • $type == 2: returns the alt2 name this attr has in the setup

When $section is -1, all attrs will be returned. Otherwise, only the attrs of the specified section are returned. Their IDs are put into the $IDs integer array. $skipMissing specifies whether non-connected attrs should be listed or not. If it is true, only the attributes with valid connections are returned. $expandBcs specifies whether to return both attributes of bilateral bcs weights or just the weight’s own name.

string[]

DPK_animUI_getAttr

( string $node, int $attr, int $side, int $IDs[] )

Returns various information about the $attr (specified by its ID). The actual return is a string array. $side specifies whether to return the left-right (== 0) or top-bottom pair (== 1) of which the $attr is part of. If it is -1, the attr is returned without symmetry computation.

In case the attr doesn’t have a valid connection, the return and $IDs will be empty.

When the attr is a usual attr without symmetry (or when $side == -1), the return will be a string array with only one element, which is the path to the attr in the scene. When the attr is a bilateral bcs weight but $side is -1, the $IDs array has one element (the $attr) but the return array will be the left weightVal and the weight’s main name.

When the attr has defined symmetry or is a bilateral bcs weight and $side is not -1, the return will contain:

  • [0]: the left (or top) attr path

  • [1]: the right (or bottom) attr path

When we want the left-right pair and the attr is a bilateral bcs weight:

  • [2]: bcsNode.weightName

When we want the top-bottom pair and both attrs are bilateral bcs weights:

  • [2]: bcsNode.topWeightName

  • [3]: bcsNode.bottomWeightName

The $IDs argument is used to indirectly return the attr IDs. It may have:

  • 0 elements: The $attr doesn’t exist or has no connection.

  • 1 elements: The $attr is a usual attr or $side is -1.

  • 2 elements: The attribute pair with $attr of the $side has been found.

string

DPK_animUI_getOtherAttr

( string $node, int $attr, int $bcsR, int $side, int $IDs[] )

Returns the attribute at the other side of the given $attr, where the axis is specified with $side (0 == left-right, 1 == top-bottom). $bcsR specifies whether the $attr is on the right side of a bilateral bcs weight. This is important because a bilateral bcs weight has the same attr ID (in this case $attr) as its right counterpart. The $IDs array will contain the id of the found attribute or nothing when none was found. It is an array because this is the only way to achieve implicit returns (MEL doesn’t know pointers or references at the moment).

int

DPK_animUI_isBilateral

( string $node, int $attr )

Returns 1 when the $attr is a bilateral bcs weight.

int

DPK_animUI_isAttr

( string $node, string $nodeAttr )

Returns -1 when the attribute $nodeAttr is currently not part of the animUI setup. If it is, the returned integer will be ID of the attr.

int[]

DPK_animUI_findSyncPair

( string $node, int $attr, int $side )

Tries to find a matching attr for $attr and returns an int array with the left and right (or top and bottom) attrs of the pair. The specified $attr can either be on index 0 or 1 of the return, depending on whether it is the left or right of the two.

If no match is found, the return will contain just one element (the $attr). If the $attr doesn’t exist, the return is empty.

When the $attr is a bilateral bcs weight, the return will be two elements with the same value ($attr).

$side is 0 for left-right and 1 for top-bottom.

Preset/Section Library Procedures

All procedures dealing with the library require the $libFile argument. This is a string containing a path to a library text file. This file has to exist and must be readable for querying operations and writable when it needs to be edited.

For an explanation of what the library is and how it works, see 4.8 Preset/Section Library.

ReturnProcedure NameArgument(s)

string[]

DPK_animUI_lib_getChars

( string $libFile )

Returns a string array with all characters defined in the $libFile.

string[]

DPK_animUI_lib_getPresets

( string $libFile, string $char )

Returns all presets defined for the $char character in the $libFile.

string[]

DPK_animUI_lib_getSections

( string $libFile, string $char )

Returns all sections defined for the $char character in the $libFile.

string

DPK_animUI_lib_createCharacter

( string $libFile, string $name )

Creates a new character called $name in the $libFile library. The name is made unique if it isn’t already. Returns the possibly changed unique name.

string

DPK_animUI_lib_renameCharacter

( string $libFile, string $char, string $newName )

Renames the $char character to the $newName. The name is made unique if it isn’t already. Returns the possibly changed unique name.

int

DPK_animUI_lib_deleteCharacter

( string $libFile, string $char )

Removes the $char character and all its presets and sections from the library $libFile. Returns whether the characters was found and removed.

int

DPK_animUI_lib_deletePresets

( string $libFile, string $char, string $presets[] )

Removes all specified $presets of the character $char from the library $libFile. Presets of other characters aren’t touched, even when they have a name that is listed in the $presets array. Only presets of the $char are removed. Returns the number of removed presets.

int

DPK_animUI_lib_deleteSections

( string $libFile, string $char, string $sections[] )

Removes all specified $sections of the character $char from the library $libFile. Sections of other characters aren’t touched, even when they have a name that is listed in the $sections array. Only sections of the $char are removed. Returns the number of removed sections.

string

DPK_animUI_lib_renamePreset

( string $libFile, string $char, string $preset, string $newName )

Renames the specified $preset of the character $char to the $newName. The name is made unique if it isn’t already. Returns the possibly changed unique name.

string

DPK_animUI_lib_renameSection

( string $libFile, string $char, string $section, string $newName )

Renames the specified $section of the character $char to the $newName. The name is made unique if it isn’t already. Returns the possibly changed unique name.

 

DPK_animUI_lib_copyToLibrary

( string $libFile, string $node, string $char, int $presetIDs[], string $preNames[] )

This procedure will copy presets from a $node with a setup for the animUI into the library ($libFile). The presets to copy are specified by their ID in the animUI setup with the $presetIDs array.

The string array $preNames should contain for each copied preset its name under which it should be stored in the library. This name is not necessarily the name of the preset in the animUI setup. If one of the names in the $preNames array already exists as preset for the $char, it is overwritten with the contents of the preset with the ID of the corresponding $presetIDs element. If the name doesn’t exist in the library, the preset is added as a new preset.

 

DPK_animUI_lib_copyToNode

( string $libFile, string $node, string $char, string $presets[], string $newNames[], int $newIDs[] )

This will copy presets from the library $libFile to the animUI setup $node. The presets to copy are specified with their $char character and their names in $presets.

The string array $newNames contains the names under which the presets will be stored. $newIDs should contain the value -1 for every preset that should become a new preset on the $node. If a preset should overwrite an existing preset, its corresponding element in $newIDs has to be the preset’s ID. When you don’t overwrite (replace) a preset by specifying its ID, you have to ensure the new name in $newNames is unique.

 

DPK_animUI_lib_copySectionsToLibrary

( string $libFile, string $node, string $char, int $sectionIDs[], string $secNames[] )

This will copy sections from the $node with a setup for the animUI into the library file $libFile. The sections to copy are specified by their ID in the animUI setup with the $sectionIDs array.

The string array $secNames should contain a name for each section. The sections will be stored under this name in the library. This name is not necessarily the name of the section in the animUI setup. If one of the names in the $secNames array already exists as section for the $char, it is overwritten with the contents of the section on the $node. If the name doesn’t exist in the library, the section is added as a new section.

 

DPK_animUI_lib_copySectionsToNode

( string $libFile, string $node, string $char, string $sections[], string $newNames[], int $newIDs[], int $add[] )

This will copy sections from the library file $libFile to the animUI setup $node. The sections to copy are specified with their $char character and their names in $sections.

The string array $newNames contains the names under which the sections will be stored. $newIDs should contain the value -1 for every section that should become a new section on the $node.

If a section should overwrite an existing section, its corresponding element in $newIDs has to be the section’s ID. There are two possibilities when overwriting an existing section. When the element in $add is false, the section’s attrs are completely replaced with the library section. In case the $add element is true, the existing attrs of the overwritten section are kept and the attrs from the library are just appended at the end.

When you don’t overwrite (replace) a section by specifying its ID, you have to ensure the new name in $newNames is unique.

Examples

// This example script will create a cube and put its transformation
// attributes into an animUI setup. We'll then create some presets.

// Initial Steps <
// Create the cube. The return will be a string array with the transform on
// index 0.
string $cube[] = `polyCube`;

// Initialize the animUI setup for the transform.
DPK_animUI_create $cube[0];


// Importing the Attrs <
// Create a section "Translate". The return of the DPK proc will be the ID of
// the new section.
int $section = `DPK_animUI_createSection $cube[0] "Translate"`;

// Import the three translate attributes into this section.
DPK_animUI_addAttrs $cube[0]
                    { ($cube[0]+".tx"), ($cube[0]+".ty"), ($cube[0]+".tz") }
                    $section;

// Create the "Rotate" section.
$section = `DPK_animUI_createSection $cube[0] "Rotate"`;

// Import the three rotate attributes.
DPK_animUI_addAttrs $cube[0]
                    { ($cube[0]+".rx"), ($cube[0]+".ry"), ($cube[0]+".rz") }
                    $section;

// Create the "Scale" section.
$section = `DPK_animUI_createSection $cube[0] "Scale"`;

// Import the three scale attributes.
DPK_animUI_addAttrs $cube[0]
                    { ($cube[0]+".sx"), ($cube[0]+".sy"), ($cube[0]+".sz") }
                    $section;


// Creating the Presets <
// The attributes are currently at their default values. Create the "Neutral"
// preset with these values.
DPK_animUI_createPreset $cube[0] "Neutral";

// Set the attributes so that the cube is stretched in mid air.
move   -a 0   0.7 0   $cube[0];
rotate -a 10  0   -20 $cube[0];
scale  -a 0.5 1   0.5 $cube[0];

// Create the "Jump" preset.
DPK_animUI_createPreset $cube[0] "Jump";

// Let the cube lie flat on the ground.
move   -a 0   0.1 0   $cube[0];
rotate -a 0   0   0   $cube[0];
scale  -a 1.5 0.2 1.5 $cube[0];

// Create the "Melt" preset.
DPK_animUI_createPreset $cube[0] "Melt";