Advanced Director Bones

Contact: Jason Weber
Last Updated: 20010928

This document briefly describes the usage of features not published in the documentation of the current Director product. You may confidently assume that these operations are not supported and there is good chance that anyone you ask about them won't know what you're talking about.

I don't neccessarily subscribe to any Director list, and it would be heavily fitered if I did. You are welcome to email me, but I don't guarantee any intelligent response. I might not have access to Director, so I'll probably have to improvise from memory.

Inverse Kinematics

This initializes an IK association from an end bone, with its effector, to some set of ancestral bones (parents and the like in the hierarchy). The id values are bone indices, the same as used in the skeletal state and the motion data. For example, to apply IK to an arm, you can provide a baseID for the shoulder and an endID for the hand.

Once IK is activated for the endbone in this manner, any motion applied to that bone, either from a motion track or manually through Lingo, is interpreted as motion to the effector instead. If the rest of the character is being animated by regular motion, it is probably best to deactive motion for the IK limb, by mapping "DefaultMotion" onto that base bone.

constraints(boneID, activeX,activeY,activeZ, limitedX,limitedY,limitedZ, minX,minY,minZ, maxX,maxY,maxZ)

Without constraints on the joint angles, the IK system will easily produce solutions that would be physically impossible without critically injuring the model. The angular limits for the specified bone (by ID) are for its motion about its parent and not for its children about itself. The three Euler angular axis are controlled independently, but be aware the Euler angles are not purely seperable like the X,Y,Z of location or scale data.

'Active' is a boolean stating whether the bone can move at all under the control of the IK system. If active, the boolean 'limited' specifies if angular limits are applied. If active and unlimited, that element of the bone rotation is allowed to assume any angle. The float values, 'min' and 'max' angles, in radians, are the limits of rotation when to associated aspect is active and limited.

The Euler angle are used in a ZYX format with a bone axis of X. This means that X rotations are applied last and represent a twisting motion about the parent's lengthwise axis.

Advanced Skinning

This usage is less flexible then the internal API allows, but provides access to skinning algorithms beyond simple transform blending of authored weights. For a more detailed explanation of these parameters, first review "Run-Time Skin Deformation".
'RegenerateWeights' is a boolean indicating if you want to throw away the authored weights and automatically generate a new set (default off).
'RemoveRogueWeights' is a boolean that finds disjoint patches of weights and reassigns them to the primary bone used by surrounding weights (default off).
'SmoothWeights' is a boolean that takes the set of weights and reduces abrupt changes in weight distribution over the surface of the mesh (default on).
'CreateBoneLinks' is a boolean that adds a curved set of miniature bones at joints that reduces artifacts otherwise common with large angular deformations (default on).
'DefaultBoneLinks' is an integer that selects the resolution of these extra bone chains (default 4).
'SmoothThreshold' is a float giving the maximum amount of weight change allowed between adjacent vertices relative the distance between the vertices and accounting for the size of the model (default 0.2).
'WeldMax' causes vertices within the given float distance to recieve exactly the same weights so the seams between mesh regions do not pull apart (default 0.001).
'ModelSize' is the general scale of the model, usually the height (default 100, centimeters presumed).

Under reasonable conditions and settings, the enhancement algorithms may take about 2 to 10 seconds to complete.

Internal API Variables

You have to give the explicit numerical index, so I'll leave it as an exercise for the reader to count down each list starting from 0. These values are used for various internal operations. Setting any variable introduces the high probablilty of a program crash or highly abnormal behavior.

To get the show modes to work, you need to do two things. First, the rendering must be set to use OpenGL. Second, you have to activate the bones debug bit (2^14) on the scenegraph. The command is something like member.debugflags=(16384).

enum BooleanProperty
	{
	// effective during run time
	ShowBones,          // display bones as wireframe
	ShowBoneNames,      // display bone name text
	ShowImplants,       // display bone implants
	ShowGrid,           // display world grid
	ShowWorldAxes,      // display axes at world origin
	ShowAxes,           // display axes on every bone
	ShowJoints,         // display joint cross-sections
	ShowCylinders,      // display cross-sections connected
	ShowConstraints,    // display IK constraint arcs
	ShowWeights,        // display weights on selected bone
	ShowAllWeights,     // display all weights with RGB blend
	ShowEffectors,      // display IK effectors
	ShowBoneLinks,      // display bone links
	ShowVertices,       // display vertex text (slow)
	ShowNormals,        // display normals as red lines with yellow
	                    // showing diff from length of 1.0
	ApplyIK,            // toggle Inverse Kinematics
	LimitAngVelocity,   // limit IK changes
	ReferenceLock,      // lock bones to reference position
	RootLock,           // lock root bone(s) to reference location
	RootClearTranslate, // remove root bone(s) translation
	RootClearRotate,    // remove root bone(s) rotation
	NoDeform,           // only compute bones, do not deform
	Renormalize,        // renormalize normals after deformation
	IKIncremental,      // apply IK incrementally
	TimerUpdate,        // sets itself when new timer data,
	                    // clears itself when read (read-only)
	MultiResLimited,    // only deform vertices under MRM limit
	AutoTranslationX,   // chained anims attach head to tail
	AutoTranslationY,
	AutoTranslationZ,
	AutoRotationX,
	AutoRotationY,
	AutoRotationZ,
	AutoScaleX,
	AutoScaleY,
	AutoScaleZ,
	AutoBlend,          // use auto blendtime vs. BlendFraction

	// only effective at load time
	LoadJustWeights,    // does not reload bones reference data
	CreateBoneLinks,    // use bone links
	RegenerateWeights,  // create new weights algorithmically
	RemoveRogueWeights, // remove spurious patches of weights
	SmoothWeights,      // smooth transitions in weights
	SmoothWeld,         // smooth close vertices collectively
	PrepareForSave,     // store info allowing bone save

	// changed per bone using IntegerProperty SelectBone
	AutoJoint,          // automatically compute joint section
	AutoLink,           // automatically compute link params
	ForTip,             // apply joint edits to bone tip vs base
	IsInfluential,      // bone is used in weight regeneration
	MaxBoolean };

enum IntegerProperty
	{
	// effective during run time
	SelectBone,         // pick specific bone by id
	NumberOfBones,      // number of bones to pick from (read-only)
	DefaultBoneLinks,   // default number of links for AutoLink
	ShowSingleMesh,     // display data for a single mesh (meshid+1)
	VertexCycle,        // only display vertex data where
	                    // vertexid%VertexCycles=VertexCycle
	VertexCycles,
	IKIterations,       // number of iteration per frame for IK

	// changed per bone using IntegerProperty SelectBone
	NumBoneLinks,       // number of links if AutoLink not set
	MaxInteger };

enum FloatProperty
	{
	// effective during run time
	Time,               // current animation time
	MinTime,            // min time of current motion (read-only)
	MaxTime,            // max time of current motion (read-only)
	BoneWidthScale,     // scaling ratio for bones display
	BoneMaxWidth,       // scaling limit for bones
	GridSize,           // size of world grid
	AxisLength,         // length of bone axis for display
	WorldAxisLength,    // length of world axis for display
	MaxAngVelocity,     // max angular velocity for IK
	BlendFraction,      // fraction from old to new mixer
	BlendStartTime,     // time which blend begins
	                    // reset by BlendToMixer()
	ReachingLimit,      // max distance of any vertex from root
	                    // (with fixed bone length and displacement)

	// only effective at load time
	ModelSize,          // approximate size of model
	SmoothThreshold,    // max delta for smoothing
	WeldMax,            // max distance to smooth collectively

	// changed per bone using IntegerProperty SelectBone
	LinkLength,         // total length of bone links
	JointCenterY,       // joint cross-section center and radials
	JointCenterZ,       // (dependent on BooleanProperty ForTip)
	JointScaleY,
	JointScaleZ,
	MaxFloat };
	

Infinite Monkeys Inc. provides this web page as a free service, but is not accountable for its content, impact, or persistance.