Adjustment: overview
(a bit of) Theory
As previously stated, attachments do not provide a "sit target" that would allow precise positioning of the avatar (and thus their pose) with respect to the object. Therefore, repositioning a pose or animation from an attachment has been considered as "impossible".
A workaround was found : playing a secondary pose after the first one to position and rotate the avatar as desired. This works because SL animations and poses are defined through the bvh standard, as the animation of a set of "bones". During the animation, each joint (for example, a shoulder) defines its angle around the 3 axis (X, Y and Z). Any joint which does not specify a particular angle is "ignored" by the animation, and thus may be animated by an animation that was previously playing, meaning that you can effectively "cumulate" animations (walking while waving your arms in the air, for example).
To make things clear, let's just define a bit of vocabulary:
Pose
a pose is an animation in Second Life® that has been uploaded as a bvh file. Playing a pose (or animation) triggers some movements of the avatar's limbs. There is no technical difference between an "animation" and a "pose", although the latter is preferably used when there is no actual movement when the avatar has reached some position. However, poses are usually looping animations (more on that later).
Primary pose
The primary pose is a pose that you intend to play with the WearPose System. It may be a sitting, standing, lying or whatever type. The term "primary" is used to distinguish it from the adjustment pose.
Adjustment pose
The adjustment pose is a special maximum priority pose that only positions and rotates the hip part of the avatar.
To understand how adjustment poses work, let's underline that the "root" of a BVH animation is a special joint which defines the position and orientation of the whole avatar. This joint is identified with the avatar hip, and this is where we plug our adjustment pose: adjustment poses are just very simple 2-frame animations that move and rotate only the root joint.
Of course this in turn causes a few limitations:
the adjustment pose will itself override the position and orientation of the hip joint the primary pose may have defined. Therefore you will need to compensate for any orientation defined in the primary pose itself inside the adjustment pose.
This system will not work with animations (like complex dances) that move the avatar as a whole during their playing. What will happen then is that the avatar will remain "stuck" in one place. There is no easy solution to this (nothing easier than editing the primary pose or animation itself anyway).
This adjustment system is thus primarily designed to allow a positional visual adjustment of the avatar with respect to its own attachment, helping adapt the pose to various avatar shapes and sizes. When using this system, the final customer will be able, for each pose you defined in the configuration, to select an adjustment pose among those you have allowed in another special notecard.
Two modes
As explained previously, the WearPose System is made of two distinct phases (preparation and production), where two different scripts are at work (WPS-Preparation and WPS-MainScript respectively). The same is true for the adjustment procedure.
Depending on the contents of the ".adjust" notecard, adjustment for a particular pose will be one of two modes:
Standard adjustment
Standard adjustment is supported only in the preparation phase. The idea is that, using simple keyboard controls, you will be able to select one of the 50 "standard" adjustment poses that ship with the WearPose System. 50 may seem a big number but actually it's far from representing all possible combinations. They only serve as a guide to define "combined" adjustment poses to be used by the manual adjustment mode (which is the only mode for production).
Standard adjustment for a given pose is indicated in the ".adjust" notecard by mentioning the pose name alone on a line.
Manual adjustment
The manual adjustment mode is supported in both phases, preparation and production. Here the customer only gets to choose one of the adjustment poses that you, the creator, personally allowed for a particular pose.
Manual adjustment for a given pose is indicated in the ".adjust" notecard by mentioning on a line the pose name, followed by the list of allowed adjustment poses, separated by | (vertical bars).
So the idea behind those two modes is that the standard adjustment mode is used by you, the creator, to experiment and find correct position and orientation parameters that will let you define, later on, more elaborate adjustment poses to be used as manual adjustment poses.
All adjustment poses are defined as one translation along the Z axis and two angles that represent rotations around the X and Y axis. You can therefore use the "standard" adjustment mode to find out the correct values of the angles and Z-offset.
(As a side note, note that QAvimator has different labels for those axes, Y and Z are inverted. The bvh format defines other angles and offsets but they are just not relevant to our situation. These are details we need not be concerned about).
However, it was not feasible to directly support any precise combination as this would have resulted in thousands of possible adjustment poses.
Therefore, standard adjustment only supports angles of 30, 45, 60, 90, 120, 135, 150, 180, 210, 225, 240, 270, 300, 315 and 330 degrees around each of the X and Y axis, but only one of them at a time. And the Z offset can go from -10 to 10, knowing that 1 unit represents approximately 12.5 centimeters in height. More details about the standard poses can be found on this page.
Although the predefined angles are quite rough in their steps and are not mixed, they are already 30, plus the 20 Z-related poses, that makes 50 poses, which is far from enough if we want a really precise positioning. You get it, this approach is very limited.
Yet, what you are really interested as a creator is probably to be able to move the avatar only on the Z (up-down) axis. But since, as stated earlier, the adjustment pose orientation will override the primary pose orientation (of the "hip" joint), so you must recreate it to compensate. This is where manual adjustment and this website kick in.
So, how do I proceed ?
The following procedure is of course only a suggestion. Try, experiment, and find what is best for you.
These directions assume you have configured your poses in the ".menus" notecard. To enable adjustment for a specific pose, this pose must be mentioned in a new notecard, named ".adjust". We are beginning with one pose to understand principles, then we will repeat for more poses.
Equip your object with standard poses
Shipping with the WearPose System is a set of 50 standard poses (as summed up here), beginning with _rX, _rY or _Z.
Just drop all these poses into your object's inventory.
Of course, this is meant only for the preparation phase. Later, when you configure manual adjustment before switching to the running phase (WPS-MainScript), these poses may be removed - if you did not use them as manual adjustment that is.
Enable standard adjustment for a pose
To enable standard adjustment for a particular pose, its name must be mentioned in the ".adjust" notecard, alone on its line.
Create this notecard (mind the lowercase name) if it does not already exist, then drop it into your object's inventory. You can then write the ID (button name) of the pose on a line of this notecard.
If, for example, you want to enable standard adjustment for a pose named "sitting" (configured for example as "POSE sitting|my-sitting-animation" line in the ".menus" notecard) just write "sitting" on a line in your ".adjust" notecard.
Experiment!
As soon as the ".adjust" notecard is saved, the WPS-Preparation script will detect the change and will reset, reading again the ".menus", ".position" and ".adjust" notecards. When it's done you are ready to try the standard adjustment on your newly configured pose.
Select your pose in the "Use pose" menu and, in, back in the main menu, click the ">Adjust<" button. You should see a message that tells you standard adjustment has been activated and that you can use your cursor keys to select the adjustment. The keys you can use are explained in the following table.
Find your values
When a standard adjustment pose is selected, the script will tell you the name of the animation file in the inventory. When you find the correct "rot X", "rot Y" and "Z" parameters for your pose, you should write them down. Of course, they won't fit exactly what is required but they should help you anyway. First concentrate on the rotational parameters (thanks to cursor keys) to find which combination of those two angles will fit what you need. Then experiment with the Z translation (page up / down).
Create missing adjustment poses
Based on what you tried with the experiments, you should now create additional adjustment that will fit more precisely what you need for a given pose. If for example you determined that "rotX" should be between 30 and 45 and rotY should be between 90 and 120, then you can create adjustment poses whose parameters are, for exemple, rotX=42 and rotY=103. Only experience and error-and-trial will help you there.
It is likely that these two angles will remain the same for all your adjustment poses (for the same primary pose) since what you really want is a vertical translation. So you should probably spend a bit of time to try to find the correct values.
To create the adjustment pose, just fill in the form on this page : Adjustment pose generator. You will get then a bvh file downloaded on your computer, which you will have to upload to SL using appropriate parameters described on the form page.
Switch to manual adjustment and use your own adjustment pose
Once your custom adjustment pose is uploaded to SL (you did use the correct parameters, right?), you have to drop it into your object's inventory, and then edit your ".adjust" notecard.
Inside this notecard, find the line where you mentioned your primary pose name earlier. On this same line, add the name of your newly uploaded adjustment pose, separated by a vertical bar. For example :
sitting|adjustment1
If you need more adjustment poses for the same primary pose, just add them with vertical bar separators:
sitting|adjustment1|adjustment2
If one of your adjustment poses should be equal to "no adjustment", just use a dash (minus sign). For example:
sitting|adjustment1|-|adjustment3
When you save the notecard, the WPS-Preparation script will reboot.
Verify it works
On reading the ".adjust" notecard, the script will understand the adjustment mode for your primary pose ("sitting" in our example) will be manual instead of standard, and will tell you so when you click on the ">Adjust<" menu button.
In this mode, only the "page up" and "page down" keys will then be available to select the next or previous adjustment pose you listed in the notecard.
Note that in manual adjustment mode, the first adjustment pose will be the one applied at boot time, some sort of "default adjustment".
Repeat
Repeat the same procedure for every primary pose you want to be available for adjustment, adding more lines inside the .adjust notecard (one per pose).
Note that you are free to use the standard adjustment poses for manual adjustment too, if you are lucky enough that they are correct for your primary pose.
End of preparation
When you are satisfied with your settings, remove again the WPS-Preparation script and install the WPS-MainScript to switch to the production phase. If everything is OK, you should now remove unused standard adjustment poses from the object's inventory.
Note that if there still exists in your configuration a primary pose that is declared as "standard adjustment", you will get a warning and adjustment will not work on that pose: standard adjustment mode is only supported during preparation phase.
Example
The following is an example of a ".adjust" notecard.
arm at hip|Y345|Y345_Z5|Y345_Z-5
Arms crossed|-|_rY30|_rY45|_rY60|_rY90|_rY270|_rY300|_rY315|_rY330
Sit1|_Z-5|_Z-4|_Z-3|_Z-2|_Z-8|_Z-7|_Z-6
Sit2|_Z-6|_Z-5|_Z-4|_Z-3|_Z-9|_Z-8|_Z-7
Model sit
As you can see on this example (from the demo) 5 (primary) poses are allowed to have an adjustment. 4 of them (arm at hip, Arms crossed, Sit1 and Sit2) use manual adjustment while the last one (Model sit) uses standard adjustment. This is valid for the WPS-Preparation script but will trigger a configuration warning if used with the WPS-MainScript.
If we for example look at the "Sit1" animation, notice that the "_Z-5" immediately follows the first vertical bar. This means that by default, the "Sit1" animation will be played with the "_Z-5" adjustment pose. Other allowed adjustment poses for this Sit1 are _Z-4, _Z-3, _Z-2, _Z-8, _Z-7 and _Z-6. This means that you (and the final customer) can "cycle" through this list using their "page up" and "page down" keys when the adjust mode is active.
Also note that these _Z-5 (etc.) adjustment poses are actually standard adjustment poses used in manual adjustment mode, which is perfectly allowed.
On this example, the pose "arm at hip" has more "composite" adjustment poses (obtained from the Adjustment pose generator on this site) that combine a rotation around the Y axis and a translation along the Z axis. It is also worth noticing the "-" (minus sign) is used as an adjustment pose name for the primary pose "Arms crossed". This means "no adjustment".