DPK_acsDataPointTools 1.00		Sep 30, 2004


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



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

- DPK_acsDataPointTools.mel               Version: 1.00
- 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
- acsDPT_start.ma
- acsDPT_finish.ma
- readme.txt


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

This script can be used to do mathematical operations on data points of an acs
node (created with DPK_attrCombinationSystemUI.mel).

It can:
- Do various mathematical operations, including setting the values of the data
  points to a defined value, adding a defined value, multiplying, and
  randomizing among many others.
- Apply all the changes to a certain amount, called the "weight" of the
  operation. This way, you can e.g. "move" all the values by 50% towards 10.
- Work on a selection of outputs. These can be filtered using any number of
  patterns. Every output that matches any of the filters will be listed.
- Only change the non-zero values or all outputs' values.
- Operate on the relative or absolute values of the data points.
- Interact with the window of the DPK_attrCombinationSystemUI script. The
  data points that are selected in this window can be used, or all data points
  of the acs nodes that are selected in the acs list.
- Work on any number of acs nodes simultaneously.


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

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


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

- Open the scene "acsDPT_start.ma". You will see the hand example of the
  acsCopy script. The acs node has already been mirrored, but the axes are
  still wrong.

- Set the thumbCurl attribute of both hand controls to 10. The left hand
  (viewed on the right side) curls the thumb correctly, while the right hand
  does it wrong. To correct this, we're going to invert all the values for the
  Y and Z axes in all data points.

- Open the UI by executing "DPK_acsDataPointTools;".

- You should see an entry "ACSnode1_copy" in the ACS node list. Select it.

- To make sure that all settings are set to their default values, select
  "Presets->Default" from the menu.

- There is a preset that inverts the Y and Z rotation axes. To apply it,
  select "Presets->Invert->Rotate->YZ" from the menu.

- In the output list, only rotate Y and rotate Z outputs are listed. They
  should all be selected.

- Make sure the operation is set to "mult" and that v1 is set to -1. Weight
  should be 1.

- Press the "Apply" button and watch the progress.

When the script has finished, the thumb should be in the correct position. The
right hand can now be used and is fully mirrored.

Open the scene "acsDPT_finish.ma" to see the results of the above steps.


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

Even though some of them may be automatically set using presets, and some may
influence each other, there are four major steps that lead to the result:
1. Define the acs node(s) to work on
2. Define the data points to edit
3. Define the outputs which should be edited in the data points
4. Define what exactly should be done with them


- The ACS List

First things first, so we start with the acs node. At the top of the UI you
will see a list. Here, all acs nodes that exist in the scene are listed. The
script will work on all data points of the acs node(s) that are selected in
this list, unless the "Work with" option is set to "Selected Data Points".


- The "Work with" Option

When set to "All Data Points", the default, the script will work on all data
points of the selected acs node. When set to "Selected Data Points", the
script will only work on the data points that are selected in the acs window
(of the DPK_attrCombinationSystemUI script). In this case, the selection in
the acs list doesn't matter, since only the selected data points of the acs
node that is currently displayed in the acs window will be used.


- Define Outputs

In this section, the outputs that are changed are defined. When an output is
selected in the "Matching Outputs" list, its value in all data points we're
operating on will be calculated according to the operation settings. When an
output is either not listed or not selected, its value is kept and not changed
in any data point.

By default, all outputs of the used acs node(s) are listed here. This is
because we have a filter in the "Filter Patterns" list that matches all
outputs: ".*". When you change this pattern, you can control which of the
outputs are listed. By default, all listed outputs are selected. When you are
finished with editing the patterns to match the outputs you need, you might
still want to exclude some of the listed outputs from the list manually. This
can be done by simply deselecting them (ctrl-click).

You can add and remove patterns using the buttons to the right of the pattern
list. "Clear" will reset the list to the one default entry ".*".

When you select a pattern, you can edit it using the two check boxes and the
text field in the "Edit Filter Pattern" part. When "Match Output" is checked,
the pattern is tested with the name of the output that is displayed in the acs
window (the actual name could differ from the displayed name, see the acs
manual). When "Match Destination" is checked, the name of the controlled
attribute is used for the matching test. When an output matches any of the
defined patterns, it is listed in the outputs list.

For more information on what regular expression patterns are and how to use
them, see the MEL docs on the "match" command.


- Define What Should Be Done (Operate Values)

In this section of the UI, you can define the operation you want to apply to
the selected (output) values of the chosen data points. When you let the mouse
rest above one of the operations, a popup help will show what it will do. Use
the v1 and v2 fields to define the values to work with. Depending on the
chosen operation, both, one, or none of them may be active. E.g., you can't
define any additional value when you calculate the sine of an output value,
but you'd need both to control the clamping.

The weight value controls how much influence the operation should have on the
values. Using this weight, you can, for example, create slight variations
using the "rand" operation. Let's, say the values are typically in the range
from -90 to 90, you could set v1 to -100, v2 to 100, and weight to 0.01. Or
you can "Move" all values towards 1 by 50%. This would be done by using the
"set" operation, setting v1 to 1 and weight to 0.5.

You can set the weight to values above 1 and below 0 too. This way, you could
move all values away from, say, 5 by setting v1 to 5 and weight to -0.5. A
value that has been 4 would now be 3.5 and 1 would be -1.


- Other Options

The "Operate on" option specifies which values are operated on. You can either
use the relative or absolute values of the data points. Btw, this is totally
independent from the mode of the data points.

The "Change Zero Outputs" check box specifies, whether the outputs that are
not changed by the data point are changed by the operation. In the hand
example, randomizing the rotations and checking this option would result in
the pointer's tipUpDown influencing the pinky's base rotation, etc.. If you
don't want this, simply uncheck this check box. Then, only the values that are
not 0 are randomized.


- Presets

There are some presets in the "Presets" menu. The "Default" item is a special
preset. It resets the whole UI into its default state. The other presets just
change the output matching and/or operation part and can be used as a starting
point for your own settings.


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

Version 1.00
    - Initial release


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

Daniel Pook-Kolb
