@zephyr3d/scene 0.7.1 → 0.8.1

package/dist/animation/ik/ik_utils.js

@@ -0,0 +1,191 @@
+import { Vector3, Quaternion } from '@zephyr3d/base';
+
+/**
+ * Utility functions for IK calculations.
+ *
+ * @internal
+ */ class IKUtils {
+    /**
+   * Calculate the rotation needed to align 'from' direction to 'to' direction.
+   *
+   * @param from - Starting direction vector
+   * @param to - Target direction vector
+   * @param result - Output quaternion
+   * @returns The rotation quaternion
+   */ static fromToRotation(from, to, result) {
+        const fromNorm = Vector3.normalize(from, new Vector3());
+        const toNorm = Vector3.normalize(to, new Vector3());
+        const dot = Vector3.dot(fromNorm, toNorm);
+        // Vectors are parallel
+        if (dot >= 0.999999) {
+            return result.identity();
+        }
+        // Vectors are opposite
+        if (dot <= -0.999999) {
+            // Find an orthogonal axis
+            let axis = Vector3.cross(Vector3.axisPX(), fromNorm, new Vector3());
+            const lenSq = axis.x * axis.x + axis.y * axis.y + axis.z * axis.z;
+            if (lenSq < 0.000001) {
+                axis = Vector3.cross(Vector3.axisPY(), fromNorm, new Vector3());
+            }
+            axis.inplaceNormalize();
+            return result.fromAxisAngle(axis, Math.PI);
+        }
+        // General case
+        const axis = Vector3.cross(fromNorm, toNorm).inplaceNormalize();
+        const angle = Math.acos(dot);
+        return result.fromAxisAngle(axis, angle);
+    }
+    /**
+   * Calculate bone length between two positions.
+   *
+   * @param start - Start position
+   * @param end - End position
+   * @returns Distance between positions
+   */ static calculateBoneLength(start, end) {
+        return Vector3.distance(start, end);
+    }
+    /**
+   * Clamp twist angle and optionally smooth with previous twist.
+   *
+   * @param currentTwist - Current twist angle in radians
+   * @param previousTwist - Previous frame's twist angle in radians (optional)
+   * @param minTwist - Minimum allowed twist angle in radians
+   * @param maxTwist - Maximum allowed twist angle in radians
+   * @param smoothFactor - Smoothing factor [0-1], 0 = no smoothing, 1 = full smoothing
+   * @returns Clamped and smoothed twist angle
+   */ static clampAndSmoothTwist(currentTwist, previousTwist, minTwist, maxTwist, smoothFactor = 0.5) {
+        // Clamp to range
+        let clampedTwist = Math.max(minTwist, Math.min(maxTwist, currentTwist));
+        // Smooth with previous frame if available
+        if (previousTwist !== undefined && smoothFactor > 0.001) {
+            // Normalize angle difference to [-PI, PI]
+            let diff = clampedTwist - previousTwist;
+            while(diff > Math.PI){
+                diff -= 2 * Math.PI;
+            }
+            while(diff < -Math.PI){
+                diff += 2 * Math.PI;
+            }
+            // Lerp
+            clampedTwist = previousTwist + diff * (1 - smoothFactor);
+        }
+        return clampedTwist;
+    }
+    /**
+   * Calculate a look-at rotation with twist constraint using a pole vector.
+   *
+   * @remarks
+   * This creates a rotation that:
+   * 1. Aligns 'forward' direction to 'targetDir'
+   * 2. Keeps the perpendicular plane aligned with 'poleDir'
+   *
+   * This prevents unwanted twist around the bone axis by using an external
+   * reference direction (pole vector) rather than relying on previous rotations.
+   *
+   * @param forward - Current forward direction (will be aligned to targetDir)
+   * @param targetDir - Desired forward direction
+   * @param poleDir - Direction that should be in the "up" hemisphere (from joint position)
+   * @param result - Output quaternion
+   * @returns The rotation quaternion
+   */ static lookAtRotationWithPole(forward, targetDir, poleDir, result) {
+        const forwardNorm = Vector3.normalize(forward, new Vector3());
+        const targetDirNorm = Vector3.normalize(targetDir, new Vector3());
+        const poleDirNorm = Vector3.normalize(poleDir, new Vector3());
+        // First, align forward to targetDir (swing rotation)
+        const swingRotation = new Quaternion();
+        this.fromToRotation(forwardNorm, targetDirNorm, swingRotation);
+        // Calculate the "right" vector perpendicular to targetDir and poleDir
+        // This defines the plane that the bone should bend in
+        const right = Vector3.cross(targetDirNorm, poleDirNorm, new Vector3());
+        const rightLenSq = right.x * right.x + right.y * right.y + right.z * right.z;
+        // If pole is parallel to target direction, no twist correction possible
+        if (rightLenSq < 0.000001) {
+            result.set(swingRotation);
+            return result;
+        }
+        right.scaleBy(1 / Math.sqrt(rightLenSq));
+        // Calculate the "up" vector perpendicular to targetDir in the pole plane
+        const up = Vector3.cross(right, targetDirNorm, new Vector3()).inplaceNormalize();
+        // Now we need to find the twist rotation around targetDir
+        // We want the local "up" axis to align with the calculated "up" vector
+        // Get a perpendicular vector to forward in the original space
+        let originalUp = Vector3.cross(forwardNorm, Vector3.axisPY(), new Vector3());
+        const originalUpLenSq = originalUp.x * originalUp.x + originalUp.y * originalUp.y + originalUp.z * originalUp.z;
+        if (originalUpLenSq < 0.000001) {
+            originalUp = Vector3.cross(forwardNorm, Vector3.axisPX(), new Vector3());
+        }
+        originalUp.inplaceNormalize();
+        // Rotate originalUp by swing rotation to see where it ends up
+        const rotatedUp = swingRotation.transform(originalUp, new Vector3());
+        // Project rotatedUp onto the plane perpendicular to targetDir
+        const rotatedUpDot = Vector3.dot(rotatedUp, targetDirNorm);
+        const rotatedUpProj = Vector3.scale(targetDirNorm, rotatedUpDot, new Vector3());
+        const rotatedUpPerp = Vector3.sub(rotatedUp, rotatedUpProj, new Vector3());
+        const rotatedUpPerpLen = rotatedUpPerp.magnitude;
+        if (rotatedUpPerpLen < 0.000001) {
+            result.set(swingRotation);
+            return result;
+        }
+        rotatedUpPerp.scaleBy(1 / rotatedUpPerpLen);
+        // Calculate twist rotation to align rotatedUpPerp with up
+        const twistRotation = new Quaternion();
+        this.fromToRotation(rotatedUpPerp, up, twistRotation);
+        // Combine swing and twist
+        return Quaternion.multiply(twistRotation, swingRotation, result);
+    }
+    /**
+   * Calculate a look-at rotation with twist constraint.
+   *
+   * @remarks
+   * This creates a rotation that:
+   * 1. Aligns 'forward' direction to 'targetDir'
+   * 2. Keeps 'up' direction as close as possible to 'targetUp'
+   *
+   * This prevents unwanted twist around the bone axis.
+   *
+   * @param forward - Current forward direction (will be aligned to targetDir)
+   * @param targetDir - Desired forward direction
+   * @param up - Current up direction (perpendicular to forward)
+   * @param targetUp - Desired up direction (will be projected perpendicular to targetDir)
+   * @param result - Output quaternion
+   * @returns The rotation quaternion
+   */ static lookAtRotation(forward, targetDir, up, targetUp, result) {
+        const forwardNorm = Vector3.normalize(forward, new Vector3());
+        const targetDirNorm = Vector3.normalize(targetDir, new Vector3());
+        // First, align forward to targetDir (swing rotation)
+        const swingRotation = new Quaternion();
+        this.fromToRotation(forwardNorm, targetDirNorm, swingRotation);
+        // Rotate the up vector by swing rotation
+        const rotatedUp = swingRotation.transform(up, new Vector3());
+        // Project targetUp onto plane perpendicular to targetDir
+        const dot = Vector3.dot(targetUp, targetDirNorm);
+        const projection = Vector3.scale(targetDirNorm, dot, new Vector3());
+        const targetUpPerp = Vector3.sub(targetUp, projection, new Vector3());
+        const targetUpPerpLen = targetUpPerp.magnitude;
+        // If targetUp is parallel to targetDir, no twist correction needed
+        if (targetUpPerpLen < 0.000001) {
+            result.set(swingRotation);
+            return result;
+        }
+        targetUpPerp.scaleBy(1 / targetUpPerpLen);
+        // Project rotatedUp onto the same plane
+        const rotatedUpDot = Vector3.dot(rotatedUp, targetDirNorm);
+        const rotatedUpProj = Vector3.scale(targetDirNorm, rotatedUpDot, new Vector3());
+        const rotatedUpPerp = Vector3.sub(rotatedUp, rotatedUpProj, new Vector3());
+        const rotatedUpPerpLen = rotatedUpPerp.magnitude;
+        if (rotatedUpPerpLen < 0.000001) {
+            result.set(swingRotation);
+            return result;
+        }
+        rotatedUpPerp.scaleBy(1 / rotatedUpPerpLen);
+        // Calculate twist rotation around targetDir
+        const twistRotation = new Quaternion();
+        this.fromToRotation(rotatedUpPerp, targetUpPerp, twistRotation);
+        // Combine swing and twist
+        return Quaternion.multiply(twistRotation, swingRotation, result);
+    }
+}
+
+export { IKUtils };
+//# sourceMappingURL=ik_utils.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ik_utils.js","sources":["../../../src/animation/ik/ik_utils.ts"],"sourcesContent":["import { Vector3, Quaternion } from '@zephyr3d/base';\r\n\r\n/**\r\n * Utility functions for IK calculations.\r\n *\r\n * @internal\r\n */\r\nexport class IKUtils {\r\n  /**\r\n   * Calculate the rotation needed to align 'from' direction to 'to' direction.\r\n   *\r\n   * @param from - Starting direction vector\r\n   * @param to - Target direction vector\r\n   * @param result - Output quaternion\r\n   * @returns The rotation quaternion\r\n   */\r\n  static fromToRotation(from: Vector3, to: Vector3, result: Quaternion): Quaternion {\r\n    const fromNorm = Vector3.normalize(from, new Vector3());\r\n    const toNorm = Vector3.normalize(to, new Vector3());\r\n\r\n    const dot = Vector3.dot(fromNorm, toNorm);\r\n\r\n    // Vectors are parallel\r\n    if (dot >= 0.999999) {\r\n      return result.identity();\r\n    }\r\n\r\n    // Vectors are opposite\r\n    if (dot <= -0.999999) {\r\n      // Find an orthogonal axis\r\n      let axis = Vector3.cross(Vector3.axisPX(), fromNorm, new Vector3());\r\n      const lenSq = axis.x * axis.x + axis.y * axis.y + axis.z * axis.z;\r\n      if (lenSq < 0.000001) {\r\n        axis = Vector3.cross(Vector3.axisPY(), fromNorm, new Vector3());\r\n      }\r\n      axis.inplaceNormalize();\r\n      return result.fromAxisAngle(axis, Math.PI);\r\n    }\r\n\r\n    // General case\r\n    const axis = Vector3.cross(fromNorm, toNorm).inplaceNormalize();\r\n    const angle = Math.acos(dot);\r\n    return result.fromAxisAngle(axis, angle);\r\n  }\r\n\r\n  /**\r\n   * Calculate bone length between two positions.\r\n   *\r\n   * @param start - Start position\r\n   * @param end - End position\r\n   * @returns Distance between positions\r\n   */\r\n  static calculateBoneLength(start: Vector3, end: Vector3): number {\r\n    return Vector3.distance(start, end);\r\n  }\r\n\r\n  /**\r\n   * Clamp twist angle and optionally smooth with previous twist.\r\n   *\r\n   * @param currentTwist - Current twist angle in radians\r\n   * @param previousTwist - Previous frame's twist angle in radians (optional)\r\n   * @param minTwist - Minimum allowed twist angle in radians\r\n   * @param maxTwist - Maximum allowed twist angle in radians\r\n   * @param smoothFactor - Smoothing factor [0-1], 0 = no smoothing, 1 = full smoothing\r\n   * @returns Clamped and smoothed twist angle\r\n   */\r\n  static clampAndSmoothTwist(\r\n    currentTwist: number,\r\n    previousTwist: number | undefined,\r\n    minTwist: number,\r\n    maxTwist: number,\r\n    smoothFactor: number = 0.5\r\n  ): number {\r\n    // Clamp to range\r\n    let clampedTwist = Math.max(minTwist, Math.min(maxTwist, currentTwist));\r\n\r\n    // Smooth with previous frame if available\r\n    if (previousTwist !== undefined && smoothFactor > 0.001) {\r\n      // Normalize angle difference to [-PI, PI]\r\n      let diff = clampedTwist - previousTwist;\r\n      while (diff > Math.PI) {\r\n        diff -= 2 * Math.PI;\r\n      }\r\n      while (diff < -Math.PI) {\r\n        diff += 2 * Math.PI;\r\n      }\r\n\r\n      // Lerp\r\n      clampedTwist = previousTwist + diff * (1 - smoothFactor);\r\n    }\r\n\r\n    return clampedTwist;\r\n  }\r\n\r\n  /**\r\n   * Calculate a look-at rotation with twist constraint using a pole vector.\r\n   *\r\n   * @remarks\r\n   * This creates a rotation that:\r\n   * 1. Aligns 'forward' direction to 'targetDir'\r\n   * 2. Keeps the perpendicular plane aligned with 'poleDir'\r\n   *\r\n   * This prevents unwanted twist around the bone axis by using an external\r\n   * reference direction (pole vector) rather than relying on previous rotations.\r\n   *\r\n   * @param forward - Current forward direction (will be aligned to targetDir)\r\n   * @param targetDir - Desired forward direction\r\n   * @param poleDir - Direction that should be in the \"up\" hemisphere (from joint position)\r\n   * @param result - Output quaternion\r\n   * @returns The rotation quaternion\r\n   */\r\n  static lookAtRotationWithPole(\r\n    forward: Vector3,\r\n    targetDir: Vector3,\r\n    poleDir: Vector3,\r\n    result: Quaternion\r\n  ): Quaternion {\r\n    const forwardNorm = Vector3.normalize(forward, new Vector3());\r\n    const targetDirNorm = Vector3.normalize(targetDir, new Vector3());\r\n    const poleDirNorm = Vector3.normalize(poleDir, new Vector3());\r\n\r\n    // First, align forward to targetDir (swing rotation)\r\n    const swingRotation = new Quaternion();\r\n    this.fromToRotation(forwardNorm, targetDirNorm, swingRotation);\r\n\r\n    // Calculate the \"right\" vector perpendicular to targetDir and poleDir\r\n    // This defines the plane that the bone should bend in\r\n    const right = Vector3.cross(targetDirNorm, poleDirNorm, new Vector3());\r\n    const rightLenSq = right.x * right.x + right.y * right.y + right.z * right.z;\r\n\r\n    // If pole is parallel to target direction, no twist correction possible\r\n    if (rightLenSq < 0.000001) {\r\n      result.set(swingRotation);\r\n      return result;\r\n    }\r\n\r\n    right.scaleBy(1 / Math.sqrt(rightLenSq));\r\n\r\n    // Calculate the \"up\" vector perpendicular to targetDir in the pole plane\r\n    const up = Vector3.cross(right, targetDirNorm, new Vector3()).inplaceNormalize();\r\n\r\n    // Now we need to find the twist rotation around targetDir\r\n    // We want the local \"up\" axis to align with the calculated \"up\" vector\r\n\r\n    // Get a perpendicular vector to forward in the original space\r\n    let originalUp = Vector3.cross(forwardNorm, Vector3.axisPY(), new Vector3());\r\n    const originalUpLenSq =\r\n      originalUp.x * originalUp.x + originalUp.y * originalUp.y + originalUp.z * originalUp.z;\r\n    if (originalUpLenSq < 0.000001) {\r\n      originalUp = Vector3.cross(forwardNorm, Vector3.axisPX(), new Vector3());\r\n    }\r\n    originalUp.inplaceNormalize();\r\n\r\n    // Rotate originalUp by swing rotation to see where it ends up\r\n    const rotatedUp = swingRotation.transform(originalUp, new Vector3());\r\n\r\n    // Project rotatedUp onto the plane perpendicular to targetDir\r\n    const rotatedUpDot = Vector3.dot(rotatedUp, targetDirNorm);\r\n    const rotatedUpProj = Vector3.scale(targetDirNorm, rotatedUpDot, new Vector3());\r\n    const rotatedUpPerp = Vector3.sub(rotatedUp, rotatedUpProj, new Vector3());\r\n    const rotatedUpPerpLen = rotatedUpPerp.magnitude;\r\n\r\n    if (rotatedUpPerpLen < 0.000001) {\r\n      result.set(swingRotation);\r\n      return result;\r\n    }\r\n\r\n    rotatedUpPerp.scaleBy(1 / rotatedUpPerpLen);\r\n\r\n    // Calculate twist rotation to align rotatedUpPerp with up\r\n    const twistRotation = new Quaternion();\r\n    this.fromToRotation(rotatedUpPerp, up, twistRotation);\r\n\r\n    // Combine swing and twist\r\n    return Quaternion.multiply(twistRotation, swingRotation, result);\r\n  }\r\n\r\n  /**\r\n   * Calculate a look-at rotation with twist constraint.\r\n   *\r\n   * @remarks\r\n   * This creates a rotation that:\r\n   * 1. Aligns 'forward' direction to 'targetDir'\r\n   * 2. Keeps 'up' direction as close as possible to 'targetUp'\r\n   *\r\n   * This prevents unwanted twist around the bone axis.\r\n   *\r\n   * @param forward - Current forward direction (will be aligned to targetDir)\r\n   * @param targetDir - Desired forward direction\r\n   * @param up - Current up direction (perpendicular to forward)\r\n   * @param targetUp - Desired up direction (will be projected perpendicular to targetDir)\r\n   * @param result - Output quaternion\r\n   * @returns The rotation quaternion\r\n   */\r\n  static lookAtRotation(\r\n    forward: Vector3,\r\n    targetDir: Vector3,\r\n    up: Vector3,\r\n    targetUp: Vector3,\r\n    result: Quaternion\r\n  ): Quaternion {\r\n    const forwardNorm = Vector3.normalize(forward, new Vector3());\r\n    const targetDirNorm = Vector3.normalize(targetDir, new Vector3());\r\n\r\n    // First, align forward to targetDir (swing rotation)\r\n    const swingRotation = new Quaternion();\r\n    this.fromToRotation(forwardNorm, targetDirNorm, swingRotation);\r\n\r\n    // Rotate the up vector by swing rotation\r\n    const rotatedUp = swingRotation.transform(up, new Vector3());\r\n\r\n    // Project targetUp onto plane perpendicular to targetDir\r\n    const dot = Vector3.dot(targetUp, targetDirNorm);\r\n    const projection = Vector3.scale(targetDirNorm, dot, new Vector3());\r\n    const targetUpPerp = Vector3.sub(targetUp, projection, new Vector3());\r\n    const targetUpPerpLen = targetUpPerp.magnitude;\r\n\r\n    // If targetUp is parallel to targetDir, no twist correction needed\r\n    if (targetUpPerpLen < 0.000001) {\r\n      result.set(swingRotation);\r\n      return result;\r\n    }\r\n\r\n    targetUpPerp.scaleBy(1 / targetUpPerpLen);\r\n\r\n    // Project rotatedUp onto the same plane\r\n    const rotatedUpDot = Vector3.dot(rotatedUp, targetDirNorm);\r\n    const rotatedUpProj = Vector3.scale(targetDirNorm, rotatedUpDot, new Vector3());\r\n    const rotatedUpPerp = Vector3.sub(rotatedUp, rotatedUpProj, new Vector3());\r\n    const rotatedUpPerpLen = rotatedUpPerp.magnitude;\r\n\r\n    if (rotatedUpPerpLen < 0.000001) {\r\n      result.set(swingRotation);\r\n      return result;\r\n    }\r\n\r\n    rotatedUpPerp.scaleBy(1 / rotatedUpPerpLen);\r\n\r\n    // Calculate twist rotation around targetDir\r\n    const twistRotation = new Quaternion();\r\n    this.fromToRotation(rotatedUpPerp, targetUpPerp, twistRotation);\r\n\r\n    // Combine swing and twist\r\n    return Quaternion.multiply(twistRotation, swingRotation, result);\r\n  }\r\n}\r\n"],"names":["IKUtils","fromToRotation","from","to","result","fromNorm","Vector3","normalize","toNorm","dot","identity","axis","cross","axisPX","lenSq","x","y","z","axisPY","inplaceNormalize","fromAxisAngle","Math","PI","angle","acos","calculateBoneLength","start","end","distance","clampAndSmoothTwist","currentTwist","previousTwist","minTwist","maxTwist","smoothFactor","clampedTwist","max","min","undefined","diff","lookAtRotationWithPole","forward","targetDir","poleDir","forwardNorm","targetDirNorm","poleDirNorm","swingRotation","Quaternion","right","rightLenSq","set","scaleBy","sqrt","up","originalUp","originalUpLenSq","rotatedUp","transform","rotatedUpDot","rotatedUpProj","scale","rotatedUpPerp","sub","rotatedUpPerpLen","magnitude","twistRotation","multiply","lookAtRotation","targetUp","projection","targetUpPerp","targetUpPerpLen"],"mappings":"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"}

package/dist/animation/ik/two_bone_ik_solver.js

@@ -0,0 +1,331 @@
+import { Vector3, Quaternion } from '@zephyr3d/base';
+import { IKSolver } from './ik_solver.js';
+import { IKUtils } from './ik_utils.js';
+
+/**
+ * Two Bone IK solver for chains with exactly 3 joints (2 bones).
+ *
+ * @remarks
+ * This solver uses an analytical solution specifically optimized for
+ * two-bone chains like arms (shoulder-elbow-wrist) or legs (hip-knee-ankle).
+ * It's faster and more stable than iterative methods like FABRIK for this case.
+ *
+ * The solver supports an optional pole vector to control the bending direction
+ * of the middle joint (elbow/knee).
+ *
+ * @public
+ */ class TwoBoneIKSolver extends IKSolver {
+    /** Optional pole vector position in world space */ _poleVector;
+    /** Weight of the pole vector constraint (0-1) */ _poleWeight;
+    /** Twist constraints for each joint (indexed by joint index) */ _twistConstraints;
+    /**
+   * Create a Two Bone IK solver.
+   *
+   * @param chain - The IK chain to solve (must have exactly 3 joints)
+   * @param poleVector - Optional pole vector position in world space
+   * @param poleWeight - Weight of the pole vector constraint (0-1, default: 1)
+   */ constructor(chain, poleVector = null, poleWeight = 1){
+        super(chain, 1, 0.001); // Two bone IK doesn't need iterations
+        if (chain.joints.length !== 3) {
+            throw new Error('Two Bone IK requires exactly 3 joints (2 bones)');
+        }
+        this._poleVector = poleVector ? poleVector.clone() : null;
+        this._poleWeight = Math.max(0, Math.min(1, poleWeight));
+        this._twistConstraints = new Map();
+        // Set default twist constraints
+        // Root joint (shoulder/hip) - moderate twist
+        this._twistConstraints.set(0, {
+            minTwist: -Math.PI * 0.25,
+            maxTwist: Math.PI * 0.25,
+            smoothFactor: 0.3
+        });
+        // Middle joint (elbow/knee) - very limited twist
+        this._twistConstraints.set(1, {
+            minTwist: -Math.PI * 0.15,
+            maxTwist: Math.PI * 0.15,
+            smoothFactor: 0.3
+        });
+    }
+    /**
+   * Set twist constraint for a specific joint.
+   *
+   * @param jointIndex - Index of the joint (0 = root, 1 = middle)
+   * @param minTwist - Minimum twist angle in radians
+   * @param maxTwist - Maximum twist angle in radians
+   * @param smoothFactor - Smoothing factor [0-1] (default: 0.3)
+   */ setTwistConstraint(jointIndex, minTwist, maxTwist, smoothFactor = 0.3) {
+        if (jointIndex < 0 || jointIndex >= this._chain.joints.length - 1) {
+            throw new Error(`Invalid joint index: ${jointIndex}`);
+        }
+        this._twistConstraints.set(jointIndex, {
+            minTwist,
+            maxTwist,
+            smoothFactor: Math.max(0, Math.min(1, smoothFactor))
+        });
+    }
+    /**
+   * Get twist constraint for a specific joint.
+   *
+   * @param jointIndex - Index of the joint
+   * @returns Twist constraint or undefined if not set
+   */ getTwistConstraint(jointIndex) {
+        return this._twistConstraints.get(jointIndex);
+    }
+    /**
+   * Remove twist constraint for a specific joint.
+   *
+   * @param jointIndex - Index of the joint
+   * @returns True if a constraint was removed
+   */ removeTwistConstraint(jointIndex) {
+        return this._twistConstraints.delete(jointIndex);
+    }
+    /**
+   * Clear all twist constraints.
+   */ clearTwistConstraints() {
+        this._twistConstraints.clear();
+    }
+    /**
+   * Get the pole vector position.
+   */ get poleVector() {
+        return this._poleVector;
+    }
+    /**
+   * Set the pole vector position.
+   */ set poleVector(value) {
+        if (value) {
+            if (!this._poleVector) {
+                this._poleVector = value.clone();
+            } else {
+                this._poleVector.set(value);
+            }
+        } else {
+            this._poleVector = null;
+        }
+    }
+    /**
+   * Get the pole vector weight.
+   */ get poleWeight() {
+        return this._poleWeight;
+    }
+    /**
+   * Set the pole vector weight (0-1).
+   */ set poleWeight(value) {
+        this._poleWeight = Math.max(0, Math.min(1, value));
+    }
+    /**
+   * Solve the IK chain to reach the target position using Two Bone IK algorithm.
+   *
+   * @param target - Target position for the end effector
+   * @returns True if the target is reachable, false if stretched to maximum
+   */ solve(target) {
+        const joints = this._chain.joints;
+        // Update joint positions from scene nodes before solving
+        this._chain.updateFromNodes();
+        // Store original positions
+        this._chain.storeOriginalPositions();
+        const root = joints[0];
+        const middle = joints[1];
+        const end = joints[2];
+        const rootPos = root.position;
+        const upperLength = root.boneLength; // Length from root to middle
+        const lowerLength = middle.boneLength; // Length from middle to end
+        const totalLength = upperLength + lowerLength;
+        // Calculate direction and distance from root to target
+        const rootToTarget = Vector3.sub(target, rootPos, new Vector3());
+        const targetDistance = rootToTarget.magnitude;
+        // Check if target is reachable
+        if (targetDistance < 0.000001) {
+            // Target is at root position, keep original pose
+            return true;
+        }
+        let reachable = true;
+        // If target is unreachable, clamp to maximum distance
+        let effectiveTarget = target;
+        if (targetDistance >= totalLength - 0.0001) {
+            // Stretch to maximum length
+            const direction = Vector3.scale(rootToTarget, 1 / targetDistance, new Vector3());
+            effectiveTarget = Vector3.add(rootPos, Vector3.scale(direction, totalLength - 0.0001, new Vector3()), new Vector3());
+            reachable = false;
+        }
+        // Calculate the distance from root to effective target
+        const rootToEffectiveTarget = Vector3.sub(effectiveTarget, rootPos, new Vector3());
+        const distance = rootToEffectiveTarget.magnitude;
+        // Use law of cosines to find the angle at the root joint
+        // cos(rootAngle) = (a² + c² - b²) / (2ac)
+        const cosRootAngle = (upperLength * upperLength + distance * distance - lowerLength * lowerLength) / (2 * upperLength * distance);
+        const clampedCosRootAngle = Math.max(-1, Math.min(1, cosRootAngle));
+        const rootAngle = Math.acos(clampedCosRootAngle);
+        // Determine the plane of bending
+        let bendNormal;
+        if (this._poleVector && this._poleWeight > 0.001) {
+            // Use pole vector to determine bend direction
+            const rootToTargetDir = Vector3.normalize(rootToEffectiveTarget, new Vector3());
+            const rootToPole = Vector3.sub(this._poleVector, rootPos, new Vector3());
+            // Project pole vector onto plane perpendicular to root-target direction
+            const projectionLength = Vector3.dot(rootToPole, rootToTargetDir);
+            const projection = Vector3.scale(rootToTargetDir, projectionLength, new Vector3());
+            const perpendicular = Vector3.sub(rootToPole, projection, new Vector3());
+            const perpLength = perpendicular.magnitude;
+            if (perpLength > 0.000001) {
+                // Bend normal is perpendicular to both root-target and pole direction
+                bendNormal = Vector3.cross(rootToTargetDir, perpendicular, new Vector3()).inplaceNormalize();
+            } else {
+                // Pole is on the line, use default bend direction
+                bendNormal = this._getDefaultBendNormal(rootToEffectiveTarget);
+            }
+            // Apply pole weight
+            if (this._poleWeight < 0.999) {
+                const defaultNormal = this._getDefaultBendNormal(rootToEffectiveTarget);
+                // Slerp between default and pole-based normal
+                const angle = Math.acos(Math.max(-1, Math.min(1, Vector3.dot(defaultNormal, bendNormal))));
+                if (angle > 0.001) {
+                    const axis = Vector3.cross(defaultNormal, bendNormal, new Vector3()).inplaceNormalize();
+                    const rotation = new Quaternion().fromAxisAngle(axis, angle * this._poleWeight);
+                    bendNormal = rotation.transform(defaultNormal, new Vector3());
+                }
+            }
+        } else {
+            // No pole vector, use default bend direction
+            bendNormal = this._getDefaultBendNormal(rootToEffectiveTarget);
+        }
+        // Calculate middle joint position
+        const rootToTargetDir = Vector3.normalize(rootToEffectiveTarget, new Vector3());
+        // Rotate root-to-target direction by rootAngle around bendNormal
+        const rotationToMiddle = new Quaternion().fromAxisAngle(bendNormal, rootAngle);
+        const rootToMiddleDir = rotationToMiddle.transform(rootToTargetDir, new Vector3());
+        // Place middle joint
+        middle.position.set(Vector3.add(rootPos, Vector3.scale(rootToMiddleDir, upperLength, new Vector3()), new Vector3()));
+        // Place end joint at target
+        end.position.set(effectiveTarget);
+        // Apply constraints after solving
+        // Note: Constraints may modify joint positions, which could affect bone lengths
+        // For Two Bone IK, we apply constraints and then restore bone lengths
+        this._applyConstraints();
+        return reachable;
+    }
+    /**
+   * Apply all constraints to the joint chain.
+   * After applying constraints, we need to restore bone lengths.
+   */ _applyConstraints() {
+        const constraints = this._chain.constraints;
+        if (constraints.length === 0) {
+            return;
+        }
+        const joints = this._chain.joints;
+        // Apply each constraint
+        for (const constraint of constraints){
+            constraint.apply(joints);
+        }
+        // After constraints are applied, we need to restore bone lengths
+        // because constraints may have moved joints in ways that change bone lengths
+        // For Two Bone IK, we fix this by adjusting positions while maintaining the constraint
+        this._restoreBoneLengths();
+    }
+    /**
+   * Restore bone lengths after constraints have been applied.
+   * This ensures that the chain maintains correct bone lengths.
+   */ _restoreBoneLengths() {
+        const joints = this._chain.joints;
+        const root = joints[0];
+        const middle = joints[1];
+        const end = joints[2];
+        const upperLength = root.boneLength;
+        const lowerLength = middle.boneLength;
+        // Fix middle joint position to maintain upper bone length
+        const rootToMiddle = Vector3.sub(middle.position, root.position, new Vector3());
+        const rootToMiddleDist = rootToMiddle.magnitude;
+        if (rootToMiddleDist > 0.000001 && Math.abs(rootToMiddleDist - upperLength) > 0.0001) {
+            const rootToMiddleDir = Vector3.scale(rootToMiddle, 1 / rootToMiddleDist, new Vector3());
+            middle.position.set(Vector3.add(root.position, Vector3.scale(rootToMiddleDir, upperLength, new Vector3()), new Vector3()));
+        }
+        // Fix end joint position to maintain lower bone length
+        const middleToEnd = Vector3.sub(end.position, middle.position, new Vector3());
+        const middleToEndDist = middleToEnd.magnitude;
+        if (middleToEndDist > 0.000001 && Math.abs(middleToEndDist - lowerLength) > 0.0001) {
+            const middleToEndDir = Vector3.scale(middleToEnd, 1 / middleToEndDist, new Vector3());
+            end.position.set(Vector3.add(middle.position, Vector3.scale(middleToEndDir, lowerLength, new Vector3()), new Vector3()));
+        }
+    }
+    /**
+   * Apply the solved joint positions to scene nodes as rotations.
+   *
+   * @param weight - Blend weight (0 = original, 1 = full IK, default: 1)
+   */ applyToNodes(weight = 1) {
+        const joints = this._chain.joints;
+        // Apply rotation for root and middle joints (end joint doesn't need rotation)
+        for(let i = 0; i < joints.length - 1; i++){
+            const joint = joints[i];
+            const nextJoint = joints[i + 1];
+            // Calculate direction from current joint to next joint in world space
+            const originalDir = Vector3.sub(nextJoint.originalPosition, joint.originalPosition, new Vector3());
+            const newDir = Vector3.sub(nextJoint.position, joint.position, new Vector3());
+            const originalDirNorm = Vector3.normalize(originalDir, new Vector3());
+            const newDirNorm = Vector3.normalize(newDir, new Vector3());
+            // Calculate basic rotation
+            const deltaRotation = new Quaternion();
+            IKUtils.fromToRotation(originalDirNorm, newDirNorm, deltaRotation);
+            // Calculate new world rotation
+            let worldRotation = Quaternion.multiply(deltaRotation, joint.originalRotation, new Quaternion());
+            // Apply swing-twist constraint to prevent over-rotation
+            // Decompose rotation around bone axis
+            const swing = new Quaternion();
+            const twist = new Quaternion();
+            worldRotation.decomposeSwingTwist(newDirNorm, swing, twist);
+            // Get twist angle
+            let twistAngle = twist.getTwistAngle(newDirNorm);
+            // Get twist constraint for this joint
+            const constraint = this._twistConstraints.get(i);
+            if (constraint) {
+                // Clamp and smooth twist
+                twistAngle = IKUtils.clampAndSmoothTwist(twistAngle, joint.previousTwist, constraint.minTwist, constraint.maxTwist, constraint.smoothFactor);
+            }
+            // Store for next frame
+            joint.previousTwist = twistAngle;
+            // Reconstruct rotation from clamped twist: Q = Twist * Swing
+            const clampedTwist = Quaternion.fromAxisAngle(newDirNorm, twistAngle);
+            worldRotation = Quaternion.multiply(clampedTwist, swing, worldRotation);
+            // Blend with original rotation based on weight
+            if (weight < 1) {
+                Quaternion.slerp(joint.originalRotation, worldRotation, weight, worldRotation);
+            }
+            // Store this frame's world rotation for next frame's twist continuity
+            if (!joint.previousIKRotation) {
+                joint.previousIKRotation = worldRotation.clone();
+            } else {
+                joint.previousIKRotation.set(worldRotation);
+            }
+            // Convert world rotation to local rotation (relative to parent)
+            if (joint.node.parent) {
+                const parentWorldRotation = new Quaternion();
+                joint.node.parent.worldMatrix.decompose(null, parentWorldRotation, null);
+                // localRotation = conjugate(parentWorldRotation) * worldRotation
+                const parentInvRotation = Quaternion.conjugate(parentWorldRotation, new Quaternion());
+                const localRotation = Quaternion.multiply(parentInvRotation, worldRotation, new Quaternion());
+                joint.node.rotation = localRotation;
+            } else {
+                // Root node has no parent, world rotation is local rotation
+                joint.node.rotation = worldRotation;
+            }
+        }
+    }
+    /**
+   * Get a default bend normal when no pole vector is specified.
+   * This tries to find a reasonable perpendicular direction.
+   *
+   * @param rootToTarget - Direction from root to target
+   * @returns A normalized perpendicular vector
+   */ _getDefaultBendNormal(rootToTarget) {
+        const rootToTargetDir = Vector3.normalize(rootToTarget, new Vector3());
+        // Try to use world up (Y axis) as reference
+        let bendNormal = Vector3.cross(rootToTargetDir, Vector3.axisPY(), new Vector3());
+        const lenSq = bendNormal.x * bendNormal.x + bendNormal.y * bendNormal.y + bendNormal.z * bendNormal.z;
+        // If root-to-target is parallel to Y axis, use X axis instead
+        if (lenSq < 0.000001) {
+            bendNormal = Vector3.cross(rootToTargetDir, Vector3.axisPX(), new Vector3());
+        }
+        return bendNormal.inplaceNormalize();
+    }
+}
+
+export { TwoBoneIKSolver };
+//# sourceMappingURL=two_bone_ik_solver.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"two_bone_ik_solver.js","sources":["../../../src/animation/ik/two_bone_ik_solver.ts"],"sourcesContent":["import { Vector3, Quaternion } from '@zephyr3d/base';\r\nimport { IKSolver } from './ik_solver';\r\nimport type { IKChain } from './ik_chain';\r\nimport { IKUtils } from './ik_utils';\r\nimport type { TwistConstraint } from './ik_constraint';\r\n\r\n/**\r\n * Two Bone IK solver for chains with exactly 3 joints (2 bones).\r\n *\r\n * @remarks\r\n * This solver uses an analytical solution specifically optimized for\r\n * two-bone chains like arms (shoulder-elbow-wrist) or legs (hip-knee-ankle).\r\n * It's faster and more stable than iterative methods like FABRIK for this case.\r\n *\r\n * The solver supports an optional pole vector to control the bending direction\r\n * of the middle joint (elbow/knee).\r\n *\r\n * @public\r\n */\r\nexport class TwoBoneIKSolver extends IKSolver {\r\n  /** Optional pole vector position in world space */\r\n  private _poleVector: Vector3 | null;\r\n  /** Weight of the pole vector constraint (0-1) */\r\n  private _poleWeight: number;\r\n  /** Twist constraints for each joint (indexed by joint index) */\r\n  private _twistConstraints: Map<number, TwistConstraint>;\r\n\r\n  /**\r\n   * Create a Two Bone IK solver.\r\n   *\r\n   * @param chain - The IK chain to solve (must have exactly 3 joints)\r\n   * @param poleVector - Optional pole vector position in world space\r\n   * @param poleWeight - Weight of the pole vector constraint (0-1, default: 1)\r\n   */\r\n  constructor(chain: IKChain, poleVector: Vector3 | null = null, poleWeight = 1) {\r\n    super(chain, 1, 0.001); // Two bone IK doesn't need iterations\r\n\r\n    if (chain.joints.length !== 3) {\r\n      throw new Error('Two Bone IK requires exactly 3 joints (2 bones)');\r\n    }\r\n\r\n    this._poleVector = poleVector ? poleVector.clone() : null;\r\n    this._poleWeight = Math.max(0, Math.min(1, poleWeight));\r\n    this._twistConstraints = new Map();\r\n\r\n    // Set default twist constraints\r\n    // Root joint (shoulder/hip) - moderate twist\r\n    this._twistConstraints.set(0, {\r\n      minTwist: -Math.PI * 0.25, // -45 degrees\r\n      maxTwist: Math.PI * 0.25, // +45 degrees\r\n      smoothFactor: 0.3\r\n    });\r\n\r\n    // Middle joint (elbow/knee) - very limited twist\r\n    this._twistConstraints.set(1, {\r\n      minTwist: -Math.PI * 0.15, // -27 degrees\r\n      maxTwist: Math.PI * 0.15, // +27 degrees\r\n      smoothFactor: 0.3\r\n    });\r\n  }\r\n\r\n  /**\r\n   * Set twist constraint for a specific joint.\r\n   *\r\n   * @param jointIndex - Index of the joint (0 = root, 1 = middle)\r\n   * @param minTwist - Minimum twist angle in radians\r\n   * @param maxTwist - Maximum twist angle in radians\r\n   * @param smoothFactor - Smoothing factor [0-1] (default: 0.3)\r\n   */\r\n  setTwistConstraint(\r\n    jointIndex: number,\r\n    minTwist: number,\r\n    maxTwist: number,\r\n    smoothFactor: number = 0.3\r\n  ): void {\r\n    if (jointIndex < 0 || jointIndex >= this._chain.joints.length - 1) {\r\n      throw new Error(`Invalid joint index: ${jointIndex}`);\r\n    }\r\n\r\n    this._twistConstraints.set(jointIndex, {\r\n      minTwist,\r\n      maxTwist,\r\n      smoothFactor: Math.max(0, Math.min(1, smoothFactor))\r\n    });\r\n  }\r\n\r\n  /**\r\n   * Get twist constraint for a specific joint.\r\n   *\r\n   * @param jointIndex - Index of the joint\r\n   * @returns Twist constraint or undefined if not set\r\n   */\r\n  getTwistConstraint(jointIndex: number): TwistConstraint | undefined {\r\n    return this._twistConstraints.get(jointIndex);\r\n  }\r\n\r\n  /**\r\n   * Remove twist constraint for a specific joint.\r\n   *\r\n   * @param jointIndex - Index of the joint\r\n   * @returns True if a constraint was removed\r\n   */\r\n  removeTwistConstraint(jointIndex: number): boolean {\r\n    return this._twistConstraints.delete(jointIndex);\r\n  }\r\n\r\n  /**\r\n   * Clear all twist constraints.\r\n   */\r\n  clearTwistConstraints(): void {\r\n    this._twistConstraints.clear();\r\n  }\r\n\r\n  /**\r\n   * Get the pole vector position.\r\n   */\r\n  get poleVector(): Vector3 | null {\r\n    return this._poleVector;\r\n  }\r\n\r\n  /**\r\n   * Set the pole vector position.\r\n   */\r\n  set poleVector(value: Vector3 | null) {\r\n    if (value) {\r\n      if (!this._poleVector) {\r\n        this._poleVector = value.clone();\r\n      } else {\r\n        this._poleVector.set(value);\r\n      }\r\n    } else {\r\n      this._poleVector = null;\r\n    }\r\n  }\r\n\r\n  /**\r\n   * Get the pole vector weight.\r\n   */\r\n  get poleWeight(): number {\r\n    return this._poleWeight;\r\n  }\r\n\r\n  /**\r\n   * Set the pole vector weight (0-1).\r\n   */\r\n  set poleWeight(value: number) {\r\n    this._poleWeight = Math.max(0, Math.min(1, value));\r\n  }\r\n\r\n  /**\r\n   * Solve the IK chain to reach the target position using Two Bone IK algorithm.\r\n   *\r\n   * @param target - Target position for the end effector\r\n   * @returns True if the target is reachable, false if stretched to maximum\r\n   */\r\n  solve(target: Vector3): boolean {\r\n    const joints = this._chain.joints;\r\n\r\n    // Update joint positions from scene nodes before solving\r\n    this._chain.updateFromNodes();\r\n\r\n    // Store original positions\r\n    this._chain.storeOriginalPositions();\r\n\r\n    const root = joints[0];\r\n    const middle = joints[1];\r\n    const end = joints[2];\r\n\r\n    const rootPos = root.position;\r\n    const upperLength = root.boneLength; // Length from root to middle\r\n    const lowerLength = middle.boneLength; // Length from middle to end\r\n    const totalLength = upperLength + lowerLength;\r\n\r\n    // Calculate direction and distance from root to target\r\n    const rootToTarget = Vector3.sub(target, rootPos, new Vector3());\r\n    const targetDistance = rootToTarget.magnitude;\r\n\r\n    // Check if target is reachable\r\n    if (targetDistance < 0.000001) {\r\n      // Target is at root position, keep original pose\r\n      return true;\r\n    }\r\n\r\n    let reachable = true;\r\n\r\n    // If target is unreachable, clamp to maximum distance\r\n    let effectiveTarget = target;\r\n    if (targetDistance >= totalLength - 0.0001) {\r\n      // Stretch to maximum length\r\n      const direction = Vector3.scale(rootToTarget, 1 / targetDistance, new Vector3());\r\n      effectiveTarget = Vector3.add(\r\n        rootPos,\r\n        Vector3.scale(direction, totalLength - 0.0001, new Vector3()),\r\n        new Vector3()\r\n      );\r\n      reachable = false;\r\n    }\r\n\r\n    // Calculate the distance from root to effective target\r\n    const rootToEffectiveTarget = Vector3.sub(effectiveTarget, rootPos, new Vector3());\r\n    const distance = rootToEffectiveTarget.magnitude;\r\n\r\n    // Use law of cosines to find the angle at the root joint\r\n    // cos(rootAngle) = (a² + c² - b²) / (2ac)\r\n    const cosRootAngle =\r\n      (upperLength * upperLength + distance * distance - lowerLength * lowerLength) /\r\n      (2 * upperLength * distance);\r\n    const clampedCosRootAngle = Math.max(-1, Math.min(1, cosRootAngle));\r\n    const rootAngle = Math.acos(clampedCosRootAngle);\r\n\r\n    // Determine the plane of bending\r\n    let bendNormal: Vector3;\r\n\r\n    if (this._poleVector && this._poleWeight > 0.001) {\r\n      // Use pole vector to determine bend direction\r\n      const rootToTargetDir = Vector3.normalize(rootToEffectiveTarget, new Vector3());\r\n      const rootToPole = Vector3.sub(this._poleVector, rootPos, new Vector3());\r\n\r\n      // Project pole vector onto plane perpendicular to root-target direction\r\n      const projectionLength = Vector3.dot(rootToPole, rootToTargetDir);\r\n      const projection = Vector3.scale(rootToTargetDir, projectionLength, new Vector3());\r\n      const perpendicular = Vector3.sub(rootToPole, projection, new Vector3());\r\n\r\n      const perpLength = perpendicular.magnitude;\r\n      if (perpLength > 0.000001) {\r\n        // Bend normal is perpendicular to both root-target and pole direction\r\n        bendNormal = Vector3.cross(rootToTargetDir, perpendicular, new Vector3()).inplaceNormalize();\r\n      } else {\r\n        // Pole is on the line, use default bend direction\r\n        bendNormal = this._getDefaultBendNormal(rootToEffectiveTarget);\r\n      }\r\n\r\n      // Apply pole weight\r\n      if (this._poleWeight < 0.999) {\r\n        const defaultNormal = this._getDefaultBendNormal(rootToEffectiveTarget);\r\n        // Slerp between default and pole-based normal\r\n        const angle = Math.acos(Math.max(-1, Math.min(1, Vector3.dot(defaultNormal, bendNormal))));\r\n        if (angle > 0.001) {\r\n          const axis = Vector3.cross(defaultNormal, bendNormal, new Vector3()).inplaceNormalize();\r\n          const rotation = new Quaternion().fromAxisAngle(axis, angle * this._poleWeight);\r\n          bendNormal = rotation.transform(defaultNormal, new Vector3());\r\n        }\r\n      }\r\n    } else {\r\n      // No pole vector, use default bend direction\r\n      bendNormal = this._getDefaultBendNormal(rootToEffectiveTarget);\r\n    }\r\n\r\n    // Calculate middle joint position\r\n    const rootToTargetDir = Vector3.normalize(rootToEffectiveTarget, new Vector3());\r\n\r\n    // Rotate root-to-target direction by rootAngle around bendNormal\r\n    const rotationToMiddle = new Quaternion().fromAxisAngle(bendNormal, rootAngle);\r\n    const rootToMiddleDir = rotationToMiddle.transform(rootToTargetDir, new Vector3());\r\n\r\n    // Place middle joint\r\n    middle.position.set(\r\n      Vector3.add(rootPos, Vector3.scale(rootToMiddleDir, upperLength, new Vector3()), new Vector3())\r\n    );\r\n\r\n    // Place end joint at target\r\n    end.position.set(effectiveTarget);\r\n\r\n    // Apply constraints after solving\r\n    // Note: Constraints may modify joint positions, which could affect bone lengths\r\n    // For Two Bone IK, we apply constraints and then restore bone lengths\r\n    this._applyConstraints();\r\n\r\n    return reachable;\r\n  }\r\n\r\n  /**\r\n   * Apply all constraints to the joint chain.\r\n   * After applying constraints, we need to restore bone lengths.\r\n   */\r\n  private _applyConstraints(): void {\r\n    const constraints = this._chain.constraints;\r\n    if (constraints.length === 0) {\r\n      return;\r\n    }\r\n\r\n    const joints = this._chain.joints;\r\n\r\n    // Apply each constraint\r\n    for (const constraint of constraints) {\r\n      constraint.apply(joints);\r\n    }\r\n\r\n    // After constraints are applied, we need to restore bone lengths\r\n    // because constraints may have moved joints in ways that change bone lengths\r\n    // For Two Bone IK, we fix this by adjusting positions while maintaining the constraint\r\n    this._restoreBoneLengths();\r\n  }\r\n\r\n  /**\r\n   * Restore bone lengths after constraints have been applied.\r\n   * This ensures that the chain maintains correct bone lengths.\r\n   */\r\n  private _restoreBoneLengths(): void {\r\n    const joints = this._chain.joints;\r\n    const root = joints[0];\r\n    const middle = joints[1];\r\n    const end = joints[2];\r\n\r\n    const upperLength = root.boneLength;\r\n    const lowerLength = middle.boneLength;\r\n\r\n    // Fix middle joint position to maintain upper bone length\r\n    const rootToMiddle = Vector3.sub(middle.position, root.position, new Vector3());\r\n    const rootToMiddleDist = rootToMiddle.magnitude;\r\n\r\n    if (rootToMiddleDist > 0.000001 && Math.abs(rootToMiddleDist - upperLength) > 0.0001) {\r\n      const rootToMiddleDir = Vector3.scale(rootToMiddle, 1 / rootToMiddleDist, new Vector3());\r\n      middle.position.set(\r\n        Vector3.add(root.position, Vector3.scale(rootToMiddleDir, upperLength, new Vector3()), new Vector3())\r\n      );\r\n    }\r\n\r\n    // Fix end joint position to maintain lower bone length\r\n    const middleToEnd = Vector3.sub(end.position, middle.position, new Vector3());\r\n    const middleToEndDist = middleToEnd.magnitude;\r\n\r\n    if (middleToEndDist > 0.000001 && Math.abs(middleToEndDist - lowerLength) > 0.0001) {\r\n      const middleToEndDir = Vector3.scale(middleToEnd, 1 / middleToEndDist, new Vector3());\r\n      end.position.set(\r\n        Vector3.add(middle.position, Vector3.scale(middleToEndDir, lowerLength, new Vector3()), new Vector3())\r\n      );\r\n    }\r\n  }\r\n\r\n  /**\r\n   * Apply the solved joint positions to scene nodes as rotations.\r\n   *\r\n   * @param weight - Blend weight (0 = original, 1 = full IK, default: 1)\r\n   */\r\n  applyToNodes(weight = 1): void {\r\n    const joints = this._chain.joints;\r\n\r\n    // Apply rotation for root and middle joints (end joint doesn't need rotation)\r\n    for (let i = 0; i < joints.length - 1; i++) {\r\n      const joint = joints[i];\r\n      const nextJoint = joints[i + 1];\r\n\r\n      // Calculate direction from current joint to next joint in world space\r\n      const originalDir = Vector3.sub(nextJoint.originalPosition, joint.originalPosition, new Vector3());\r\n      const newDir = Vector3.sub(nextJoint.position, joint.position, new Vector3());\r\n\r\n      const originalDirNorm = Vector3.normalize(originalDir, new Vector3());\r\n      const newDirNorm = Vector3.normalize(newDir, new Vector3());\r\n\r\n      // Calculate basic rotation\r\n      const deltaRotation = new Quaternion();\r\n      IKUtils.fromToRotation(originalDirNorm, newDirNorm, deltaRotation);\r\n\r\n      // Calculate new world rotation\r\n      let worldRotation = Quaternion.multiply(deltaRotation, joint.originalRotation, new Quaternion());\r\n\r\n      // Apply swing-twist constraint to prevent over-rotation\r\n      // Decompose rotation around bone axis\r\n      const swing = new Quaternion();\r\n      const twist = new Quaternion();\r\n      worldRotation.decomposeSwingTwist(newDirNorm, swing, twist);\r\n\r\n      // Get twist angle\r\n      let twistAngle = twist.getTwistAngle(newDirNorm);\r\n\r\n      // Get twist constraint for this joint\r\n      const constraint = this._twistConstraints.get(i);\r\n      if (constraint) {\r\n        // Clamp and smooth twist\r\n        twistAngle = IKUtils.clampAndSmoothTwist(\r\n          twistAngle,\r\n          joint.previousTwist,\r\n          constraint.minTwist,\r\n          constraint.maxTwist,\r\n          constraint.smoothFactor\r\n        );\r\n      }\r\n\r\n      // Store for next frame\r\n      joint.previousTwist = twistAngle;\r\n\r\n      // Reconstruct rotation from clamped twist: Q = Twist * Swing\r\n      const clampedTwist = Quaternion.fromAxisAngle(newDirNorm, twistAngle);\r\n      worldRotation = Quaternion.multiply(clampedTwist, swing, worldRotation);\r\n\r\n      // Blend with original rotation based on weight\r\n      if (weight < 1) {\r\n        Quaternion.slerp(joint.originalRotation, worldRotation, weight, worldRotation);\r\n      }\r\n\r\n      // Store this frame's world rotation for next frame's twist continuity\r\n      if (!joint.previousIKRotation) {\r\n        joint.previousIKRotation = worldRotation.clone();\r\n      } else {\r\n        joint.previousIKRotation.set(worldRotation);\r\n      }\r\n\r\n      // Convert world rotation to local rotation (relative to parent)\r\n      if (joint.node.parent) {\r\n        const parentWorldRotation = new Quaternion();\r\n        joint.node.parent.worldMatrix.decompose(null, parentWorldRotation, null);\r\n\r\n        // localRotation = conjugate(parentWorldRotation) * worldRotation\r\n        const parentInvRotation = Quaternion.conjugate(parentWorldRotation, new Quaternion());\r\n        const localRotation = Quaternion.multiply(parentInvRotation, worldRotation, new Quaternion());\r\n\r\n        joint.node.rotation = localRotation;\r\n      } else {\r\n        // Root node has no parent, world rotation is local rotation\r\n        joint.node.rotation = worldRotation;\r\n      }\r\n    }\r\n  }\r\n\r\n  /**\r\n   * Get a default bend normal when no pole vector is specified.\r\n   * This tries to find a reasonable perpendicular direction.\r\n   *\r\n   * @param rootToTarget - Direction from root to target\r\n   * @returns A normalized perpendicular vector\r\n   */\r\n  private _getDefaultBendNormal(rootToTarget: Vector3): Vector3 {\r\n    const rootToTargetDir = Vector3.normalize(rootToTarget, new Vector3());\r\n\r\n    // Try to use world up (Y axis) as reference\r\n    let bendNormal = Vector3.cross(rootToTargetDir, Vector3.axisPY(), new Vector3());\r\n    const lenSq = bendNormal.x * bendNormal.x + bendNormal.y * bendNormal.y + bendNormal.z * bendNormal.z;\r\n\r\n    // If root-to-target is parallel to Y axis, use X axis instead\r\n    if (lenSq < 0.000001) {\r\n      bendNormal = Vector3.cross(rootToTargetDir, Vector3.axisPX(), new Vector3());\r\n    }\r\n\r\n    return bendNormal.inplaceNormalize();\r\n  }\r\n}\r\n"],"names":["TwoBoneIKSolver","IKSolver","chain","poleVector","poleWeight","joints","length","Error","_poleVector","clone","_poleWeight","Math","max","min","_twistConstraints","Map","set","minTwist","PI","maxTwist","smoothFactor","setTwistConstraint","jointIndex","_chain","getTwistConstraint","get","removeTwistConstraint","delete","clearTwistConstraints","clear","value","solve","target","updateFromNodes","storeOriginalPositions","root","middle","end","rootPos","position","upperLength","boneLength","lowerLength","totalLength","rootToTarget","Vector3","sub","targetDistance","magnitude","reachable","effectiveTarget","direction","scale","add","rootToEffectiveTarget","distance","cosRootAngle","clampedCosRootAngle","rootAngle","acos","bendNormal","rootToTargetDir","normalize","rootToPole","projectionLength","dot","projection","perpendicular","perpLength","cross","inplaceNormalize","_getDefaultBendNormal","defaultNormal","angle","axis","rotation","Quaternion","fromAxisAngle","transform","rotationToMiddle","rootToMiddleDir","_applyConstraints","constraints","constraint","apply","_restoreBoneLengths","rootToMiddle","rootToMiddleDist","abs","middleToEnd","middleToEndDist","middleToEndDir","applyToNodes","weight","i","joint","nextJoint","originalDir","originalPosition","newDir","originalDirNorm","newDirNorm","deltaRotation","IKUtils","fromToRotation","worldRotation","multiply","originalRotation","swing","twist","decomposeSwingTwist","twistAngle","getTwistAngle","clampAndSmoothTwist","previousTwist","clampedTwist","slerp","previousIKRotation","node","parent","parentWorldRotation","worldMatrix","decompose","parentInvRotation","conjugate","localRotation","axisPY","lenSq","x","y","z","axisPX"],"mappings":"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"}