| |
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.
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.
| Return | Procedure Name | Argument(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. |
| Return | Procedure Name | Argument(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:
When we want the left-right pair and the attr is a bilateral bcs weight:
When we want the top-bottom pair and both attrs are bilateral bcs weights:
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. |
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.
| Return | Procedure Name | Argument(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. |
<
string $cube[] = `polyCube`;
DPK_animUI_create $cube[0];
<
int $section = `DPK_animUI_createSection $cube[0] "Translate"`;
DPK_animUI_addAttrs $cube[0]
{ ($cube[0]+".tx"), ($cube[0]+".ty"), ($cube[0]+".tz") }
$section;
$section = `DPK_animUI_createSection $cube[0] "Rotate"`;
DPK_animUI_addAttrs $cube[0]
{ ($cube[0]+".rx"), ($cube[0]+".ry"), ($cube[0]+".rz") }
$section;
$section = `DPK_animUI_createSection $cube[0] "Scale"`;
DPK_animUI_addAttrs $cube[0]
{ ($cube[0]+".sx"), ($cube[0]+".sy"), ($cube[0]+".sz") }
$section;
<
DPK_animUI_createPreset $cube[0] "Neutral";
move -a 0 0.7 0 $cube[0];
rotate -a 10 0 -20 $cube[0];
scale -a 0.5 1 0.5 $cube[0];
DPK_animUI_createPreset $cube[0] "Jump";
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];
DPK_animUI_createPreset $cube[0] "Melt";
| |