@redwilly/anima 0.1.0

package/dist/core/math/bezier/BezierPath.js

@@ -0,0 +1,264 @@
+import { Vector2 } from '../Vector2/Vector2';
+import { getTangentAtPath } from './sampling';
+import { getQuadraticLength, getCubicLength } from './length';
+import { evaluateQuadratic, evaluateCubic } from './evaluators';
+import { toCubicCommands, subdividePath } from './morphing';
+/**
+ * A class representing a Bezier path, capable of storing standard path commands
+ * (move, line, quadratic curve, cubic curve, close).
+ */
+export class BezierPath {
+    commands = [];
+    currentPoint = Vector2.ZERO;
+    startPoint = Vector2.ZERO;
+    // Caching for O(1) length and O(log N) point sampling
+    cachedLength = null;
+    segmentLengths = [];
+    segmentCDF = [];
+    /** Invalidates the cached length data. Called after any path modification. */
+    invalidateCache() {
+        this.cachedLength = null;
+        this.segmentLengths = [];
+        this.segmentCDF = [];
+    }
+    /** Builds the cache if not already valid. */
+    ensureCache() {
+        if (this.cachedLength !== null)
+            return;
+        this.segmentLengths = [];
+        this.segmentCDF = [];
+        let totalLength = 0;
+        let cursor = Vector2.ZERO;
+        let subpathStart = Vector2.ZERO;
+        for (const cmd of this.commands) {
+            let segmentLength = 0;
+            switch (cmd.type) {
+                case 'Move':
+                    cursor = cmd.end;
+                    subpathStart = cmd.end;
+                    break;
+                case 'Line':
+                    segmentLength = cursor.subtract(cmd.end).length();
+                    cursor = cmd.end;
+                    break;
+                case 'Quadratic':
+                    if (cmd.control1) {
+                        segmentLength = getQuadraticLength(cursor, cmd.control1, cmd.end);
+                    }
+                    cursor = cmd.end;
+                    break;
+                case 'Cubic':
+                    if (cmd.control1 && cmd.control2) {
+                        segmentLength = getCubicLength(cursor, cmd.control1, cmd.control2, cmd.end);
+                    }
+                    cursor = cmd.end;
+                    break;
+                case 'Close':
+                    segmentLength = cursor.subtract(subpathStart).length();
+                    cursor = subpathStart;
+                    break;
+            }
+            this.segmentLengths.push(segmentLength);
+            totalLength += segmentLength;
+            this.segmentCDF.push(totalLength);
+        }
+        this.cachedLength = totalLength;
+    }
+    /** Starts a new subpath at the specified point. */
+    moveTo(point) {
+        this.invalidateCache();
+        this.commands.push({ type: 'Move', end: point });
+        this.currentPoint = point;
+        this.startPoint = point;
+    }
+    lineTo(point) {
+        this.invalidateCache();
+        this.commands.push({ type: 'Line', end: point });
+        this.currentPoint = point;
+    }
+    quadraticTo(control, end) {
+        this.invalidateCache();
+        this.commands.push({ type: 'Quadratic', control1: control, end: end });
+        this.currentPoint = end;
+    }
+    cubicTo(control1, control2, end) {
+        this.invalidateCache();
+        this.commands.push({
+            type: 'Cubic',
+            control1: control1,
+            control2: control2,
+            end: end
+        });
+        this.currentPoint = end;
+    }
+    closePath() {
+        this.invalidateCache();
+        this.commands.push({ type: 'Close', end: this.startPoint });
+        this.currentPoint = this.startPoint;
+    }
+    getCommands() {
+        return [...this.commands];
+    }
+    getLength() {
+        this.ensureCache();
+        return this.cachedLength;
+    }
+    /** Returns the point on the path at the normalized position t (0-1). */
+    getPointAt(t) {
+        this.ensureCache();
+        const totalLength = this.cachedLength;
+        if (totalLength === 0 || this.commands.length === 0) {
+            return this.commands.length > 0 ? this.commands[this.commands.length - 1].end : Vector2.ZERO;
+        }
+        t = Math.max(0, Math.min(1, t));
+        const targetDistance = t * totalLength;
+        // Binary search for the segment containing targetDistance
+        let low = 0;
+        let high = this.segmentCDF.length - 1;
+        while (low < high) {
+            const mid = (low + high) >>> 1;
+            if (this.segmentCDF[mid] < targetDistance) {
+                low = mid + 1;
+            }
+            else {
+                high = mid;
+            }
+        }
+        const segmentIndex = low;
+        const cmd = this.commands[segmentIndex];
+        if (!cmd)
+            return Vector2.ZERO;
+        // Calculate the starting cursor for this segment
+        let cursor = Vector2.ZERO;
+        let subpathStart = Vector2.ZERO;
+        for (let i = 0; i < segmentIndex; i++) {
+            const c = this.commands[i];
+            if (c.type === 'Move') {
+                cursor = c.end;
+                subpathStart = c.end;
+            }
+            else if (c.type === 'Close') {
+                cursor = subpathStart;
+            }
+            else {
+                cursor = c.end;
+            }
+        }
+        // Calculate local t within this segment
+        const segmentStart = segmentIndex > 0 ? this.segmentCDF[segmentIndex - 1] : 0;
+        const segmentLength = this.segmentLengths[segmentIndex];
+        const localT = segmentLength > 0 ? (targetDistance - segmentStart) / segmentLength : 0;
+        // Evaluate the point at localT
+        switch (cmd.type) {
+            case 'Move':
+                return cmd.end;
+            case 'Line':
+                return cursor.lerp(cmd.end, localT);
+            case 'Quadratic':
+                if (cmd.control1) {
+                    return evaluateQuadratic(cursor, cmd.control1, cmd.end, localT);
+                }
+                return cmd.end;
+            case 'Cubic':
+                if (cmd.control1 && cmd.control2) {
+                    return evaluateCubic(cursor, cmd.control1, cmd.control2, cmd.end, localT);
+                }
+                return cmd.end;
+            case 'Close':
+                return cursor.lerp(subpathStart, localT);
+            default:
+                return cursor;
+        }
+    }
+    getTangentAt(t) {
+        return getTangentAtPath(this.commands, t);
+    }
+    getPoints(count) {
+        const points = [];
+        if (count <= 0)
+            return points;
+        if (count === 1)
+            return [this.getPointAt(0)];
+        for (let i = 0; i < count; i++) {
+            const t = i / (count - 1);
+            points.push(this.getPointAt(t));
+        }
+        return points;
+    }
+    getPointCount() {
+        return this.commands.length;
+    }
+    clone() {
+        const newPath = new BezierPath();
+        newPath.commands = this.commands.map(cmd => ({ ...cmd }));
+        newPath.currentPoint = this.currentPoint;
+        newPath.startPoint = this.startPoint;
+        return newPath;
+    }
+    /** Returns a new BezierPath where all segments are converted to Cubic curves. */
+    toCubic() {
+        const newPath = new BezierPath();
+        const cubicCmds = toCubicCommands(this.commands);
+        for (const cmd of cubicCmds) {
+            if (cmd.type === 'Move') {
+                newPath.moveTo(cmd.end);
+            }
+            else if (cmd.type === 'Cubic' && cmd.control1 && cmd.control2) {
+                newPath.cubicTo(cmd.control1, cmd.control2, cmd.end);
+            }
+        }
+        return newPath;
+    }
+    static interpolate(path1, path2, t) {
+        const [p1, p2] = BezierPath.matchPoints(path1, path2);
+        const result = new BezierPath();
+        const cmds1 = p1.commands;
+        const cmds2 = p2.commands;
+        for (let i = 0; i < cmds1.length; i++) {
+            const c1 = cmds1[i];
+            const c2 = cmds2[i];
+            if (c1.type === 'Move' && c2.type === 'Move') {
+                result.moveTo(c1.end.lerp(c2.end, t));
+            }
+            else if (c1.type === 'Cubic' && c2.type === 'Cubic') {
+                if (c1.control1 && c1.control2 && c2.control1 && c2.control2) {
+                    result.cubicTo(c1.control1.lerp(c2.control1, t), c1.control2.lerp(c2.control2, t), c1.end.lerp(c2.end, t));
+                }
+            }
+            else {
+                result.moveTo(c1.end.lerp(c2.end, t));
+            }
+        }
+        return result;
+    }
+    /** Matches the number of points/commands in two paths for morphing. */
+    static matchPoints(path1, path2) {
+        let p1 = path1.toCubic();
+        let p2 = path2.toCubic();
+        const count1 = p1.commands.length;
+        const count2 = p2.commands.length;
+        if (count1 === count2)
+            return [p1, p2];
+        if (count1 < count2) {
+            const subdivided = subdividePath(p1.commands, count2);
+            p1 = BezierPath.fromCommands(subdivided);
+        }
+        else {
+            const subdivided = subdividePath(p2.commands, count1);
+            p2 = BezierPath.fromCommands(subdivided);
+        }
+        return [p1, p2];
+    }
+    static fromCommands(commands) {
+        const path = new BezierPath();
+        for (const cmd of commands) {
+            if (cmd.type === 'Move') {
+                path.moveTo(cmd.end);
+            }
+            else if (cmd.type === 'Cubic' && cmd.control1 && cmd.control2) {
+                path.cubicTo(cmd.control1, cmd.control2, cmd.end);
+            }
+        }
+        return path;
+    }
+}

package/dist/core/math/bezier/evaluators.d.ts

@@ -0,0 +1,9 @@
+import { Vector2 } from '../Vector2/Vector2';
+/** Evaluates a point on a quadratic Bezier curve at parameter t (0-1). */
+export declare function evaluateQuadratic(p0: Vector2, p1: Vector2, p2: Vector2, t: number): Vector2;
+/** Evaluates a point on a cubic Bezier curve at parameter t (0-1). */
+export declare function evaluateCubic(p0: Vector2, p1: Vector2, p2: Vector2, p3: Vector2, t: number): Vector2;
+/** Evaluates the derivative of a quadratic Bezier curve at parameter t (0-1). */
+export declare function evaluateQuadraticDerivative(p0: Vector2, p1: Vector2, p2: Vector2, t: number): Vector2;
+/** Evaluates the derivative of a cubic Bezier curve at parameter t (0-1). */
+export declare function evaluateCubicDerivative(p0: Vector2, p1: Vector2, p2: Vector2, p3: Vector2, t: number): Vector2;

package/dist/core/math/bezier/evaluators.js

@@ -0,0 +1,36 @@
+/** Evaluates a point on a quadratic Bezier curve at parameter t (0-1). */
+export function evaluateQuadratic(p0, p1, p2, t) {
+    const oneMinusT = 1 - t;
+    // (1-t)^2 * p0 + 2(1-t)t * p1 + t^2 * p2
+    return p0.multiply(oneMinusT * oneMinusT)
+        .add(p1.multiply(2 * oneMinusT * t))
+        .add(p2.multiply(t * t));
+}
+/** Evaluates a point on a cubic Bezier curve at parameter t (0-1). */
+export function evaluateCubic(p0, p1, p2, p3, t) {
+    const oneMinusT = 1 - t;
+    const oneMinusT2 = oneMinusT * oneMinusT;
+    const oneMinusT3 = oneMinusT2 * oneMinusT;
+    const t2 = t * t;
+    const t3 = t2 * t;
+    // (1-t)^3 * p0 + 3(1-t)^2 * t * p1 + 3(1-t) * t^2 * p2 + t^3 * p3
+    return p0.multiply(oneMinusT3)
+        .add(p1.multiply(3 * oneMinusT2 * t))
+        .add(p2.multiply(3 * oneMinusT * t2))
+        .add(p3.multiply(t3));
+}
+/** Evaluates the derivative of a quadratic Bezier curve at parameter t (0-1). */
+export function evaluateQuadraticDerivative(p0, p1, p2, t) {
+    // 2(1-t)(p1-p0) + 2t(p2-p1)
+    const oneMinusT = 1 - t;
+    return p1.subtract(p0).multiply(2 * oneMinusT)
+        .add(p2.subtract(p1).multiply(2 * t));
+}
+/** Evaluates the derivative of a cubic Bezier curve at parameter t (0-1). */
+export function evaluateCubicDerivative(p0, p1, p2, p3, t) {
+    // 3(1-t)^2(p1-p0) + 6(1-t)t(p2-p1) + 3t^2(p3-p2)
+    const oneMinusT = 1 - t;
+    return p1.subtract(p0).multiply(3 * oneMinusT * oneMinusT)
+        .add(p2.subtract(p1).multiply(6 * oneMinusT * t))
+        .add(p3.subtract(p2).multiply(3 * t * t));
+}

package/dist/core/math/bezier/index.d.ts

@@ -0,0 +1,8 @@
+export type { PathCommandType, PathCommand } from './types';
+export { BezierPath } from './BezierPath';
+export { evaluateQuadratic, evaluateCubic, evaluateQuadraticDerivative, evaluateCubicDerivative } from './evaluators';
+export { getQuadraticLength, getCubicLength } from './length';
+export { getPathLength, getPointAtPath, getTangentAtPath } from './sampling';
+export { toCubicCommands, splitCubic, subdividePath } from './morphing';
+export { splitCubicAt, splitQuadraticAt } from './split';
+export type { CubicSegment, QuadraticSegment } from './split';

package/dist/core/math/bezier/index.js

@@ -0,0 +1,6 @@
+export { BezierPath } from './BezierPath';
+export { evaluateQuadratic, evaluateCubic, evaluateQuadraticDerivative, evaluateCubicDerivative } from './evaluators';
+export { getQuadraticLength, getCubicLength } from './length';
+export { getPathLength, getPointAtPath, getTangentAtPath } from './sampling';
+export { toCubicCommands, splitCubic, subdividePath } from './morphing';
+export { splitCubicAt, splitQuadraticAt } from './split';

package/dist/core/math/bezier/length.d.ts

@@ -0,0 +1,5 @@
+import { Vector2 } from '../Vector2/Vector2';
+/** Calculates approximate length of a quadratic Bezier curve via subdivision (10 steps). */
+export declare function getQuadraticLength(p0: Vector2, p1: Vector2, p2: Vector2): number;
+/** Calculates approximate length of a cubic Bezier curve via subdivision (20 steps). */
+export declare function getCubicLength(p0: Vector2, p1: Vector2, p2: Vector2, p3: Vector2): number;

package/dist/core/math/bezier/length.js

@@ -0,0 +1,27 @@
+import { evaluateQuadratic, evaluateCubic } from './evaluators';
+/** Calculates approximate length of a quadratic Bezier curve via subdivision (10 steps). */
+export function getQuadraticLength(p0, p1, p2) {
+    const steps = 10;
+    let length = 0;
+    let prev = p0;
+    for (let i = 1; i <= steps; i++) {
+        const t = i / steps;
+        const current = evaluateQuadratic(p0, p1, p2, t);
+        length += prev.subtract(current).length();
+        prev = current;
+    }
+    return length;
+}
+/** Calculates approximate length of a cubic Bezier curve via subdivision (20 steps). */
+export function getCubicLength(p0, p1, p2, p3) {
+    const steps = 20;
+    let length = 0;
+    let prev = p0;
+    for (let i = 1; i <= steps; i++) {
+        const t = i / steps;
+        const current = evaluateCubic(p0, p1, p2, p3, t);
+        length += prev.subtract(current).length();
+        prev = current;
+    }
+    return length;
+}

package/dist/core/math/bezier/morphing.d.ts

@@ -0,0 +1,16 @@
+import { Vector2 } from '../Vector2/Vector2';
+import type { PathCommand } from './types';
+/**
+ * Converts a path to use only cubic Bezier curves.
+ * Lines and quadratics are converted to equivalent cubics.
+ */
+export declare function toCubicCommands(commands: PathCommand[]): PathCommand[];
+/**
+ * Splits a cubic Bezier curve at parameter t using De Casteljau's algorithm.
+ */
+export declare function splitCubic(p0: Vector2, p1: Vector2, p2: Vector2, p3: Vector2, t: number): [PathCommand, PathCommand];
+/**
+ * Subdivides a path to match a target command count.
+ * Uses iterative approach to avoid stack overflow on complex paths.
+ */
+export declare function subdividePath(commands: PathCommand[], targetCount: number): PathCommand[];

package/dist/core/math/bezier/morphing.js

@@ -0,0 +1,151 @@
+import { Vector2 } from '../Vector2/Vector2';
+/**
+ * Converts a path to use only cubic Bezier curves.
+ * Lines and quadratics are converted to equivalent cubics.
+ */
+export function toCubicCommands(commands) {
+    const result = [];
+    let cursor = new Vector2(0, 0);
+    let subpathStart = new Vector2(0, 0);
+    for (const cmd of commands) {
+        switch (cmd.type) {
+            case 'Move':
+                result.push({ type: 'Move', end: cmd.end });
+                cursor = cmd.end;
+                subpathStart = cmd.end;
+                break;
+            case 'Line': {
+                // Convert Line to Cubic: P0, P1 -> P0, P0+(P1-P0)/3, P1-(P1-P0)/3, P1
+                const delta = cmd.end.subtract(cursor);
+                const c1 = cursor.add(delta.multiply(1 / 3));
+                const c2 = cmd.end.subtract(delta.multiply(1 / 3));
+                result.push({ type: 'Cubic', control1: c1, control2: c2, end: cmd.end });
+                cursor = cmd.end;
+                break;
+            }
+            case 'Quadratic':
+                if (cmd.control1) {
+                    // Convert Quadratic to Cubic
+                    // CP1 = P0 + 2/3 * (QP1 - P0)
+                    // CP2 = P1 + 2/3 * (QP1 - P1)
+                    const qp1 = cmd.control1;
+                    const cubicC1 = cursor.add(qp1.subtract(cursor).multiply(2 / 3));
+                    const cubicC2 = cmd.end.add(qp1.subtract(cmd.end).multiply(2 / 3));
+                    result.push({ type: 'Cubic', control1: cubicC1, control2: cubicC2, end: cmd.end });
+                }
+                cursor = cmd.end;
+                break;
+            case 'Cubic':
+                if (cmd.control1 && cmd.control2) {
+                    result.push({
+                        type: 'Cubic',
+                        control1: cmd.control1,
+                        control2: cmd.control2,
+                        end: cmd.end
+                    });
+                }
+                cursor = cmd.end;
+                break;
+            case 'Close': {
+                // Convert close to cubic line back to start
+                const delta = subpathStart.subtract(cursor);
+                const c1 = cursor.add(delta.multiply(1 / 3));
+                const c2 = subpathStart.subtract(delta.multiply(1 / 3));
+                result.push({ type: 'Cubic', control1: c1, control2: c2, end: subpathStart });
+                cursor = subpathStart;
+                break;
+            }
+        }
+    }
+    return result;
+}
+/**
+ * Splits a cubic Bezier curve at parameter t using De Casteljau's algorithm.
+ */
+export function splitCubic(p0, p1, p2, p3, t) {
+    const p01 = p0.lerp(p1, t);
+    const p12 = p1.lerp(p2, t);
+    const p23 = p2.lerp(p3, t);
+    const p012 = p01.lerp(p12, t);
+    const p123 = p12.lerp(p23, t);
+    const p0123 = p012.lerp(p123, t);
+    const cmd1 = {
+        type: 'Cubic',
+        control1: p01,
+        control2: p012,
+        end: p0123
+    };
+    const cmd2 = {
+        type: 'Cubic',
+        control1: p123,
+        control2: p23,
+        end: p3
+    };
+    return [cmd1, cmd2];
+}
+/**
+ * Subdivides a path to match a target command count.
+ * Uses iterative approach to avoid stack overflow on complex paths.
+ */
+export function subdividePath(commands, targetCount) {
+    let currentCommands = commands;
+    while (currentCommands.length < targetCount) {
+        const needed = targetCount - currentCommands.length;
+        const result = [];
+        // Identify cubic indices for splitting
+        const cubicIndices = [];
+        for (let i = 0; i < currentCommands.length; i++) {
+            if (currentCommands[i].type === 'Cubic') {
+                cubicIndices.push(i);
+            }
+        }
+        if (cubicIndices.length === 0) {
+            // No curves to split - add degenerate cubics at last point
+            const lastCmd = currentCommands[currentCommands.length - 1];
+            if (lastCmd) {
+                const pt = lastCmd.end;
+                const resultCmds = [...currentCommands];
+                for (let k = 0; k < needed; k++) {
+                    resultCmds.push({ type: 'Cubic', control1: pt, control2: pt, end: pt });
+                }
+                return resultCmds;
+            }
+            return currentCommands;
+        }
+        let splitsPerformed = 0;
+        let cursor = new Vector2(0, 0);
+        for (let i = 0; i < currentCommands.length; i++) {
+            const cmd = currentCommands[i];
+            if (cmd.type === 'Move') {
+                result.push({ type: 'Move', end: cmd.end });
+                cursor = cmd.end;
+            }
+            else if (cmd.type === 'Cubic' && splitsPerformed < needed) {
+                if (cmd.control1 && cmd.control2) {
+                    const [c1, c2] = splitCubic(cursor, cmd.control1, cmd.control2, cmd.end, 0.5);
+                    result.push(c1);
+                    result.push(c2);
+                    splitsPerformed++;
+                    cursor = cmd.end;
+                }
+                else {
+                    result.push(cmd);
+                    cursor = cmd.end;
+                }
+            }
+            else {
+                if (cmd.type === 'Cubic' && cmd.control1 && cmd.control2) {
+                    result.push({
+                        type: 'Cubic',
+                        control1: cmd.control1,
+                        control2: cmd.control2,
+                        end: cmd.end
+                    });
+                }
+                cursor = cmd.end;
+            }
+        }
+        currentCommands = result;
+    }
+    return currentCommands;
+}

package/dist/core/math/bezier/sampling.d.ts

@@ -0,0 +1,7 @@
+import { Vector2 } from '../Vector2/Vector2';
+import type { PathCommand } from './types';
+export declare function getPathLength(commands: PathCommand[]): number;
+/** Point on the path at normalized position t (0-1). */
+export declare function getPointAtPath(commands: PathCommand[], t: number): Vector2;
+/** Tangent vector on the path at normalized position t (0-1). */
+export declare function getTangentAtPath(commands: PathCommand[], t: number): Vector2;