DPK_acsCopy 1.01		Dec 10, 2005


---------
Contents:
---------
1. Files Included
2. Overview
3. Installation
4. Quick Start
5. Manual
6. History
---------



-----------------
1. Files Included

- DPK_acsCopy.mel                         Version: 1.01
- DPK_arrayTools.mel                      Version: 0.14
- DPK_attrCombinationSystemUI.mel         Version: 1.03
- DPK_findInAllNamespaces.mel             Version: 1.0.0
- DPK_getArgs.mel                         Version: 0.051
- DPK_multiDimArray.mel                   Version: 0.08
- DPK_rigLongName.mel                     Version: 1.00
- DPK_rigShortName.mel                    Version: 1.00
- DPK_simpleListUI.mel                    Version: 0.02
- acsCopy_start.ma
- acsCopy_finish.ma
- readme.txt


-----------
2. Overview

This script is used to mirror an existing acs (created using the
DPK_attrCombinationSystemUI.mel script) from one side of a character to
another. It is written in a flexible way, allowing it to be used for other
purposes, too. E.g., you can copy an acs from one character to another.

The way this is done is by defining so called 'patterns' and 'replacement
strings' which tell the script where to find the controlling and controlled
(inputs and outputs) attributes of the other side (or character). By default,
the names of the inputs and outputs starting with an "l_" are converted into
names starting with an "r_".

The script can create a copy of an existing acs node and:
- Copy the inputs and/or outputs of a selected acs
- Copy the data points of the selected acs

Copying inputs and outputs is done by finding matching objects after the
customizable name conversion. When a matching object for an input could not be
found, the same attribute that is used for the original acs' input can
optionally be used for the copied acs.


---------------
3. Installation

Copy the ".mel" file(s) into your scripts directory (e.g.: ../maya/scripts).


--------------
4. Quick Start

- Open the scene "acsCopy_start.ma". You should see two hands as children of
  one root joint. There are also two hand control objects (the two curves).
  You might already know them from the acs tutorial scenes. The left hand (on
  the right side of the view) is set up using an acs node. You can try out the
  attributes on the l_handCtrl and the different finger controls. They should
  all work like in the finished acs tutorial scene. The right hand has no
  setup and thus can't be used at the moment. This is what we're going to
  change now.

- Select the acs node "ACSnode1".

- Execute the script "DPK_acsCopy;". A window will open and the acs node will
  be selected. If not, select the acs node. The top three text fields should
  all contain the string "^l_" and the bottom three the string "r_".

- To make sure the default settings are used, select "Edit->Reset Settings"
  from the menu.

- Press the "Copy/Mirror" button and watch the progress.

You should now see a node "ACSnode1_copy" in the outliner. It uses the inputs
of the right hand control and controls the joints of the right hand. Try the
control attributes on the right hand control to see that the data points have
been copied.

Don't be surprised to see that the joints rotate in the wrong direction. This
is because the mirrored joints have different rotation directions than the
original ones. It is not a problem of the acs or this script. To correct this,
simply invert one or two axes using the "DPK_acsDataPointTools" script. Which
axes have to be inverted depends on the skeleton. In this case it is the Y and
Z axis.

The scene "acsCopy_finish.ma" contains the result of the above steps (plus the
inversion of the Y and Z axes).


---------
5. Manual

This is a pretty simple script. You shouldn't need long to understand how to
make full use of it. Below is a list of the UI elements with little
descriptions of what they do.


- The Edit Menu

This menu contains just the "Reset Settings" item. This will reset the check
boxes and text fields to their default settings.


- The ACS List

There is a list in the upper left part of the UI that displays all acs nodes
in the current scene. The nodes that are selected in this list will be
mirrored.


- Copy Inputs

If this check box is checked, the inputs of the selected acs node(s) will be
copied to the new acs node(s). The names are converted using the pattern
strings (see below).


- Copy Outputs

If checked, the outputs of the selected acs node(s) will be copied to the new
acs node(s). Like with the inputs, the names are converted using the patterns
(see below).


- Copy Data Points

If checked and both, inputs and outputs are copied, the data points of the
selected acs node(s) will be copied to the new acs node(s). In case an input
couldn't be copied (when no match was found and the "Use same input..." check
box is not checked), the data points that use positions of this input can't be
copied. When an output couldn't be copied, it will simply get no value in the
copied data points.


- Use same input when no match

When this option is checked and the script can't find a matching input, the
same attribute that feeds into the input of the original acs node is used and
imported into the new acs node. This way, both acs nodes will be controlled by
the same input attribute.


- Match Patterns and Replacement Strings

These patterns are used to find the corresponding input/output on "the other
side" of the character. Let's say we have a left hand that is completely set
up using the acs, like in the example scene. When all the joints (which are
outputs of the acs) and all the control objects (which are the inputs) have
names starting with an "l_", and the joints and controls of the right hand
have names starting with an "r_", you can simply define a match pattern of
"^l_" and a replacement of "r_" to convert the input and output names. This
way, the script can find the nodes on the other side of the character. When
you want to copy an acs from one character to another, simply make sure the
other character has a differently named parent node (which is usually the
case) and set the patterns and replacement strings appropriately.


- Convert Node Names

This pattern and replacement string is used to convert the names of the nodes
that have the input and output attributes. Only the nodes' names are used by
this pattern, the parent names or attribute names are not changed here.


- Convert Attr Names

This pattern and replacement string is used to convert the names of the
attributes that are inputs or outputs. The match pattern is applied to each
part of the attribute string separately. This means that the attribute name
"attrL[0].childL" is not converted in one go. Instead, the pattern is applied
to the "attrL" and "childL" part independently. Note that the index part has
been left out for the matching. So a pattern of "L$" with a replacement of "R"
would result in the converted attribute name "attrR[0].childR".


- Convert Parent Names

When (and only when) the node's name is not unique in the scene, the node gets
a prefix consisting of its path (i.e. its parents). Not all parents up to the
world are used, only as many as needed to make the name unique. The pattern
and replacement will be used on each of these parents independently. This
section is especially useful when copying from one character to another. But
even in the example scene this pattern is used, since the individual finger
objects have non-unique names.


----------
6. History

Version 1.01
    - Minor bug fix with handling missing output counterparts


Version 1.00
    - Initial release


--------------
If you have any comments or suggestions, please email me at:
daniel@dpk.stargrav.com

Daniel Pook-Kolb
