diff --git a/libraries/animation/src/AnimInverseKinematics.h b/libraries/animation/src/AnimInverseKinematics.h index 0136b7d125..d5a110ea76 100644 --- a/libraries/animation/src/AnimInverseKinematics.h +++ b/libraries/animation/src/AnimInverseKinematics.h @@ -59,6 +59,47 @@ public: float getMaxErrorOnLastSolve() { return _maxErrorOnLastSolve; } + /**jsdoc + *
Specifies the initial conditions of the IK solver.
+ *Value | Name | Description | + *
---|---|---|
0 | RelaxToUnderPoses | This is a blend between PreviousSolution and
+ * UnderPoses : it is 15/16 PreviousSolution and 1/16 UnderPoses . This
+ * provides some of the benefits of using UnderPoses so that the underlying animation is still visible,
+ * while at the same time converging faster then using the UnderPoses only initial solution. |
1 | RelaxToLimitCenterPoses | This is a blend between
+ * Previous Solution and LimitCenterPoses : it is 15/16 PreviousSolution and
+ * 1/16 LimitCenterPoses . This should converge quickly because it is close to the previous solution, but
+ * still provides the benefits of avoiding limb locking. |
2 | PreviousSolution | The IK system will begin to solve from the same position and
+ * orientations for each joint that was the result from the previous frame. + * Pros: because the end effectors typically do not move much from frame to frame, this is likely to converge quickly + * to a valid solution. + * Cons: If the previous solution resulted in an awkward or uncomfortable posture, the next frame will also be + * awkward and uncomfortable. It can also result in locked elbows and knees. |
3 | UnderPoses | The IK occurs at one of the top-most layers, it has access to the + * full posture that was computed via canned animations and blends. We call this animated set of poses the "under + * pose". The under poses are what would be visible if IK was completely disabled. Using the under poses as the + * initial conditions of the CCD solve will cause some of the animated motion to be blended in to the result of the + * IK. This can result in very natural results, especially if there are only a few IK targets enabled. On the other + * hand, because the under poses might be quite far from the desired end effector, it can converge slowly in some + * cases, causing it to never reach the IK target in the allotted number of iterations. Also, in situations where all + * of the IK targets are being controlled by external sensors, sometimes starting from the under poses can cause + * awkward motions from the underlying animations to leak into the IK result. |
4 | LimitCenterPoses | This pose is taken to be the center of all the joint
+ * constraints. This can prevent the IK solution from getting locked or stuck at a particular constraint. For
+ * example, if the arm is pointing straight outward from the body, as the end effector moves towards the body, at
+ * some point the elbow should bend to accommodate. However, because the CCD solver is stuck at a local maximum, it
+ * will not rotate the elbow, unless the initial conditions already has the elbow bent, which is the case for
+ * LimitCenterPoses . When all the IK targets are enabled, this result will provide a consistent starting
+ * point for each IK solve, hopefully resulting in a consistent, natural result. |
Specifies sets of joints.
+ *Value | Name | Description | + *
---|---|---|
0 | FullBodyBoneSet | All joints. |
1 | UpperBodyBoneSet | Only the "Spine" joint and its children. |
2 | LowerBodyBoneSet | Only the leg joints and their children. |
3 | LeftArmBoneSet | Joints that are children of the "LeftShoulder" joint. |
4 | RightArmBoneSet | Joints that are children of the "RightShoulder" + * joint. |
5 | AboveTheHeadBoneSet | Joints that are children of the "Head" joint. |
6 | BelowTheHeadBoneSet | Joints that are NOT children of the "head" + * joint. |
7 | HeadOnlyBoneSet | The "Head" joint. |
8 | SpineOnlyBoneSet | The "Spine" joint. |
9 | EmptyBoneSet | No joints. |
10 | LeftHandBoneSet | joints that are children of the "LeftHand" joint. |
11 | RightHandBoneSet | Joints that are children of the "RightHand" joint. |
12 | HipsOnlyBoneSet | The "Hips" joint. |
13 | BothFeetBoneSet | The "LeftFoot" and "RightFoot" joints. |
An IK target type.
+ *Value | Name | Description | + *
---|---|---|
0 | RotationAndPosition | Attempt to reach the rotation and position end + * effector. |
1 | RotationOnly | Attempt to reach the end effector rotation only. |
2 | HmdHead | Deprecated: A special mode of IK that would attempt + * to prevent unnecessary bending of the spine. |
3 | HipsRelativeRotationAndPosition | Attempt to reach a rotation and position end + * effector that is not in absolute rig coordinates but is offset by the avatar hips translation. |
4 | Spline | Use a cubic Hermite spline to model the human spine. This prevents + * kinks in the spine and allows for a small amount of stretch and squash. |
5 | Unknown | IK is disabled. |
An AnimStateDictionary
object may have the following properties. It may also have other properties, set by
+ * scripts.
Name | Type | Description | + *
---|---|---|
userAnimNone | boolean | true when no user overrideAnimation is
+ * playing. |
userAnimA | boolean | true when a user overrideAnimation is
+ * playing. |
userAnimB | boolean | true when a user overrideAnimation is
+ * playing. |
sine | number | Oscillating sine wave. |
moveForwardSpeed | number | Controls the blend between the various forward walking + * & running animations. |
moveBackwardSpeed | number | Controls the blend between the various backward walking + * & running animations. |
moveLateralSpeed | number | Controls the blend between the various sidestep walking + * & running animations. |
isMovingForward | boolean | true if the avatar is moving
+ * forward. |
isMovingBackward | boolean | true if the avatar is moving
+ * backward. |
isMovingRight | boolean | true if the avatar is moving to the
+ * right. |
isMovingLeft | boolean | true if the avatar is moving to the
+ * left. |
isMovingRightHmd | boolean | true if the avatar is moving to the right
+ * while the user is in HMD mode. |
isMovingLeftHmd | boolean | true if the avatar is moving to the left while
+ * the user is in HMD mode. |
isNotMoving | boolean | true if the avatar is stationary. |
isTurningRight | boolean | true if the avatar is turning
+ * clockwise. |
isTurningLeft | boolean | true if the avatar is turning
+ * counter-clockwise. |
isNotTurning | boolean | true if the avatar is not turning. |
isFlying | boolean | true if the avatar is flying. |
isNotFlying | boolean | true if the avatar is not flying. |
isTakeoffStand | boolean | true if the avatar is about to execute a
+ * standing jump. |
isTakeoffRun | boolean | true if the avatar is about to execute a running
+ * jump. |
isNotTakeoff | boolean | true if the avatar is not jumping. |
isInAirStand | boolean | true if the avatar is in the air after a standing
+ * jump. |
isInAirRun | boolean | true if the avatar is in the air after a running
+ * jump. |
isNotInAir | boolean | true if the avatar on the ground. |
inAirAlpha | number | Used to interpolate between the up, apex, and down in-air + * animations. |
ikOverlayAlpha | number | The blend between upper body and spline IK versus the + * underlying animation |
headPosition | {@link Vec3} | The desired position of the Head joint in
+ * rig coordinates. |
headRotation | {@link Quat} | The desired orientation of the Head joint in
+ * rig coordinates. |
headType | {@link MyAvatar.IKTargetType|IKTargetType} | The type of IK used for the + * head. |
headWeight | number | How strongly the head chain blends with the other IK + * chains. |
leftHandPosition | {@link Vec3} | The desired position of the LeftHand
+ * joint in rig coordinates. |
leftHandRotation | {@link Quat} | The desired orientation of the LeftHand
+ * joint in rig coordinates. |
leftHandType | {@link MyAvatar.IKTargetType|IKTargetType} | The type of IK used for the + * left arm. |
leftHandPoleVectorEnabled | boolean | When true , the elbow angle is
+ * controlled by the rightHandPoleVector property value. Otherwise the elbow direction comes from the
+ * underlying animation. |
leftHandPoleReferenceVector | {@link Vec3} | The direction of the elbow in the local + * coordinate system of the elbow. |
leftHandPoleVector | {@link Vec3} | The direction the elbow should point in rig + * coordinates. |
rightHandPosition | {@link Vec3} | The desired position of the RightHand
+ * joint in rig coordinates. |
rightHandRotation | {@link Quat} | The desired orientation of the
+ * RightHand joint in rig coordinates. |
rightHandType | {@link MyAvatar.IKTargetType|IKTargetType} | The type of IK used for + * the right arm. |
rightHandPoleVectorEnabled | boolean | When true , the elbow angle is
+ * controlled by the rightHandPoleVector property value. Otherwise the elbow direction comes from the
+ * underlying animation. |
rightHandPoleReferenceVector | {@link Vec3} | The direction of the elbow in the local + * coordinate system of the elbow. |
rightHandPoleVector | {@link Vec3} | The direction the elbow should point in rig + * coordinates. |
leftFootIKEnabled | boolean | true if IK is enabled for the left
+ * foot. |
rightFootIKEnabled | boolean | true if IK is enabled for the right
+ * foot. |
leftFootIKPositionVar | string | The name of the source for the desired position
+ * of the LeftFoot joint. If not set, the foot rotation of the underlying animation will be used. |
leftFootIKRotationVar | string | The name of the source for the desired rotation
+ * of the LeftFoot joint. If not set, the foot rotation of the underlying animation will be used. |
leftFootPoleVectorEnabled | boolean | When true , the knee angle is
+ * controlled by the leftFootPoleVector property value. Otherwise the knee direction comes from the
+ * underlying animation. |
leftFootPoleVector | {@link Vec3} | The direction the knee should face in rig + * coordinates. |
rightFootIKPositionVar | string | The name of the source for the desired position
+ * of the RightFoot joint. If not set, the foot rotation of the underlying animation will be used. |
rightFootIKRotationVar | string | The name of the source for the desired rotation
+ * of the RightFoot joint. If not set, the foot rotation of the underlying animation will be used. |
rightFootPoleVectorEnabled | boolean | When true , the knee angle is
+ * controlled by the rightFootPoleVector property value. Otherwise the knee direction comes from the
+ * underlying animation. |
rightFootPoleVector | {@link Vec3} | The direction the knee should face in rig + * coordinates. |
isTalking | boolean | true if the avatar is talking. |
notIsTalking | boolean | true if the avatar is not talking. |
solutionSource | {@link MyAvatar.AnimIKSolutionSource|AnimIKSolutionSource} | + *Determines the initial conditions of the IK solver. |
defaultPoseOverlayAlpha | number | Controls the blend between the main animation state + * machine and the default pose. Mostly used during full body tracking so that walking & jumping animations do not + * affect the IK of the figure. |
defaultPoseOverlayBoneSet | {@link MyAvatar.AnimOverlayBoneSet|AnimOverlayBoneSet} | + *Specifies which bones will be replace by the source overlay. |
hipsType | {@link MyAvatar.IKTargetType|IKTargetType} | The type of IK used for the + * hips. |
hipsPosition | {@link Vec3} | The desired position of Hips joint in rig
+ * coordinates. |
hipsRotation | {@link Quat} | the desired orientation of the Hips joint in
+ * rig coordinates. |
spine2Type | {@link MyAvatar.IKTargetType|IKTargetType} | The type of IK used for the
+ * Spine2 joint. |
spine2Position | {@link Vec3} | The desired position of the Spine2 joint
+ * in rig coordinates. |
spine2Rotation | {@link Quat} | The desired orientation of the Spine2
+ * joint in rig coordinates. |
leftFootIKAlpha | number | Blends between full IK for the leg and the underlying + * animation. |
rightFootIKAlpha | number | Blends between full IK for the leg and the underlying + * animation. |
hipsWeight | number | How strongly the hips target blends with the IK solution for + * other IK chains. |
leftHandWeight | number | How strongly the left hand blends with IK solution of other + * IK chains. |
rightHandWeight | number | How strongly the right hand blends with IK solution of other + * IK chains. |
spine2Weight | number | How strongly the spine2 chain blends with the rest of the IK + * solution. |
leftHandOverlayAlpha | number | Used to blend in the animated hand gesture poses, such + * as point and thumbs up. |
leftHandGraspAlpha | number | Used to blend between an open hand and a closed hand. + * Usually changed as you squeeze the trigger of the hand controller. |
rightHandOverlayAlpha | number | Used to blend in the animated hand gesture poses, + * such as point and thumbs up. |
rightHandGraspAlpha | number | Used to blend between an open hand and a closed hand. + * Usually changed as you squeeze the trigger of the hand controller. |
isLeftIndexPoint | boolean | true if the left hand should be
+ * pointing. |
isLeftThumbRaise | boolean | true if the left hand should be
+ * thumbs-up. |
isLeftIndexPointAndThumbRaise | boolean | true if the left hand should be
+ * pointing and thumbs-up. |
isLeftHandGrasp | boolean | true if the left hand should be at rest,
+ * grasping the controller. |
isRightIndexPoint | boolean | true if the right hand should be
+ * pointing. |
isRightThumbRaise | boolean | true if the right hand should be
+ * thumbs-up. |
isRightIndexPointAndThumbRaise | boolean | true if the right hand should
+ * be pointing and thumbs-up. |
isRightHandGrasp | boolean | true if the right hand should be at rest,
+ * grasping the controller. |
Note: Rig coordinates are +z
forward and +y
up.