Wednesday, May 23, 2007

LinkRez documentation, early draft

The following is a VERY early draft of documentation for LinkRez. It will likely be split to MANY pages, and have COPIOUS screenshots. There will probably be a quick-start guide, and then a series of lessons, generating more and more complex necklaces.

This page will probably disappear, when more finalized and illustrated documentation is completed, but for now, this will give people a sense of LinkRez's complexity and power, as well as help early testers.

Besides more testing, I think I'd like to write a utility that will help people generate some standard tiny prims that are generally useful.




LinkRez

LinkRez is a tool to help position single or multi-prim "links" into a necklace chain that is shaped as closely as possible to an avatar's neck.


Features:
  • customization of necklace chain width, length in front and back, "drop" in front and back, curvature shape, and rounded vs. pointed fronts, to precisely fit avatars

  • can use necklace chain links made up of single or multiple prims

  • can use prims with unusual "center points", positional and rotational offsets

  • precise placement of links to be perfectly touching; unlike other utilities, links will NOT be "bunched up" or "spaced apart"

  • supports links that lie "flat" on the body, "alternating" chain links, "incrementing" twisting links, "random" (spinning round beads), or "constant" offset from flat-lying links

  • simple chat commands for single link-type necklaces

  • full-featured notecard-driven necklace program that support the use of an unlimited number of different link types in a necklace, with different link rotations and sizes, repeated necklace link segments


======================
Jumping right in
======================

This will let your create a few necklaces, using the included prims.
  • rez the LinkRez object on the ground
  • if a pose stand does not automatically appear, "TOUCH" the LinkRez object
    • [ ] to do: figure out why it's not rezzing automatically, on-rez

Generate a default test necklace

  • type "/1 TEST", to rez a test necklace
  • the links will be Temp-On-Rez, and will disappear after a minute or so
  • it will use default settings, which should include:
    • BEND 1.5
    • PENDANT 0.0
    • EVENLINKS
    • PATHTYPE SPLIT
    • LINKTYPE FLAT
    • LINKANGLE 20.0
  • congratulations, your first necklace!
  • notice that the links lie "flat" -- we'll change that in the next test necklace

Change to "alternating" links

  • wait for the first necklace to disappear, OR drag the clear disk a little bit to the side, so that you don't rez the 2nd necklace over the first one
  • type "/1 LINKTYPE ALTERNATE"
  • type "/1 TEST"
  • zoom in, and you'll see that each successive link "alternates" + or - 20 degrees (set by the LINKANGLE) from flat against the body

Change to "incrementing" links

  • wait for the first necklace to disappear, OR drag the clear disk a little bit to the side, so that you don't rez the 2nd necklace over the first one
  • type "/1 LINKTYPE INCREMENT"
  • type "/1 TEST"
  • zoom in, and you'll see that each successive link "twists" 20 degrees (set by the LINKANGLE) from the previous link

Custom size the necklace

  • open the edit window (under Tools menu, or press CTRL-3)
  • check the "Edit linked parts" checkbox
  • check the "Stretch Both Sides" checkbox
  • click to select the front BLUE half ellipse

  • press and hold CTRL- and SHIFT- to reveal the resizing arrows
    • drag the GREEN sizing box to change the width of the necklace guide
    • drag the RED sizing box to change the front length of the necklace guide

  • press and hold CTRL- to reveal the rotation circles
    • drag the GREEN rotation circle to change the angle of the front drop

  • type "/1 TEST"
  • notice that the new necklace size is determined by how you resized and rotated the guide ellipse
  • you can do this while properly positioned over a pose stand, to precisely fit necklaces to an avatar
  • this works with the back guide ellipse too

Change the necklace "drop" with the BEND parameter
  • type "/1 BEND 1.0"
  • type "/1 TEST"
    • notice that the necklace perfectly tracks the guide ellipse
    • notice that the connection between the front and back halves of the necklaces is a bit angular
  • type "/1 BEND 2.0" and then "/1 TEST"
    • notice that the necklace comes "off" of the guide ellipse, and that the curve over the shoulder is a bit smoother
  • you can vary the bend parameter to better fit specific avatars
  • [ ] To do: identify a good default BEND parameter

Change the "pointiness" of the necklace with the PENDANT fraction

  • the previous necklaces should have been generated with a PENDANT fraction of 0
  • type "/1 PENDANT 0.5" and then "/1 TEST"
  • notice that the front of the necklace is now pointy, better for "pendants"

In future lessons, you will try using your own links, and then use notecard programs to use multiple different types of links, within the same necklace.



======================
Using the sizing board
======================

This is absolutely critical when using weirdly shaped, twisted, tortured, and rotated prims as links, because otherwise, LinkRez has NO idea what a "flat" orientation looks like, or how "long" the link is, to space the links perfectly.

To get the sizing / offset parameters of the link you'd like to use, you simply place, rotate, and position your link precisely; make a copy of that link that is the proper distance apart; and then touch the sizing board. The sizing parameters will be chatted, and can be copied and pasted for future use.

In detail:

1) the sizing board will automatically rotate itself to ZERO_ROTATION, so that the world's red axis lines up perfectly with the sizing board's red toothpick axis
  • this will make it MUCH easier to "shift-drag" your copy of the link at step 5

2) rez the link on the sizing board

3) rotate it so that it is lying perfectly flat against the grey sizing board
  • this defines what rotation offset makes a link lie "flat"
  • rotation offset is an Euler representation of a rotation correction, using DEGREES (same as in the prim Edit window)

4) position it so that it is perfectly centered on the blue dot with the red, green, and blue toothpick axes
  • this defines where the CENTER of the link is, where rotations will act
  • position offset is a vector offset (in meters)
  • the blue dot must be at the center, meaning half your link's height should be UNDER the surface of the grey slab

5) SHIFT-CLICK-DRAG on the appropriate axis to create a copy of the link, and move it PRECISELY down the RED toothpick axis until the 2 links are JUST touching (or overlapping, if you want interdigitated links)
  • this defines the LENGTH of the link, so LinkRez will know how apart the links need to be separated
  • length is reported in MILLIMETERS (not meters), so that you can more easily edit it by hand in notecard programs
  • do NOT rotate your copied link

6) TOUCH the sizing board, and it will detect the pair of links, and CHATthe length and offsets
  • go into your chat history and copy the line NAME~LENGTH~rotOffset~posOffset
  • I'd recommend immediately pasting this into the description field of your link, so that you'll always have easy access to the information
  • note that to use this information for LinkRez, it will need to be preceeded with "LINK ", either in chat commands or notecard programs



==============
Guide ellipses
==============

LinkRez is composed of 3 linked prims:
  • large transparent disk, that defines the "plane" of the top of the necklace
  • blue half ellipse, that defines the FRONT width, length, and angle of the front of the necklace
  • purple half ellipse, that defines the BACK width, length, and angle of the front of the necklace

Make sure "EDIT LINKED PARTS" is checked off in the Edit box to:
  • move the transparent sizing plane disk forwards / backwards / up / down to "center" the necklace properly on a posing avatar
  • stretch, rotate, and position the blue and purple guide ellipses, to fit the avatar neck
  • it's OK if part of the blue front half ellipse embeds in the avatar's chest; using a larger BEND parameter will have the necklace rez further forwards



=================
Chat command list
=================

Default chat channel to use commands: /1

BEND ##
  • ## is a number greater than 1.0
  • 1.0 will have the necklace follow the guide ellipse exactly
  • the bigger ## is, the farther out from the guide ellipse the necklace will go
  • 1.3 to 1.5 seems to work OK, but I want YOU all to tell me what works for you
PENDANT ##
  • ## is a number between 0.0 and 1.0
  • 0.0 is a perfectly rounded front
  • 1.0 is a completely pointy front
LINKTYPE ##
  • ## is one of ["FLAT", "INCREMENT", "ALTERNATE", "RANDOM", "CONSTANT"]
  • FLAT against body
  • INCREMENT the angle of each successive link by LINKANGLE
  • ALTERNATE the angle of each successive link by plus or minus LINKANGLE
  • RANDOM -- spins the link randomly along the axis of the necklace
  • CONSTANT -- applies a constant angle change from the "FLAT" angle

LINKANGLE ##
  • ## is a number in DEGREES that LINKTYPE INCREMENT, ALTERNATE, and CONSTANT uses

PATHTYPE ##
  • ## is one of ["SPLIT", "FOLLOW"]
  • determines whether the links "SPLIT" from the front, or "FOLLOW" one another
  • important when the link is NOT symmetric, along various axes

EVENLINKS
  • rezzes pairs of links only
  • this is the default

ODDLINKS
  • rezzes a single front and center link, and then paired links subsequently
  • looks good with rounded fronts (low PENDANT), and terrible for pointy fronts

TEST
  • using the necklace parametersabove, rezzes a "test necklace" made up of Temp-On-Rez links, so you can more easily test how well the necklace will fit

LINK LINKNAME~LENGTH~rotOffset~posOffset
  • create a necklace made up of a SINGLE prim type, without needing to use a notecard program
  • LINKNAME is the case-sensitive name of the link to be rezzed
  • LENGTH is the length in MILLIMETERS (not meters), of each link
  • rotOffset and posOffset are OPTIONAL: if they are not included, they will be assumed to be ZERO_ROTATION and ZERO_VECTOR
  • you can get LINKNAME~LENGTH~rotOffset~posOffset from the sizing board
  • e.g., LINK oval~6 --> rezzes an entire necklace using prim "oval", treating each oval as 6 millimeters long

RUN ##
  • run an entire necklace notecard program ##

CHANNEL ##
  • changes the chat channel for commands to ##

REZLIMIT ##
  • to prevent inadvertent infinite loops of rezzing, if a rez limit is exceeded, the script stops
  • defaults to 300 links rezzed
  • you can change the limit to ##

RESET
  • resets the script and guide ellipses
  • unfortunately, will only work if the script is not currently doing anything



==========================
Notecard program command structure
==========================

  • one command per line

GUIDE FRONT~#####
GUIDE BACK~#####
  • when you run a TEST, LINK, or NOTECARD, LinkRez will chat the ellipse GUIDE parameters, which you can copy and paste into future notecard programs
  • this includes the width, front length, front angle, back length, back angle information
  • this lets you set the size / position of the guide ellipses for future necklaces
  • I'd recommend including a comment, like "// sized for XYZ" or "// default avatar", so you know who the GUIDE fits well for

BEND, PENDANT, EVENLINKS, ODDLINKS
  • any of these commands can be included in a notecard program, BEFORE the first link is rezzed

LINKTYPE, LINKANGLE, PATHTYPE
  • any of these commands can be used anywhere in a notecard program

LINK LINKNAME~LENGTH~rotOffset~posOffset
  • rezzes that link, using the current linktype / linkangle / pathtype parameters
  • like above, rotOffset and posOffset are optional


REPEAT ##
...
...
...
ENDREPEAT
- repeats all the commands between REPEAT ## and ENDREPEAT, a total of ## times



REPEATUNTIL ##
...
...
...
ENDREPEAT

  • repeats all the commands between REPEAT ## and ENDREPEAT, UNTIL the links have been rezzed to ## DEGREES
  • 0 degrees is the front of the necklace; 90 degrees is the side; 180 degrees is the back
  • so REPEATUNTIL 90 ... ENDREPEAT will rezz links all the way up to the "side", before progressing with the rest of the notecard program

When the end of the notecard has been reached, LinkRez will continue rezzing the LAST link rezzed, with the current LINKTYPE settings, until it reaches the back of the necklace.


The simplest notecard program would consist of a single line with a LINK command:
- e.g., LINK oval~6
- would rez an entire necklace using prim "oval", treating each oval as 6 millimeters long


Tips:
  • all text on a line after a "/" is considered a comment and will be ignored; helpful to leave notes to yourself
  • "~" is frequently used as a delimiter (like for the LINK sizing board output), and shouldn't be used
  • blank lines will be ignored
  • be careful about extra spaces; they'll probably cause problems




================================
Tips on custom-fitting necklaces
================================

3 prim parts:
  • "root plane": transparent disk, controls the overall position of the necklace chain; can be tilted
  • "front blue guide ellipse": controls width, front half length and angle
  • "back purple guide ellipse": controls width, back half length and angle
2 parameters set by chat commands
  • /1 BEND ##: how much the necklace curves AWAY from the guide ellipse, to allow a rounded, over-the-shoulder drape
    • 1.0 (tracks guide ellipse perfectly); larger values come away from the guide ellipse further; try 1.3 to 2.0
  • /1 PENDANT ##
    • from 0.0 to 1.0, how pointy the front of the necklace will be

Pose avatar on posestand

Position the "root plane" to "center" the necklace chain properly
  • right-click the "root plane" and select edit (shouldn't matter if Edit Linked Parts is on or off)
  • move to the correct height, at the very top of the shoulders
  • move to centered, with respect to left and right
  • move forward and back, so that "break" between the ellipse front and back halves is at the very top of the shoulders
  • perhaps JUST in front of the tops of the shoulders works better; NEED TO TEST THIS MORE
NOW, make sure the Edit window is open, and that:
  • "Edit Linked Parts" is CHECKED
  • "Stretch Both Sides" is CHECKED

Stretch and position the "front half ellipse"
  • STRETCH (ALT-SHIFT) the width to the desired width
  • STRETCH (ALT-SHIFT) the front tab to the desired length
  • ROTATE (ALT) so that the VERY front of the ellipse just emerges from the avatars body
  • it's OK if parts of the ellipse are embedded in the avatar body
  • modifying the BEND parameter will change how much the chain comes "forward" from the plane of the half ellipse

Stretch position the "back half ellipse"
  • ROTATE (ALT) to the desired angle
  • STRETCH (ALT-SHIFT) the back tab so that the VERY back of the ellipse just hugs the back of the neck

Check how the necklace chain will look by using the "/1 TEST" command
  • rezzes a necklace chain, using Temp On Rez prims that will disappear after a minute or so
Adjust as needed

When it fits to your satisfaction:
  • issue the "/1 LINK primName~length" command, to create a necklace with just one type of link

    OR

  • issue the "/1 RUN notecardName", to execute a notecard program


==========
Other tips
==========

  • for a rounded front, choose a PendantFraction of 0.0

  • for a pointed front, choose a PendantFraction from 0.25 to 0.75 (maximum 1.0)

  • a bend parameter from around 1.3 to 1.5 seems to work well; NEED TO TEST THIS MORE

  • if the necklace is embedded in the avatars body, you can:
    • use a higher bend parameter
    • move the entire "root plane" forwards a little bit (and then readjusting the front and back half ellipses)

  • if the necklace comes "off" the avatar's torso too far, you can:
    • use a lower bend parameter
    • move the entire "root plane" back a little bit (and then readjusting the front and back half ellipses)

  • if you want the "top" of the necklace to be more rounded (less angular from front half to back half), use a higher bend parameter
    • because this will make the necklace come "out" away from the guide ellipse more, you may need to move the guide ellipses BACK a little bit

  • once you have settings that fit an avatar perfectly, SAVE them for re-use in future necklace chains
    • copy the settings from the CHAT HISTORY



==============
Other Ideas
==============

  • in general (especially with a pointed pendant front), you'll want an even number of necklace chain links
  • you can also specify that there be a single front link, for a total ODD number of necklace chain links
  • even better fits MIGHT be achievable by tilting the root plane forwards and backwards; NEED TO TEST MORE