@zephyr3d/scene 0.7.1 → 0.8.0

package/dist/animation/ik/ik_angle_constraint.js

@@ -0,0 +1,181 @@
+import { Vector3 } from '@zephyr3d/base';
+import { IKConstraint } from './ik_constraint.js';
+
+/**
+ * Angle constraint for IK joints.
+ *
+ * Limits the angle between the bone from parent to this joint
+ * and the bone from this joint to child.
+ *
+ * @remarks
+ * This is useful for joints like elbows and knees that have
+ * limited range of motion.
+ *
+ * @public
+ */ class IKAngleConstraint extends IKConstraint {
+    /** Minimum angle in degrees */ _minAngle;
+    /** Maximum angle in degrees */ _maxAngle;
+    /**
+   * Create an angle constraint.
+   *
+   * @param jointIndex - Index of the joint in the chain
+   * @param minAngle - Minimum angle in degrees (0 = straight)
+   * @param maxAngle - Maximum angle in degrees (180 = fully bent)
+   */ constructor(jointIndex, minAngle, maxAngle){
+        super(jointIndex);
+        this._minAngle = Math.max(0, minAngle);
+        this._maxAngle = Math.min(180, maxAngle);
+        if (this._minAngle > this._maxAngle) {
+            throw new Error('IKAngleConstraint: minAngle must be <= maxAngle');
+        }
+    }
+    /**
+   * Get the minimum angle in degrees.
+   */ get minAngle() {
+        return this._minAngle;
+    }
+    /**
+   * Set the minimum angle in degrees.
+   */ set minAngle(value) {
+        this._minAngle = Math.max(0, Math.min(value, this._maxAngle));
+    }
+    /**
+   * Get the maximum angle in degrees.
+   */ get maxAngle() {
+        return this._maxAngle;
+    }
+    /**
+   * Set the maximum angle in degrees.
+   */ set maxAngle(value) {
+        this._maxAngle = Math.min(180, Math.max(value, this._minAngle));
+    }
+    /**
+   * Apply the angle constraint to limit joint bending.
+   */ apply(joints) {
+        const index = this._jointIndex;
+        // For end effector (last joint), we constrain the angle between the last two bones
+        // For other joints, we constrain the angle at the joint itself
+        if (index === joints.length - 1) {
+            // End effector: constrain angle between (parent-1 -> parent) and (parent -> this)
+            if (index < 2) {
+                return; // Need at least 3 joints total
+            }
+            this._applyEndEffectorConstraint(joints, index);
+        } else {
+            // Regular joint: constrain angle between (parent -> this) and (this -> child)
+            if (index < 1) {
+                return; // Root joint cannot be constrained this way
+            }
+            this._applyRegularConstraint(joints, index);
+        }
+    }
+    /**
+   * Apply constraint to end effector joint.
+   */ _applyEndEffectorConstraint(joints, index) {
+        const grandParentJoint = joints[index - 2];
+        const parentJoint = joints[index - 1];
+        const currentJoint = joints[index];
+        // Calculate bone vectors
+        const incomingBone = Vector3.sub(parentJoint.position, grandParentJoint.position, new Vector3());
+        const outgoingBone = Vector3.sub(currentJoint.position, parentJoint.position, new Vector3());
+        const incomingLen = incomingBone.magnitude;
+        const outgoingLen = outgoingBone.magnitude;
+        if (incomingLen < 0.000001 || outgoingLen < 0.000001) {
+            return;
+        }
+        // Normalize
+        const incomingNorm = Vector3.scale(incomingBone, 1 / incomingLen, new Vector3());
+        const outgoingNorm = Vector3.scale(outgoingBone, 1 / outgoingLen, new Vector3());
+        // Calculate current angle
+        const dot = Vector3.dot(incomingNorm, outgoingNorm);
+        const currentAngleDeg = Math.acos(Math.max(-1, Math.min(1, dot))) * (180 / Math.PI);
+        // Check if constraint is violated
+        let targetAngleDeg = currentAngleDeg;
+        if (currentAngleDeg < this._minAngle) {
+            targetAngleDeg = this._minAngle;
+        } else if (currentAngleDeg > this._maxAngle) {
+            targetAngleDeg = this._maxAngle;
+        } else {
+            return;
+        }
+        // Apply the same constraint logic as regular joints
+        this._adjustJointAngle(incomingNorm, outgoingNorm, currentAngleDeg, targetAngleDeg, parentJoint, currentJoint);
+    }
+    /**
+   * Apply constraint to regular joint.
+   */ _applyRegularConstraint(joints, index) {
+        const parentJoint = joints[index - 1];
+        const currentJoint = joints[index];
+        const childJoint = joints[index + 1];
+        // Calculate bone vectors: incoming bone (parent->current) and outgoing bone (current->child)
+        const incomingBone = Vector3.sub(currentJoint.position, parentJoint.position, new Vector3());
+        const outgoingBone = Vector3.sub(childJoint.position, currentJoint.position, new Vector3());
+        const incomingLen = incomingBone.magnitude;
+        const outgoingLen = outgoingBone.magnitude;
+        if (incomingLen < 0.000001 || outgoingLen < 0.000001) {
+            return;
+        }
+        // Normalize
+        const incomingNorm = Vector3.scale(incomingBone, 1 / incomingLen, new Vector3());
+        const outgoingNorm = Vector3.scale(outgoingBone, 1 / outgoingLen, new Vector3());
+        // Calculate current angle between incoming and outgoing bones (interior angle)
+        const dot = Vector3.dot(incomingNorm, outgoingNorm);
+        const currentAngleDeg = Math.acos(Math.max(-1, Math.min(1, dot))) * (180 / Math.PI);
+        // Check if constraint is violated
+        let targetAngleDeg = currentAngleDeg;
+        if (currentAngleDeg < this._minAngle) {
+            targetAngleDeg = this._minAngle;
+        } else if (currentAngleDeg > this._maxAngle) {
+            targetAngleDeg = this._maxAngle;
+        } else {
+            return;
+        }
+        // Apply the constraint
+        this._adjustJointAngle(incomingNorm, outgoingNorm, currentAngleDeg, targetAngleDeg, currentJoint, childJoint);
+    }
+    /**
+   * Adjust joint angle by rotating the outgoing bone.
+   */ _adjustJointAngle(incomingNorm, outgoingNorm, currentAngleDeg, targetAngleDeg, pivotJoint, targetJoint) {
+        // Add a dead zone to prevent oscillation
+        const angleDifference = Math.abs(targetAngleDeg - currentAngleDeg);
+        const isHardConstraint = Math.abs(this._maxAngle - this._minAngle) < 0.01;
+        const deadZone = isHardConstraint ? 0.2 : 0.1;
+        if (angleDifference < deadZone) {
+            return; // Too close to target, avoid over-correction
+        }
+        // Calculate rotation axis (perpendicular to both bone vectors)
+        const axis = Vector3.cross(incomingNorm, outgoingNorm, new Vector3());
+        const axisLen = axis.magnitude;
+        // Use a smaller threshold to allow constraint to work at small angles
+        if (axisLen < 0.0001) {
+            return; // Vectors are too close to parallel or anti-parallel
+        }
+        axis.scaleBy(1 / axisLen);
+        // Calculate the angle we need to rotate
+        const targetAngleRad = targetAngleDeg * (Math.PI / 180);
+        const currentAngleRad = currentAngleDeg * (Math.PI / 180);
+        let deltaAngle = targetAngleRad - currentAngleRad;
+        // Apply full correction without damping to ensure constraints are enforced
+        // This is necessary because FABRIK will try to undo the constraint in the next iteration
+        // So we need strong constraint enforcement
+        // Rotate the outgoing bone vector around the axis by deltaAngle
+        const cos = Math.cos(deltaAngle);
+        const sin = Math.sin(deltaAngle);
+        const oneMinusCos = 1 - cos;
+        // Rodrigues' rotation formula
+        const rotated = new Vector3();
+        rotated.x = outgoingNorm.x * (cos + axis.x * axis.x * oneMinusCos) + outgoingNorm.y * (axis.x * axis.y * oneMinusCos - axis.z * sin) + outgoingNorm.z * (axis.x * axis.z * oneMinusCos + axis.y * sin);
+        rotated.y = outgoingNorm.x * (axis.y * axis.x * oneMinusCos + axis.z * sin) + outgoingNorm.y * (cos + axis.y * axis.y * oneMinusCos) + outgoingNorm.z * (axis.y * axis.z * oneMinusCos - axis.x * sin);
+        rotated.z = outgoingNorm.x * (axis.z * axis.x * oneMinusCos - axis.y * sin) + outgoingNorm.y * (axis.z * axis.y * oneMinusCos + axis.x * sin) + outgoingNorm.z * (cos + axis.z * axis.z * oneMinusCos);
+        // Update target joint position using the rotated bone vector
+        const boneLength = pivotJoint.boneLength;
+        rotated.scaleBy(boneLength);
+        Vector3.add(pivotJoint.position, rotated, targetJoint.position);
+    // Note: We do NOT recursively update subsequent joints here.
+    // Instead, we let FABRIK algorithm handle the propagation in subsequent iterations.
+    // This ensures that each joint's constraint is properly applied.
+    }
+}
+
+export { IKAngleConstraint };
+//# sourceMappingURL=ik_angle_constraint.js.map

package/dist/animation/ik/ik_angle_constraint.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ik_angle_constraint.js","sources":["../../../src/animation/ik/ik_angle_constraint.ts"],"sourcesContent":["import { Vector3 } from '@zephyr3d/base';\r\nimport { IKConstraint } from './ik_constraint';\r\nimport type { IKJoint } from './ik_joint';\r\n\r\n/**\r\n * Angle constraint for IK joints.\r\n *\r\n * Limits the angle between the bone from parent to this joint\r\n * and the bone from this joint to child.\r\n *\r\n * @remarks\r\n * This is useful for joints like elbows and knees that have\r\n * limited range of motion.\r\n *\r\n * @public\r\n */\r\nexport class IKAngleConstraint extends IKConstraint {\r\n  /** Minimum angle in degrees */\r\n  private _minAngle: number;\r\n  /** Maximum angle in degrees */\r\n  private _maxAngle: number;\r\n\r\n  /**\r\n   * Create an angle constraint.\r\n   *\r\n   * @param jointIndex - Index of the joint in the chain\r\n   * @param minAngle - Minimum angle in degrees (0 = straight)\r\n   * @param maxAngle - Maximum angle in degrees (180 = fully bent)\r\n   */\r\n  constructor(jointIndex: number, minAngle: number, maxAngle: number) {\r\n    super(jointIndex);\r\n    this._minAngle = Math.max(0, minAngle);\r\n    this._maxAngle = Math.min(180, maxAngle);\r\n\r\n    if (this._minAngle > this._maxAngle) {\r\n      throw new Error('IKAngleConstraint: minAngle must be <= maxAngle');\r\n    }\r\n  }\r\n\r\n  /**\r\n   * Get the minimum angle in degrees.\r\n   */\r\n  get minAngle(): number {\r\n    return this._minAngle;\r\n  }\r\n\r\n  /**\r\n   * Set the minimum angle in degrees.\r\n   */\r\n  set minAngle(value: number) {\r\n    this._minAngle = Math.max(0, Math.min(value, this._maxAngle));\r\n  }\r\n\r\n  /**\r\n   * Get the maximum angle in degrees.\r\n   */\r\n  get maxAngle(): number {\r\n    return this._maxAngle;\r\n  }\r\n\r\n  /**\r\n   * Set the maximum angle in degrees.\r\n   */\r\n  set maxAngle(value: number) {\r\n    this._maxAngle = Math.min(180, Math.max(value, this._minAngle));\r\n  }\r\n\r\n  /**\r\n   * Apply the angle constraint to limit joint bending.\r\n   */\r\n  apply(joints: IKJoint[]): void {\r\n    const index = this._jointIndex;\r\n\r\n    // For end effector (last joint), we constrain the angle between the last two bones\r\n    // For other joints, we constrain the angle at the joint itself\r\n    if (index === joints.length - 1) {\r\n      // End effector: constrain angle between (parent-1 -> parent) and (parent -> this)\r\n      if (index < 2) {\r\n        return; // Need at least 3 joints total\r\n      }\r\n      this._applyEndEffectorConstraint(joints, index);\r\n    } else {\r\n      // Regular joint: constrain angle between (parent -> this) and (this -> child)\r\n      if (index < 1) {\r\n        return; // Root joint cannot be constrained this way\r\n      }\r\n      this._applyRegularConstraint(joints, index);\r\n    }\r\n  }\r\n\r\n  /**\r\n   * Apply constraint to end effector joint.\r\n   */\r\n  private _applyEndEffectorConstraint(joints: IKJoint[], index: number): void {\r\n    const grandParentJoint = joints[index - 2];\r\n    const parentJoint = joints[index - 1];\r\n    const currentJoint = joints[index];\r\n\r\n    // Calculate bone vectors\r\n    const incomingBone = Vector3.sub(parentJoint.position, grandParentJoint.position, new Vector3());\r\n    const outgoingBone = Vector3.sub(currentJoint.position, parentJoint.position, new Vector3());\r\n\r\n    const incomingLen = incomingBone.magnitude;\r\n    const outgoingLen = outgoingBone.magnitude;\r\n\r\n    if (incomingLen < 0.000001 || outgoingLen < 0.000001) {\r\n      return;\r\n    }\r\n\r\n    // Normalize\r\n    const incomingNorm = Vector3.scale(incomingBone, 1 / incomingLen, new Vector3());\r\n    const outgoingNorm = Vector3.scale(outgoingBone, 1 / outgoingLen, new Vector3());\r\n\r\n    // Calculate current angle\r\n    const dot = Vector3.dot(incomingNorm, outgoingNorm);\r\n    const currentAngleDeg = Math.acos(Math.max(-1, Math.min(1, dot))) * (180 / Math.PI);\r\n\r\n    // Check if constraint is violated\r\n    let targetAngleDeg = currentAngleDeg;\r\n    if (currentAngleDeg < this._minAngle) {\r\n      targetAngleDeg = this._minAngle;\r\n    } else if (currentAngleDeg > this._maxAngle) {\r\n      targetAngleDeg = this._maxAngle;\r\n    } else {\r\n      return;\r\n    }\r\n\r\n    // Apply the same constraint logic as regular joints\r\n    this._adjustJointAngle(\r\n      incomingNorm,\r\n      outgoingNorm,\r\n      currentAngleDeg,\r\n      targetAngleDeg,\r\n      parentJoint,\r\n      currentJoint\r\n    );\r\n  }\r\n\r\n  /**\r\n   * Apply constraint to regular joint.\r\n   */\r\n  private _applyRegularConstraint(joints: IKJoint[], index: number): void {\r\n    const parentJoint = joints[index - 1];\r\n    const currentJoint = joints[index];\r\n    const childJoint = joints[index + 1];\r\n\r\n    // Calculate bone vectors: incoming bone (parent->current) and outgoing bone (current->child)\r\n    const incomingBone = Vector3.sub(currentJoint.position, parentJoint.position, new Vector3());\r\n    const outgoingBone = Vector3.sub(childJoint.position, currentJoint.position, new Vector3());\r\n\r\n    const incomingLen = incomingBone.magnitude;\r\n    const outgoingLen = outgoingBone.magnitude;\r\n\r\n    if (incomingLen < 0.000001 || outgoingLen < 0.000001) {\r\n      return;\r\n    }\r\n\r\n    // Normalize\r\n    const incomingNorm = Vector3.scale(incomingBone, 1 / incomingLen, new Vector3());\r\n    const outgoingNorm = Vector3.scale(outgoingBone, 1 / outgoingLen, new Vector3());\r\n\r\n    // Calculate current angle between incoming and outgoing bones (interior angle)\r\n    const dot = Vector3.dot(incomingNorm, outgoingNorm);\r\n    const currentAngleDeg = Math.acos(Math.max(-1, Math.min(1, dot))) * (180 / Math.PI);\r\n\r\n    // Check if constraint is violated\r\n    let targetAngleDeg = currentAngleDeg;\r\n    if (currentAngleDeg < this._minAngle) {\r\n      targetAngleDeg = this._minAngle;\r\n    } else if (currentAngleDeg > this._maxAngle) {\r\n      targetAngleDeg = this._maxAngle;\r\n    } else {\r\n      return;\r\n    }\r\n\r\n    // Apply the constraint\r\n    this._adjustJointAngle(\r\n      incomingNorm,\r\n      outgoingNorm,\r\n      currentAngleDeg,\r\n      targetAngleDeg,\r\n      currentJoint,\r\n      childJoint\r\n    );\r\n  }\r\n\r\n  /**\r\n   * Adjust joint angle by rotating the outgoing bone.\r\n   */\r\n  private _adjustJointAngle(\r\n    incomingNorm: Vector3,\r\n    outgoingNorm: Vector3,\r\n    currentAngleDeg: number,\r\n    targetAngleDeg: number,\r\n    pivotJoint: IKJoint,\r\n    targetJoint: IKJoint\r\n  ): void {\r\n    // Add a dead zone to prevent oscillation\r\n    const angleDifference = Math.abs(targetAngleDeg - currentAngleDeg);\r\n    const isHardConstraint = Math.abs(this._maxAngle - this._minAngle) < 0.01;\r\n    const deadZone = isHardConstraint ? 0.2 : 0.1;\r\n\r\n    if (angleDifference < deadZone) {\r\n      return; // Too close to target, avoid over-correction\r\n    }\r\n\r\n    // Calculate rotation axis (perpendicular to both bone vectors)\r\n    const axis = Vector3.cross(incomingNorm, outgoingNorm, new Vector3());\r\n    const axisLen = axis.magnitude;\r\n\r\n    // Use a smaller threshold to allow constraint to work at small angles\r\n    if (axisLen < 0.0001) {\r\n      return; // Vectors are too close to parallel or anti-parallel\r\n    }\r\n\r\n    axis.scaleBy(1 / axisLen);\r\n\r\n    // Calculate the angle we need to rotate\r\n    const targetAngleRad = targetAngleDeg * (Math.PI / 180);\r\n    const currentAngleRad = currentAngleDeg * (Math.PI / 180);\r\n    let deltaAngle = targetAngleRad - currentAngleRad;\r\n\r\n    // Apply full correction without damping to ensure constraints are enforced\r\n    // This is necessary because FABRIK will try to undo the constraint in the next iteration\r\n    // So we need strong constraint enforcement\r\n\r\n    // Rotate the outgoing bone vector around the axis by deltaAngle\r\n    const cos = Math.cos(deltaAngle);\r\n    const sin = Math.sin(deltaAngle);\r\n    const oneMinusCos = 1 - cos;\r\n\r\n    // Rodrigues' rotation formula\r\n    const rotated = new Vector3();\r\n    rotated.x =\r\n      outgoingNorm.x * (cos + axis.x * axis.x * oneMinusCos) +\r\n      outgoingNorm.y * (axis.x * axis.y * oneMinusCos - axis.z * sin) +\r\n      outgoingNorm.z * (axis.x * axis.z * oneMinusCos + axis.y * sin);\r\n\r\n    rotated.y =\r\n      outgoingNorm.x * (axis.y * axis.x * oneMinusCos + axis.z * sin) +\r\n      outgoingNorm.y * (cos + axis.y * axis.y * oneMinusCos) +\r\n      outgoingNorm.z * (axis.y * axis.z * oneMinusCos - axis.x * sin);\r\n\r\n    rotated.z =\r\n      outgoingNorm.x * (axis.z * axis.x * oneMinusCos - axis.y * sin) +\r\n      outgoingNorm.y * (axis.z * axis.y * oneMinusCos + axis.x * sin) +\r\n      outgoingNorm.z * (cos + axis.z * axis.z * oneMinusCos);\r\n\r\n    // Update target joint position using the rotated bone vector\r\n    const boneLength = pivotJoint.boneLength;\r\n    rotated.scaleBy(boneLength);\r\n    Vector3.add(pivotJoint.position, rotated, targetJoint.position);\r\n\r\n    // Note: We do NOT recursively update subsequent joints here.\r\n    // Instead, we let FABRIK algorithm handle the propagation in subsequent iterations.\r\n    // This ensures that each joint's constraint is properly applied.\r\n  }\r\n}\r\n"],"names":["IKAngleConstraint","IKConstraint","jointIndex","minAngle","maxAngle","_minAngle","Math","max","_maxAngle","min","Error","value","apply","joints","index","_jointIndex","length","_applyEndEffectorConstraint","_applyRegularConstraint","grandParentJoint","parentJoint","currentJoint","incomingBone","Vector3","sub","position","outgoingBone","incomingLen","magnitude","outgoingLen","incomingNorm","scale","outgoingNorm","dot","currentAngleDeg","acos","PI","targetAngleDeg","_adjustJointAngle","childJoint","pivotJoint","targetJoint","angleDifference","abs","isHardConstraint","deadZone","axis","cross","axisLen","scaleBy","targetAngleRad","currentAngleRad","deltaAngle","cos","sin","oneMinusCos","rotated","x","y","z","boneLength","add"],"mappings":"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"}

package/dist/animation/ik/ik_chain.js

@@ -0,0 +1,163 @@
+import { Vector3, Quaternion } from '@zephyr3d/base';
+import { IKUtils } from './ik_utils.js';
+
+/**
+ * Represents a chain of joints for IK solving.
+ *
+ * @public
+ */ class IKChain {
+    /** Array of joints in the chain (root to end effector) */ _joints;
+    /** Total length of the chain */ _totalLength;
+    /** Constraints applied to joints */ _constraints;
+    /**
+   * Create an IK chain from an array of scene nodes.
+   *
+   * @param nodes - Array of scene nodes from root to end effector
+   */ constructor(nodes){
+        if (nodes.length < 2) {
+            throw new Error('IK chain must have at least 2 joints');
+        }
+        this._joints = [];
+        this._totalLength = 0;
+        this._constraints = [];
+        // Create joints from nodes
+        for(let i = 0; i < nodes.length; i++){
+            const node = nodes[i];
+            const position = new Vector3();
+            const rotation = new Quaternion();
+            node.worldMatrix.decompose(null, rotation, position);
+            let boneLength = 0;
+            if (i < nodes.length - 1) {
+                const nextPosition = new Vector3();
+                nodes[i + 1].worldMatrix.decompose(null, null, nextPosition);
+                boneLength = IKUtils.calculateBoneLength(position, nextPosition);
+                this._totalLength += boneLength;
+            }
+            this._joints.push({
+                node,
+                position: position.clone(),
+                originalPosition: position.clone(),
+                rotation: rotation.clone(),
+                originalRotation: rotation.clone(),
+                boneLength
+            });
+        }
+    }
+    /**
+   * Create an IK chain by traversing from a start node to an end node.
+   *
+   * @remarks
+   * This method walks up the parent chain from the end node until it
+   * reaches the start node, building the joint chain in the process.
+   *
+   * @param startNode - The root joint of the chain
+   * @param endNode - The end effector joint
+   * @returns The created IK chain
+   */ static fromNodeHierarchy(startNode, endNode) {
+        const nodes = [];
+        let current = endNode;
+        // Walk up the hierarchy from end to start
+        while(current){
+            nodes.unshift(current); // Add to front
+            if (current === startNode) {
+                break;
+            }
+            current = current.parent;
+        }
+        if (nodes[0] !== startNode) {
+            throw new Error('End node is not a descendant of start node');
+        }
+        if (nodes.length < 2) {
+            throw new Error('IK chain must have at least 2 joints');
+        }
+        return new IKChain(nodes);
+    }
+    /**
+   * Get all joints in the chain.
+   */ get joints() {
+        return this._joints;
+    }
+    /**
+   * Get the root joint (first joint in the chain).
+   */ get root() {
+        return this._joints[0];
+    }
+    /**
+   * Get the end effector (last joint in the chain).
+   */ get endEffector() {
+        return this._joints[this._joints.length - 1];
+    }
+    /**
+   * Get the total length of the chain.
+   */ get totalLength() {
+        return this._totalLength;
+    }
+    /**
+   * Get the number of joints in the chain.
+   */ get length() {
+        return this._joints.length;
+    }
+    /**
+   * Update joint positions from their scene nodes.
+   */ updateFromNodes() {
+        for (const joint of this._joints){
+            joint.node.worldMatrix.decompose(null, joint.rotation, joint.position);
+        }
+    }
+    /**
+   * Store current positions as original positions.
+   */ storeOriginalPositions() {
+        for (const joint of this._joints){
+            joint.originalPosition.set(joint.position);
+            joint.originalRotation.set(joint.rotation);
+        }
+    }
+    /**
+   * Restore joints to their original positions.
+   */ restoreOriginalPositions() {
+        for (const joint of this._joints){
+            joint.position.set(joint.originalPosition);
+            joint.rotation.set(joint.originalRotation);
+        }
+    }
+    /**
+   * Add a constraint to a specific joint.
+   *
+   * @param constraint - The constraint to add
+   */ addConstraint(constraint) {
+        this._constraints.push(constraint);
+    }
+    /**
+   * Remove a constraint from the chain.
+   *
+   * @param constraint - The constraint to remove
+   * @returns True if the constraint was found and removed
+   */ removeConstraint(constraint) {
+        const index = this._constraints.indexOf(constraint);
+        if (index >= 0) {
+            this._constraints.splice(index, 1);
+            return true;
+        }
+        return false;
+    }
+    /**
+   * Clear all constraints from the chain.
+   */ clearConstraints() {
+        this._constraints = [];
+    }
+    /**
+   * Get all constraints in the chain.
+   */ get constraints() {
+        return this._constraints;
+    }
+    /**
+   * Apply all constraints to the joint chain.
+   */ applyConstraints() {
+        for (const constraint of this._constraints){
+            constraint.apply(this._joints);
+        }
+    }
+}
+
+export { IKChain };
+//# sourceMappingURL=ik_chain.js.map

package/dist/animation/ik/ik_chain.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ik_chain.js","sources":["../../../src/animation/ik/ik_chain.ts"],"sourcesContent":["import { Vector3, Quaternion } from '@zephyr3d/base';\r\nimport type { IKJoint } from './ik_joint';\r\nimport type { SceneNode } from '../../scene/scene_node';\r\nimport type { IKConstraint } from './ik_constraint';\r\nimport { IKUtils } from './ik_utils';\r\n\r\n/**\r\n * Represents a chain of joints for IK solving.\r\n *\r\n * @public\r\n */\r\nexport class IKChain {\r\n  /** Array of joints in the chain (root to end effector) */\r\n  private _joints: IKJoint[];\r\n  /** Total length of the chain */\r\n  private _totalLength: number;\r\n  /** Constraints applied to joints */\r\n  private _constraints: IKConstraint[];\r\n\r\n  /**\r\n   * Create an IK chain from an array of scene nodes.\r\n   *\r\n   * @param nodes - Array of scene nodes from root to end effector\r\n   */\r\n  constructor(nodes: SceneNode[]) {\r\n    if (nodes.length < 2) {\r\n      throw new Error('IK chain must have at least 2 joints');\r\n    }\r\n\r\n    this._joints = [];\r\n    this._totalLength = 0;\r\n    this._constraints = [];\r\n\r\n    // Create joints from nodes\r\n    for (let i = 0; i < nodes.length; i++) {\r\n      const node = nodes[i];\r\n      const position = new Vector3();\r\n      const rotation = new Quaternion();\r\n      node.worldMatrix.decompose(null, rotation, position);\r\n\r\n      let boneLength = 0;\r\n      if (i < nodes.length - 1) {\r\n        const nextPosition = new Vector3();\r\n        nodes[i + 1].worldMatrix.decompose(null, null, nextPosition);\r\n        boneLength = IKUtils.calculateBoneLength(position, nextPosition);\r\n        this._totalLength += boneLength;\r\n      }\r\n\r\n      this._joints.push({\r\n        node,\r\n        position: position.clone(),\r\n        originalPosition: position.clone(),\r\n        rotation: rotation.clone(),\r\n        originalRotation: rotation.clone(),\r\n        boneLength\r\n      });\r\n    }\r\n  }\r\n\r\n  /**\r\n   * Create an IK chain by traversing from a start node to an end node.\r\n   *\r\n   * @remarks\r\n   * This method walks up the parent chain from the end node until it\r\n   * reaches the start node, building the joint chain in the process.\r\n   *\r\n   * @param startNode - The root joint of the chain\r\n   * @param endNode - The end effector joint\r\n   * @returns The created IK chain\r\n   */\r\n  static fromNodeHierarchy(startNode: SceneNode, endNode: SceneNode): IKChain {\r\n    const nodes: SceneNode[] = [];\r\n    let current: SceneNode | null = endNode;\r\n\r\n    // Walk up the hierarchy from end to start\r\n    while (current) {\r\n      nodes.unshift(current); // Add to front\r\n\r\n      if (current === startNode) {\r\n        break;\r\n      }\r\n\r\n      current = current.parent as SceneNode | null;\r\n    }\r\n\r\n    if (nodes[0] !== startNode) {\r\n      throw new Error('End node is not a descendant of start node');\r\n    }\r\n\r\n    if (nodes.length < 2) {\r\n      throw new Error('IK chain must have at least 2 joints');\r\n    }\r\n\r\n    return new IKChain(nodes);\r\n  }\r\n\r\n  /**\r\n   * Get all joints in the chain.\r\n   */\r\n  get joints(): IKJoint[] {\r\n    return this._joints;\r\n  }\r\n\r\n  /**\r\n   * Get the root joint (first joint in the chain).\r\n   */\r\n  get root(): IKJoint {\r\n    return this._joints[0];\r\n  }\r\n\r\n  /**\r\n   * Get the end effector (last joint in the chain).\r\n   */\r\n  get endEffector(): IKJoint {\r\n    return this._joints[this._joints.length - 1];\r\n  }\r\n\r\n  /**\r\n   * Get the total length of the chain.\r\n   */\r\n  get totalLength(): number {\r\n    return this._totalLength;\r\n  }\r\n\r\n  /**\r\n   * Get the number of joints in the chain.\r\n   */\r\n  get length(): number {\r\n    return this._joints.length;\r\n  }\r\n\r\n  /**\r\n   * Update joint positions from their scene nodes.\r\n   */\r\n  updateFromNodes(): void {\r\n    for (const joint of this._joints) {\r\n      joint.node.worldMatrix.decompose(null, joint.rotation, joint.position);\r\n    }\r\n  }\r\n\r\n  /**\r\n   * Store current positions as original positions.\r\n   */\r\n  storeOriginalPositions(): void {\r\n    for (const joint of this._joints) {\r\n      joint.originalPosition.set(joint.position);\r\n      joint.originalRotation.set(joint.rotation);\r\n    }\r\n  }\r\n\r\n  /**\r\n   * Restore joints to their original positions.\r\n   */\r\n  restoreOriginalPositions(): void {\r\n    for (const joint of this._joints) {\r\n      joint.position.set(joint.originalPosition);\r\n      joint.rotation.set(joint.originalRotation);\r\n    }\r\n  }\r\n\r\n  /**\r\n   * Add a constraint to a specific joint.\r\n   *\r\n   * @param constraint - The constraint to add\r\n   */\r\n  addConstraint(constraint: IKConstraint): void {\r\n    this._constraints.push(constraint);\r\n  }\r\n\r\n  /**\r\n   * Remove a constraint from the chain.\r\n   *\r\n   * @param constraint - The constraint to remove\r\n   * @returns True if the constraint was found and removed\r\n   */\r\n  removeConstraint(constraint: IKConstraint): boolean {\r\n    const index = this._constraints.indexOf(constraint);\r\n    if (index >= 0) {\r\n      this._constraints.splice(index, 1);\r\n      return true;\r\n    }\r\n    return false;\r\n  }\r\n\r\n  /**\r\n   * Clear all constraints from the chain.\r\n   */\r\n  clearConstraints(): void {\r\n    this._constraints = [];\r\n  }\r\n\r\n  /**\r\n   * Get all constraints in the chain.\r\n   */\r\n  get constraints(): readonly IKConstraint[] {\r\n    return this._constraints;\r\n  }\r\n\r\n  /**\r\n   * Apply all constraints to the joint chain.\r\n   */\r\n  applyConstraints(): void {\r\n    for (const constraint of this._constraints) {\r\n      constraint.apply(this._joints);\r\n    }\r\n  }\r\n}\r\n"],"names":["IKChain","nodes","length","Error","_joints","_totalLength","_constraints","i","node","position","Vector3","rotation","Quaternion","worldMatrix","decompose","boneLength","nextPosition","IKUtils","calculateBoneLength","push","clone","originalPosition","originalRotation","fromNodeHierarchy","startNode","endNode","current","unshift","parent","joints","root","endEffector","totalLength","updateFromNodes","joint","storeOriginalPositions","set","restoreOriginalPositions","addConstraint","constraint","removeConstraint","index","indexOf","splice","clearConstraints","constraints","applyConstraints","apply"],"mappings":"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"}

package/dist/animation/ik/ik_chain_builder.js

@@ -0,0 +1,68 @@
+import { IKChain } from './ik_chain.js';
+
+/**
+ * Helper class for building IK chains from various sources.
+ *
+ * @public
+ */ class IKChainBuilder {
+    /**
+   * Create an IK chain from an array of scene nodes.
+   *
+   * @param nodes - Array of scene nodes from root to end effector
+   * @returns The created IK chain
+   */ static fromNodes(nodes) {
+        return new IKChain(nodes);
+    }
+    /**
+   * Create an IK chain from a skeleton using joint indices.
+   *
+   * @param skeleton - The skeleton containing the joints
+   * @param jointIndices - Array of joint indices from root to end effector
+   * @returns The created IK chain
+   */ static fromSkeleton(skeleton, jointIndices) {
+        if (jointIndices.length < 2) {
+            throw new Error('IK chain must have at least 2 joints');
+        }
+        const joints = skeleton.joints;
+        const nodes = [];
+        for (const index of jointIndices){
+            if (index < 0 || index >= joints.length) {
+                throw new Error(`Invalid joint index: ${index}`);
+            }
+            nodes.push(joints[index]);
+        }
+        return new IKChain(nodes);
+    }
+    /**
+   * Create an IK chain by traversing from a start node to an end node.
+   *
+   * @remarks
+   * This method walks up the parent chain from the end node until it
+   * reaches the start node, building the joint chain in the process.
+   *
+   * @param startNode - The root joint of the chain
+   * @param endNode - The end effector joint
+   * @returns The created IK chain
+   */ static fromNodeHierarchy(startNode, endNode) {
+        const nodes = [];
+        let current = endNode;
+        // Walk up the hierarchy from end to start
+        while(current){
+            nodes.unshift(current); // Add to front
+            if (current === startNode) {
+                break;
+            }
+            current = current.parent;
+        }
+        if (nodes[0] !== startNode) {
+            throw new Error('End node is not a descendant of start node');
+        }
+        if (nodes.length < 2) {
+            throw new Error('IK chain must have at least 2 joints');
+        }
+        return new IKChain(nodes);
+    }
+}
+
+export { IKChainBuilder };
+//# sourceMappingURL=ik_chain_builder.js.map

package/dist/animation/ik/ik_chain_builder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ik_chain_builder.js","sources":["../../../src/animation/ik/ik_chain_builder.ts"],"sourcesContent":["import { IKChain } from './ik_chain';\r\nimport type { SceneNode } from '../../scene/scene_node';\r\nimport type { Skeleton } from '../skeleton';\r\n\r\n/**\r\n * Helper class for building IK chains from various sources.\r\n *\r\n * @public\r\n */\r\nexport class IKChainBuilder {\r\n  /**\r\n   * Create an IK chain from an array of scene nodes.\r\n   *\r\n   * @param nodes - Array of scene nodes from root to end effector\r\n   * @returns The created IK chain\r\n   */\r\n  static fromNodes(nodes: SceneNode[]): IKChain {\r\n    return new IKChain(nodes);\r\n  }\r\n\r\n  /**\r\n   * Create an IK chain from a skeleton using joint indices.\r\n   *\r\n   * @param skeleton - The skeleton containing the joints\r\n   * @param jointIndices - Array of joint indices from root to end effector\r\n   * @returns The created IK chain\r\n   */\r\n  static fromSkeleton(skeleton: Skeleton, jointIndices: number[]): IKChain {\r\n    if (jointIndices.length < 2) {\r\n      throw new Error('IK chain must have at least 2 joints');\r\n    }\r\n\r\n    const joints = skeleton.joints;\r\n    const nodes: SceneNode[] = [];\r\n\r\n    for (const index of jointIndices) {\r\n      if (index < 0 || index >= joints.length) {\r\n        throw new Error(`Invalid joint index: ${index}`);\r\n      }\r\n      nodes.push(joints[index]);\r\n    }\r\n\r\n    return new IKChain(nodes);\r\n  }\r\n\r\n  /**\r\n   * Create an IK chain by traversing from a start node to an end node.\r\n   *\r\n   * @remarks\r\n   * This method walks up the parent chain from the end node until it\r\n   * reaches the start node, building the joint chain in the process.\r\n   *\r\n   * @param startNode - The root joint of the chain\r\n   * @param endNode - The end effector joint\r\n   * @returns The created IK chain\r\n   */\r\n  static fromNodeHierarchy(startNode: SceneNode, endNode: SceneNode): IKChain {\r\n    const nodes: SceneNode[] = [];\r\n    let current: SceneNode | null = endNode;\r\n\r\n    // Walk up the hierarchy from end to start\r\n    while (current) {\r\n      nodes.unshift(current); // Add to front\r\n\r\n      if (current === startNode) {\r\n        break;\r\n      }\r\n\r\n      current = current.parent as SceneNode | null;\r\n    }\r\n\r\n    if (nodes[0] !== startNode) {\r\n      throw new Error('End node is not a descendant of start node');\r\n    }\r\n\r\n    if (nodes.length < 2) {\r\n      throw new Error('IK chain must have at least 2 joints');\r\n    }\r\n\r\n    return new IKChain(nodes);\r\n  }\r\n}\r\n"],"names":["IKChainBuilder","fromNodes","nodes","IKChain","fromSkeleton","skeleton","jointIndices","length","Error","joints","index","push","fromNodeHierarchy","startNode","endNode","current","unshift","parent"],"mappings":";;AAIA;;;;AAIC,IACM,MAAMA,cAAAA,CAAAA;AACX;;;;;MAMA,OAAOC,SAAUC,CAAAA,KAAkB,EAAW;AAC5C,QAAA,OAAO,IAAIC,OAAQD,CAAAA,KAAAA,CAAAA;AACrB;AAEA;;;;;;AAMC,MACD,OAAOE,YAAAA,CAAaC,QAAkB,EAAEC,YAAsB,EAAW;QACvE,IAAIA,YAAAA,CAAaC,MAAM,GAAG,CAAG,EAAA;AAC3B,YAAA,MAAM,IAAIC,KAAM,CAAA,sCAAA,CAAA;AAClB;QAEA,MAAMC,MAAAA,GAASJ,SAASI,MAAM;AAC9B,QAAA,MAAMP,QAAqB,EAAE;QAE7B,KAAK,MAAMQ,SAASJ,YAAc,CAAA;AAChC,YAAA,IAAII,KAAQ,GAAA,CAAA,IAAKA,KAASD,IAAAA,MAAAA,CAAOF,MAAM,EAAE;AACvC,gBAAA,MAAM,IAAIC,KAAAA,CAAM,CAAC,qBAAqB,EAAEE,KAAO,CAAA,CAAA,CAAA;AACjD;AACAR,YAAAA,KAAAA,CAAMS,IAAI,CAACF,MAAM,CAACC,KAAM,CAAA,CAAA;AAC1B;AAEA,QAAA,OAAO,IAAIP,OAAQD,CAAAA,KAAAA,CAAAA;AACrB;AAEA;;;;;;;;;;AAUC,MACD,OAAOU,iBAAAA,CAAkBC,SAAoB,EAAEC,OAAkB,EAAW;AAC1E,QAAA,MAAMZ,QAAqB,EAAE;AAC7B,QAAA,IAAIa,OAA4BD,GAAAA,OAAAA;;AAGhC,QAAA,MAAOC,OAAS,CAAA;YACdb,KAAMc,CAAAA,OAAO,CAACD,OAAAA,CAAAA,CAAAA;AAEd,YAAA,IAAIA,YAAYF,SAAW,EAAA;AACzB,gBAAA;AACF;AAEAE,YAAAA,OAAAA,GAAUA,QAAQE,MAAM;AAC1B;AAEA,QAAA,IAAIf,KAAK,CAAC,CAAE,CAAA,KAAKW,SAAW,EAAA;AAC1B,YAAA,MAAM,IAAIL,KAAM,CAAA,4CAAA,CAAA;AAClB;QAEA,IAAIN,KAAAA,CAAMK,MAAM,GAAG,CAAG,EAAA;AACpB,YAAA,MAAM,IAAIC,KAAM,CAAA,sCAAA,CAAA;AAClB;AAEA,QAAA,OAAO,IAAIL,OAAQD,CAAAA,KAAAA,CAAAA;AACrB;AACF;;;;"}

package/dist/animation/ik/ik_constraint.js

@@ -0,0 +1,25 @@
+/**
+ * Base class for IK constraints.
+ *
+ * Constraints are applied after each FABRIK iteration to enforce
+ * joint limitations (angle limits, pole vectors, etc.).
+ *
+ * @public
+ */ class IKConstraint {
+    /** The joint index this constraint applies to */ _jointIndex;
+    /**
+   * Create an IK constraint.
+   *
+   * @param jointIndex - Index of the joint in the chain (0 = root)
+   */ constructor(jointIndex){
+        this._jointIndex = jointIndex;
+    }
+    /**
+   * Get the joint index this constraint applies to.
+   */ get jointIndex() {
+        return this._jointIndex;
+    }
+}
+
+export { IKConstraint };
+//# sourceMappingURL=ik_constraint.js.map

package/dist/animation/ik/ik_constraint.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ik_constraint.js","sources":["../../../src/animation/ik/ik_constraint.ts"],"sourcesContent":["import type { IKJoint } from './ik_joint';\r\n\r\n/**\r\n * Base class for IK constraints.\r\n *\r\n * Constraints are applied after each FABRIK iteration to enforce\r\n * joint limitations (angle limits, pole vectors, etc.).\r\n *\r\n * @public\r\n */\r\nexport abstract class IKConstraint {\r\n  /** The joint index this constraint applies to */\r\n  protected _jointIndex: number;\r\n\r\n  /**\r\n   * Create an IK constraint.\r\n   *\r\n   * @param jointIndex - Index of the joint in the chain (0 = root)\r\n   */\r\n  constructor(jointIndex: number) {\r\n    this._jointIndex = jointIndex;\r\n  }\r\n\r\n  /**\r\n   * Get the joint index this constraint applies to.\r\n   */\r\n  get jointIndex(): number {\r\n    return this._jointIndex;\r\n  }\r\n\r\n  /**\r\n   * Apply the constraint to the joint chain.\r\n   *\r\n   * This method modifies joint positions to satisfy the constraint.\r\n   *\r\n   * @param joints - Array of all joints in the chain\r\n   */\r\n  abstract apply(joints: IKJoint[]): void;\r\n}\r\n\r\n/**\r\n * Twist constraint configuration for a joint.\r\n *\r\n * @public\r\n */\r\nexport interface TwistConstraint {\r\n  /** Minimum twist angle in radians */\r\n  minTwist: number;\r\n  /** Maximum twist angle in radians */\r\n  maxTwist: number;\r\n  /** Smoothing factor [0-1], 0 = no smoothing, 1 = full smoothing */\r\n  smoothFactor: number;\r\n}\r\n"],"names":["IKConstraint","jointIndex","_jointIndex"],"mappings":"AAEA;;;;;;;AAOC,IACM,MAAeA,YAAAA,CAAAA;sDAEpB,WAA8B;AAE9B;;;;MAKA,WAAA,CAAYC,UAAkB,CAAE;QAC9B,IAAI,CAACC,WAAW,GAAGD,UAAAA;AACrB;AAEA;;AAEC,MACD,IAAIA,UAAqB,GAAA;QACvB,OAAO,IAAI,CAACC,WAAW;AACzB;AAUF;;;;"}

package/dist/animation/ik/ik_pole_constraint.js

@@ -0,0 +1,123 @@
+import { Vector3 } from '@zephyr3d/base';
+import { IKConstraint } from './ik_constraint.js';
+
+/**
+ * Pole vector constraint for IK chains.
+ *
+ * Controls the twist/rotation of a joint chain by ensuring the middle joint
+ * bends toward a specified pole vector position.
+ *
+ * @remarks
+ * This is commonly used for arms and legs to control which direction
+ * the elbow or knee points. For example, ensuring an elbow points
+ * backward or a knee points forward.
+ *
+ * The pole vector defines a plane, and the middle joint is constrained
+ * to lie on this plane.
+ *
+ * @public
+ */ class IKPoleVectorConstraint extends IKConstraint {
+    /** The pole vector position in world space */ _poleVector;
+    /** Weight of the constraint (0 = no effect, 1 = full effect) */ _weight;
+    /**
+   * Create a pole vector constraint.
+   *
+   * @param jointIndex - Index of the middle joint to constrain (typically elbow or knee)
+   * @param poleVector - Position in world space that the joint should point toward
+   * @param weight - Constraint weight (0-1, default: 1)
+   */ constructor(jointIndex, poleVector, weight = 1){
+        super(jointIndex);
+        this._poleVector = poleVector.clone();
+        this._weight = Math.max(0, Math.min(1, weight));
+    }
+    /**
+   * Get the pole vector position.
+   */ get poleVector() {
+        return this._poleVector;
+    }
+    /**
+   * Set the pole vector position.
+   */ set poleVector(value) {
+        this._poleVector.set(value);
+    }
+    /**
+   * Get the constraint weight.
+   */ get weight() {
+        return this._weight;
+    }
+    /**
+   * Set the constraint weight (0-1).
+   */ set weight(value) {
+        this._weight = Math.max(0, Math.min(1, value));
+    }
+    /**
+   * Apply the pole vector constraint.
+   *
+   * This adjusts the middle joint position to align with the pole vector
+   * while maintaining bone lengths.
+   */ apply(joints) {
+        const index = this._jointIndex;
+        // Need at least 3 joints (parent, this, child)
+        if (index < 1 || index >= joints.length - 1) {
+            return;
+        }
+        if (this._weight < 0.001) {
+            return; // No effect
+        }
+        const parentJoint = joints[index - 1];
+        const currentJoint = joints[index];
+        const childJoint = joints[index + 1];
+        // Calculate the plane defined by parent, child, and pole vector
+        const parentPos = parentJoint.position;
+        const childPos = childJoint.position;
+        const currentPos = currentJoint.position;
+        // Vector from parent to child (the "line" we're bending around)
+        const parentToChild = Vector3.sub(childPos, parentPos, new Vector3());
+        const lineLength = parentToChild.magnitude;
+        if (lineLength < 0.000001) {
+            return; // Parent and child are at same position
+        }
+        const lineDir = Vector3.scale(parentToChild, 1 / lineLength, new Vector3());
+        // Project current joint onto the parent-child line
+        const parentToCurrent = Vector3.sub(currentPos, parentPos, new Vector3());
+        const projectionLength = Vector3.dot(parentToCurrent, lineDir);
+        const projectionPoint = Vector3.scale(lineDir, projectionLength, new Vector3());
+        projectionPoint.addBy(parentPos);
+        // Vector from projection point to current joint (perpendicular to line)
+        const perpendicular = Vector3.sub(currentPos, projectionPoint, new Vector3());
+        const perpLength = perpendicular.magnitude;
+        if (perpLength < 0.000001) {
+            return; // Current joint is on the line
+        }
+        // Calculate desired direction toward pole vector
+        const parentToPole = Vector3.sub(this._poleVector, parentPos, new Vector3());
+        const poleProjectionLength = Vector3.dot(parentToPole, lineDir);
+        const poleProjectionPoint = Vector3.scale(lineDir, poleProjectionLength, new Vector3());
+        poleProjectionPoint.addBy(parentPos);
+        // Direction from projection to pole (perpendicular to line)
+        const poleDirection = Vector3.sub(this._poleVector, poleProjectionPoint, new Vector3());
+        const poleDirLength = poleDirection.magnitude;
+        if (poleDirLength < 0.000001) {
+            return; // Pole is on the line
+        }
+        poleDirection.scaleBy(1 / poleDirLength);
+        // Calculate new position for current joint
+        // Keep the same distance from the line, but rotate toward pole direction
+        const desiredPerpendicular = Vector3.scale(poleDirection, perpLength, new Vector3());
+        const newPosition = Vector3.add(projectionPoint, desiredPerpendicular, new Vector3());
+        // Apply weight (blend between original and constrained position)
+        if (this._weight < 0.999) {
+            // Manual lerp: result = a + (b - a) * t
+            const blended = new Vector3();
+            blended.x = currentPos.x + (newPosition.x - currentPos.x) * this._weight;
+            blended.y = currentPos.y + (newPosition.y - currentPos.y) * this._weight;
+            blended.z = currentPos.z + (newPosition.z - currentPos.z) * this._weight;
+            currentJoint.position.set(blended);
+        } else {
+            currentJoint.position.set(newPosition);
+        }
+    }
+}
+
+export { IKPoleVectorConstraint };
+//# sourceMappingURL=ik_pole_constraint.js.map