//----------------------------------------------------------------------------------------------
//
//	AUTHOR:		Ingo Clemens
//	DATE:		Dez 01, 2007
//			created: Nov 20, 2004
//
//	DESCRIPTION:	Advanced character rigging tool with various options to setup
//			a character based on a given skeleton.
//			See the PDF documentation for a complete description of the
//			features and implementations.
//
//
//----------------------------------------------------------------------------------------------
//
//	KNOWN ISSUES:	- It is not advised to UNDO the mirroring or reversing of the pose.
//			Doing this the constraints of the hand will no longer work
//			correctly and the hand appears to be broken.
//
//----------------------------------------------------------------------------------------------
//
//
//	VERSIONS:
//			2.1 - Dez 01, 2007
//			- removed all display layers and switched them to sets; this cleans up the
//				display layer editor a lot which is an improvement in complex scenes;
//				only the loResGeometry layer remains in the layer editor
//			- added two more shelf buttons to toggle the visibility and the display status
//				for the new sets
//			2.0 - Sep 01, 2007
//			- adjusted the head control and foot control rotation order to a better
//				default setting
//			- eliminated the selectability of the arm and leg twist joints
//			- better filtering of the joints in the "Assign LoRes Geometry Names"-Folder
//			- fixed an issue with FK hand z-rotations not being zero after rigging in
//				some occasions (depending on the joint setup)
//			- added the functionality to be able to blend between the two head/neck
//				follow states which had just a switching function prior this fix
//			- fixed a problem with the head rotation being in follow mode when the
//				body would be turned to the side due to an orientation issue
//			- moved the pivot of the torso control down to the pelvis as this allows
//				for a better rotation when bending the character down
//			- reworked the building of the FK joints in the spine from a motion path
//				setup to a simpler one using the pointOnCurve command
//			- the spine setup is undoable now due to the new spine creation procedure
//			- when bending the character with the back control the upper body is more
//				rigid due to the rib cage and the bending comes more from the
//				abdomen area
//			- added a breathing functionality on the upper body which encompasses the
//				only expression in the rig
//			- rearranged the script location, keeping all character rigger scripts in
//				one place
//			- removed all character rigger icons to a subfolder for transparency
//			- removed the progress bar due to a very slow refresh on OS X which slowed
//				down the reading and storing significially
//			- added a button to get the name of a selected clip/pose in the list for
//				overwriting or renaming purposes
//			- made the current auto prefix function only available when having the
//				current character set option selected
//			- fixed an issue with the current maya version (8.5) where an option is
//				available which assigns new objects to the current layer
//				(editDisplayLayerGlobals). This causes errors in the script and is
//				automatically switched off upon opening the character rigger window
//			- created a new set of icons for the tool
//			- included the orient joint tool and the recall world position tool in the
//				rigging scripts
//			- added the breathing attributes to the ignore list of the body controls as
//					these don't mirror during the reversing of the pose
//
//
//			1.6.5 - Mar 16, 2007
//			- fixed a mirror and reverse pose issue with the shoulder control which has
//				been redesigned to rotate rather than translate
//			- fixed a problem reading back in animations with the option "current frame"
//				as this inserted the keyframes one frame too early
//			- when stretching the arms and legs the upper arm and upper leg got
//				stretched too much; removed the stretching from the twist joints
//			1.6.4 - Mar 11, 2007
//			- due to the setup of the forearm twist the right hand joint had a default
//				Z-rotation value of 1. The problem was based on a reverse node
//				and has been corrected with a multiply node
//			1.6.3 - Mar 05, 2007
//			- fixed a minor issue, where three joint fingers would not be rigged
//				appropriately; also changed the UI so that switching between
//				finger joint counts also changes the field labels
//			1.6.2 - Feb 02, 2007
//			- added additional twists for the upper arm and the upper leg for
//				better distributing skin deformations
//			- cleaned the list for renaming lowRes geometry from unnecessary entries
//			- the shoulder control is now controlled by rotations and not through
//				translations anymore
//			- fixed a shoulder problem where the shoulder didn't move with the upper
//				body rotations; the shoulder now stays inline with the body
//			1.6.1 - Jan 18, 2007
//			ONLY CHANGES TO THE POSE MIRRORING AND REVERSING WERE MADE
//			- removed the headNeckFollow Attribute from mirroring, which created an
//				error
//			- fixed a bug with the auto shoulder and the individual shoulder control
//				while reversing the pose
//			- the torso control is mirrored correctly now
//			- additional fixes include that the torso and main control can now be
//				rotated with the pose reversing correctly
//			1.6 - Dez 18, 2006
//			- implemented stretchable arms and legs
//			- added a forearm twist with additional joints; radius and ulna joints
//				are kept but not as skinning joints; the loRes geometry can
//				now be parented to the new joints to help visualize the arm
//				twist
//			- reversing poses didn't work properly with the new forearm twist -
//				fixed!
//			- fixed a bug with pose reversing after changing the lower arm twist
//				function; the original lower arm joint is not a skin joint
//				anymore and got not mirrored correctly
//			- fixed a tiny error where the leg stretch locators were not grouped
//				correctly
//			1.5 - Nov 08, 2006
//			- fixed an incompatibility with Maya 7 on OSX regarding not fully
//				specified ik handle types
//			- fixed hand mirroring problems since the new rigging concept of the
//				hand control
//			- mirroring now also works with rotated characters and mirrors across
//				the characters center
//			- fixed some minor issues with namespaces
//			- fixed some minor bugs where some foot control attributes where not
//				mirrored correctly
//			- mirroring now also automaticially switches IK/FK states, but only if
//				the chain to modify is not currently in a transition between IK
//				and FK
//			- added a new feature called "reverse pose" which fully reverses the
//				current character pose to easily animate walk cycles
//			- the active character set will now be cleared when executing the switch
//				character set function with nothing selected
//			- renamed the character set for the main control from "main" to
//				"placement" for better recognizing
//			- renamed the foot control attribute "Heel Pivot Side" to "Heel Pivot
//				Twist" to match the other attribute names
//				NOTE: THIS CAN CAUSE ISSUES WITH EXISTING CHARACTER POSES AND
//					ANIMATIONS AS THESE REFER TO THE OLD ATTRIBUTE NAME!
//					THIS IS USUALLY NOT A PROBLEM AS THIS ATTRIBUTE IS NOT
//					VERY COMMONLY USED!
//			- modified the head setup so that the head control influences both the
//				head joint and neck joint rotation; the neck control is now
//				used to adjust the neck orientation for finer control
//				- subfix: neck joint geo didn't follow the neck rotation
//					correctly; altered the setup with additional joints
//					that work as substitute parents for the neck geometry
//			- when entering a short name manually in the store tool it can store any
//				animation from properly named nodes organized in character sets;
//				all participating nodes and character sets need the short name
//				extension
//			- finally worked on the UI appearance on OSX systems and made the script
//				compatible with both windows and osx; a script detects the
//				running system and choses the right layout
//				NOTE: THE OS IS STORED IN THE ENVIRONMENT VARIBLE
//					"icCharRigRunningOS". TO INVOKE A NEW CHECK REMOVE THE
//					VARIABLE WITH "optionVar -rm icCharRigRunningOS"
//
//			1.4.3 - Aug 24, 2006
//			- added the feature to store only the current time range
//			- added the feature to discard the main control when reading back in data
//			- added the feature to restore at the original frames or from the
//				current frame
//			- added a progress bar for reading in poses and animations to give the
//				user more feedback
//			- added an option to place the upper body control either at pelvis or
//				shoulder depth depending on the character pose to center the
//				control around the given geometry
//			- fixed that the character placement scale got not stored in the
//				character definition node
//			- when storing poses character sets without subcharacter sets would not
//				get processed correctly - fixed!
//			1.4.2 - Jul 17, 2006
//			- fixed the arm setup so that the elbow control directly lies on the
//				arm solver plane; creating an up vector constraint doesn't move
//				the elbow anymore; this also creates an better up vector for
//				the hand orientation during the setup
//			- fixed a problem occuring in maya 7: when setting a key on the leg
//				character sets an error came up, because all leg ik handles had
//				connections to the character set; this is not necessary when
//				connecting all ik blend attributes via ConnectNodeToIKFK
//			- cancelling the overwriting of an existing store file replaced the
//				original file - fixed!
//			- storing the pose of the current character set with an existing file
//				name didn't bring up the confirm overwrite window - fixed!
//			- fixed some procedures to correctly read the characters short name;
//				names with less than 4 characters had not been read correctly
//			- fixed a bug with reading poses, where an FK related pose wouldn't
//				be restored correctly
//			- the Character Rigger Store UI gets the character name automatically,
//				if a character control is selected upon window creation
//			- animations can now be read and inserted at the current time; the time
//				base option in the UI defines where the insertion point is based
//				on the original animation
//			- writing out poses and animations now also ignores constraint
//				connections that have been added after the rigging process
//			1.4.1 - Jul 06, 2006
//			- added an additional roll attribute to each finger for better control
//			1.4 - May 04, 2006
//			- revised arm setup:
//				- simplified the hand rotation by redesigning the entire hand
//				  setup and putting the rotation attributes on the hand control
//				- added a new script for toggling between ik and fk independed
//				  from the selected control or joint and without having to use
//				  the function in the maya animation menu
//
//
//			1.3.8 - Mar 29, 2006
//			- fixed related problems to version 1.3.7, such as:
//				- namespaces don't appear in the pose/animation files anymore
//				  to be able to apply them to any character
//				- added an additional namespace field in the UI to show the
//				  current namespace of the selected character
//				- made the namespace possible to contain underscores
//				- referenced characters with any namespace will now work
//			- made the mirroring of poses work on characters with namespaces
//			1.3.7 - Mar 12, 2006
//			- fixed a problem with loading/storing poses, where referenced characters
//				wouldn't read poses/animations because of the wrong delimiter
//				in the pose/animation file
//			1.3.6 - Feb 13, 2006
//			- fixed an issue with loading a pose/animation to a character that has
//				a different joint count as the source character
//			1.3.5 - Nov 05, 2005
//			- fixed a problem where even correctly positioned arms would cause an
//				error telling the user that the rotations would not be zero
//			- fixed a mistake with the character store UI; even folder names got
//				listed
//			- fixed the setup script to discontinue if the shelf tab field is left
//				blank
//			1.3.4 - Oct 18, 2005
//			- added a tool to easily select the character set or subcharacter set
//				based on the selected control
//			1.3.3 - Oct 14, 2005
//			- fixed the accidential hiding of the torso control channels that
//				happened during the 1.3.1 update
//			1.3.2 - Oct 11, 2005
//			- added the ik blending of the ik handles to the character sets for a
//				better management of timing the animation; the ik blend keys
//				appear now along with the other keys
//			1.3.1 - Sep 27, 2005
//			- additional cleanup for spine cluster handles that had visible channels
//			1.3 - Jun 29, 2005
//			- added a tool for loading/saving poses and animations
//			- added a toolset to mirror poses from one side to the other
//			- redesigned the wrist lock mode vom v1.2.6; the wrist lock attribute
//				now blends between wrist rotation and hand turn attributes
//			- fixed the finger control; the fingers now rotate the same direction
//				when both controls are selected and common attributes are used
//				to create mirrored poses
//			- added a thumb roll attribute for finer thumb control
//			- added two progress windows; for opening the UI and for creating the
//				complete character
//			1.2.6 - Jun 13, 2005
//			- corrected the rotation of the hand in wrist lock mode; the rotation is
//				now more predictable through another attribute (hand turn) which
//				works only in wrist lock mode
//			1.2.5 - Jun 12, 2005
//			- corrected some inconvenience with the wrist rotations in fk mode; after
//				rotating the lower arm with the wrist rotate attribute the wrist
//				control now shows more appropriate rotations
//			- some minor cleanup changes
//			1.2.4 - Jun 09, 2005
//			- fixed the pickwalking switch that would not reset to default pickwalking
//			- corrected the right wrist rotation to match the positive/negative value
//				of the left side
//			- applied pickwalking for fk joints/controls between both sides of the
//				character
//			1.2.3 - Jun 03, 2005
//			- changed the rotational behavior of the hand and wrist; the hand
//				rotation axes were left in the default position after the wrist
//				have been rotated
//			- fixed a script error when using the pickwalk toggle (wrong use
//				of the environment variable)
//			1.2.2 - Jun 01, 2005
//			- fixed a bug, where some lores geometry would not attach properly
//			1.2.1 - May 22, 2005
//			- removed all global variables for better integration
//			- NOTE: an environment variable is used to temporarily store the joints;
//				the variables name is "icCharRigCollectChainJoints"; the variable
//				is queried upon script execution to see wether there is a name
//				conflict with an existing variable
//
//			1.2 - Apr 22, 2005
//			- fixed a bug where the head/neck follow would not work correctly
//				in an animation situation
//
//			1.1 - Feb 20, 2005
//			- added the feature to append custom extensions to the character
//			- define character locator is now compatible with newer versions
//				(get character function can ask for attributes that the
//				character locator doesnt carry due to version changes)
//
//			1.0 - Jan 16, 2005
//			- hopefully first bugfree version; testing follows
//
//			0.12 - Jan 15, 2005
//			- various bugfixes and feature improvements
//
//			0.01 - Jan 02, 2005
//
//----------------------------------------------------------------------------------------------