loomlarge 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,631 @@
+/**
+ * LoomLarge - AU Mapping Types
+ *
+ * Type definitions for configurable Action Unit mappings.
+ * Allows the engine to work with different character rigs (CC4, Mixamo, etc.)
+ */
+
+/**
+ * AUMappingConfig - Complete configuration for AU-to-morph/bone mappings
+ *
+ * This is the main configuration object that defines how Action Units
+ * map to morph targets and bone transformations for a specific rig type.
+ */
+interface AUMappingConfig {
+    /** AU ID to morph target names (e.g., AU 12 → ['Mouth_Smile_L', 'Mouth_Smile_R']) */
+    auToMorphs: Record<number, string[]>;
+    /** AU ID to bone bindings (e.g., AU 51 → [{ node: 'HEAD', channel: 'ry', scale: 1, maxDegrees: 30 }]) */
+    auToBones: Record<number, BoneBinding[]>;
+    /** Bone key to actual node name in the model (e.g., 'HEAD' → 'CC_Base_Head') */
+    boneNodes: Record<string, string>;
+    /** Morph category to mesh names (e.g., 'face' → ['CC_Base_Body_1']) */
+    morphToMesh: Record<string, string[]>;
+    /** Viseme keys in order (typically 15 phoneme positions) */
+    visemeKeys: string[];
+    /** Optional: Default mix weights for bone/morph blending (0 = morph only, 1 = bone only) */
+    auMixDefaults?: Record<number, number>;
+    /** Optional: AU metadata (names, muscle basis, etc.) */
+    auInfo?: Record<string, AUInfo>;
+    /** Optional: Eye mesh node fallbacks (some rigs use mesh nodes instead of bone nodes) */
+    eyeMeshNodes?: {
+        LEFT: string;
+        RIGHT: string;
+    };
+}
+/**
+ * Helper type for mesh categories in morphToMesh
+ */
+type MorphCategory = 'face' | 'viseme' | 'eye' | 'tearLine' | 'tongue' | 'hair';
+
+/**
+ * LoomLarge - Core Type Definitions
+ *
+ * Type definitions for the 3D character animation engine.
+ * These are framework-agnostic interfaces that work with any 3D engine.
+ */
+/**
+ * TransitionHandle - returned from transition methods
+ * Provides promise-based completion notification plus fine-grained control.
+ */
+interface TransitionHandle {
+    /** Resolves when the transition completes (or is cancelled) */
+    promise: Promise<void>;
+    /** Pause this transition (holds at current value) */
+    pause: () => void;
+    /** Resume this transition after pause */
+    resume: () => void;
+    /** Cancel this transition immediately (resolves promise) */
+    cancel: () => void;
+}
+/** Standard bone keys used in AU bindings */
+type BoneKey = 'EYE_L' | 'EYE_R' | 'JAW' | 'HEAD' | 'NECK' | 'TONGUE' | string;
+/**
+ * BoneBinding - Defines how an AU maps to bone transformations
+ */
+interface BoneBinding {
+    node: BoneKey;
+    channel: 'rx' | 'ry' | 'rz' | 'tx' | 'ty' | 'tz';
+    scale: -1 | 1;
+    maxDegrees?: number;
+    maxUnits?: number;
+}
+/**
+ * RotationAxis - Defines which AUs control a specific rotation axis
+ */
+interface RotationAxis {
+    aus: number[];
+    axis: 'rx' | 'ry' | 'rz';
+    negative?: number;
+    positive?: number;
+}
+/**
+ * CompositeRotation - Defines unified rotation axes for bones
+ */
+interface CompositeRotation {
+    node: string;
+    pitch: RotationAxis | null;
+    yaw: RotationAxis | null;
+    roll: RotationAxis | null;
+}
+/**
+ * AUInfo - Metadata about an Action Unit
+ */
+interface AUInfo {
+    id: string;
+    name: string;
+    muscularBasis?: string;
+    links?: string[];
+    faceArea?: 'Upper' | 'Lower';
+    facePart?: string;
+}
+/** Per-axis rotation state */
+interface RotationAxisState {
+    value: number;
+    maxRadians: number;
+}
+interface CompositeRotationState {
+    pitch: RotationAxisState;
+    yaw: RotationAxisState;
+    roll: RotationAxisState;
+}
+type RotationsState = Record<string, CompositeRotationState>;
+
+/**
+ * LoomLarge Engine Interface
+ *
+ * Defines the contract for 3D character animation engines.
+ * Implementations can target different 3D frameworks (Three.js, Babylon.js, etc.)
+ */
+
+/**
+ * Mesh interface - minimal requirements for meshes with morph targets
+ */
+interface LoomMesh {
+    name: string;
+    visible: boolean;
+    isMesh: boolean;
+    morphTargetInfluences?: number[];
+    morphTargetDictionary?: Record<string, number>;
+}
+/**
+ * Vector3-like interface
+ */
+interface LoomVector3 {
+    x: number;
+    y: number;
+    z: number;
+    clone(): LoomVector3;
+    copy(v: LoomVector3): void;
+}
+/**
+ * Euler rotation interface
+ */
+interface LoomEuler {
+    x: number;
+    y: number;
+    z: number;
+    order: string;
+}
+/**
+ * Quaternion interface
+ */
+interface LoomQuaternion {
+    clone(): LoomQuaternion;
+    copy(q: LoomQuaternion): void;
+}
+/**
+ * Object3D interface - minimal requirements for scene objects
+ */
+interface LoomObject3D {
+    name?: string;
+    position: LoomVector3;
+    quaternion: LoomQuaternion;
+    rotation: LoomEuler & {
+        set(x: number, y: number, z: number, order: string): void;
+    };
+    traverse(callback: (obj: any) => void): void;
+    getObjectByName(name: string): LoomObject3D | undefined;
+    updateMatrixWorld(force: boolean): void;
+}
+/**
+ * Payload for initializing the engine with a loaded model
+ */
+interface ReadyPayload {
+    meshes: LoomMesh[];
+    model: LoomObject3D;
+}
+/**
+ * Configuration options for the LoomLarge engine
+ */
+interface LoomLargeConfig {
+    /** AU to morph target mappings */
+    auMappings?: AUMappingConfig;
+}
+/**
+ * Mesh info returned from getMeshList()
+ */
+interface MeshInfo {
+    name: string;
+    visible: boolean;
+    morphCount: number;
+}
+/**
+ * LoomLarge Engine Interface
+ *
+ * The main interface for controlling 3D character facial animation.
+ * Supports Action Units (AUs), morph targets, visemes, and bone control.
+ */
+interface LoomLarge {
+    /**
+     * Initialize the engine with a loaded model.
+     * Call this after loading your 3D model.
+     */
+    onReady(payload: ReadyPayload): void;
+    /**
+     * Update animation state. Call each frame with delta time in seconds.
+     */
+    update(deltaSeconds: number): void;
+    /**
+     * Dispose engine resources and cleanup.
+     */
+    dispose(): void;
+    /**
+     * Set AU value immediately (no transition)
+     * @param id - AU number (e.g., 12 for smile) or string ('12L' for left side)
+     * @param v - Value 0-1
+     * @param balance - Optional L/R balance: -1 = left only, 0 = both, +1 = right only
+     */
+    setAU(id: number | string, v: number, balance?: number): void;
+    /**
+     * Transition AU value smoothly over time
+     * @param id - AU number or string
+     * @param to - Target value 0-1
+     * @param durationMs - Transition duration in milliseconds
+     * @param balance - Optional L/R balance
+     */
+    transitionAU(id: number | string, to: number, durationMs?: number, balance?: number): TransitionHandle;
+    /**
+     * Get current AU value
+     */
+    getAU(id: number): number;
+    /**
+     * Set morph target value immediately
+     * @param key - Morph target name
+     * @param v - Value 0-1
+     * @param meshNames - Optional specific meshes to target
+     */
+    setMorph(key: string, v: number, meshNames?: string[]): void;
+    /**
+     * Transition morph target value smoothly
+     * @param key - Morph target name
+     * @param to - Target value 0-1
+     * @param durationMs - Transition duration in milliseconds
+     * @param meshNames - Optional specific meshes to target
+     */
+    transitionMorph(key: string, to: number, durationMs?: number, meshNames?: string[]): TransitionHandle;
+    /**
+     * Set viseme value immediately (for lip-sync)
+     * @param visemeIndex - Viseme index 0-14
+     * @param value - Value 0-1
+     * @param jawScale - Jaw movement multiplier (default 1.0)
+     */
+    setViseme(visemeIndex: number, value: number, jawScale?: number): void;
+    /**
+     * Transition viseme value smoothly
+     */
+    transitionViseme(visemeIndex: number, to: number, durationMs?: number, jawScale?: number): TransitionHandle;
+    /**
+     * Set mix weight for an AU (blend between morph and bone contribution)
+     */
+    setAUMixWeight(id: number, weight: number): void;
+    /**
+     * Get current mix weight for an AU
+     */
+    getAUMixWeight(id: number): number;
+    /**
+     * Pause all transitions
+     */
+    pause(): void;
+    /**
+     * Resume all transitions
+     */
+    resume(): void;
+    /**
+     * Check if engine is paused
+     */
+    getPaused(): boolean;
+    /**
+     * Clear all active transitions
+     */
+    clearTransitions(): void;
+    /**
+     * Get count of active transitions
+     */
+    getActiveTransitionCount(): number;
+    /**
+     * Reset all facial animation to neutral state
+     */
+    resetToNeutral(): void;
+    /**
+     * Get list of all meshes in the model
+     */
+    getMeshList(): MeshInfo[];
+    /**
+     * Set mesh visibility
+     */
+    setMeshVisible(meshName: string, visible: boolean): void;
+    /**
+     * Update AU mappings configuration
+     */
+    setAUMappings(mappings: AUMappingConfig): void;
+    /**
+     * Get current AU mappings configuration
+     */
+    getAUMappings(): AUMappingConfig;
+}
+
+/**
+ * Animation System Interface
+ *
+ * Defines the contract for transition/animation systems.
+ * Implementations can use different interpolation strategies.
+ */
+
+/**
+ * Animation system that manages value transitions over time.
+ */
+interface Animation {
+    /**
+     * Update all active transitions by delta time.
+     * @param dtSeconds - Time elapsed since last tick in seconds
+     */
+    tick(dtSeconds: number): void;
+    /**
+     * Add or replace a transition for the given key.
+     * If a transition with the same key exists, it should be cancelled and replaced.
+     *
+     * @param key - Unique identifier for this transition
+     * @param from - Starting value
+     * @param to - Target value
+     * @param durationMs - Duration in milliseconds
+     * @param apply - Callback to apply the interpolated value
+     * @param easing - Optional easing function (default: ease-in-out)
+     * @returns TransitionHandle for control
+     */
+    addTransition(key: string, from: number, to: number, durationMs: number, apply: (value: number) => void, easing?: (t: number) => number): TransitionHandle;
+    /**
+     * Clear all active transitions.
+     */
+    clearTransitions(): void;
+    /**
+     * Get count of active transitions.
+     */
+    getActiveTransitionCount(): number;
+}
+
+/**
+ * LoomLargeThree - Three.js Implementation
+ *
+ * Default implementation of the LoomLarge interface for Three.js.
+ * Controls 3D character facial animation using Action Units (AUs),
+ * morph targets, visemes, and bone transformations.
+ */
+
+declare class LoomLargeThree implements LoomLarge {
+    private config;
+    private animation;
+    private auValues;
+    private rigReady;
+    private missingBoneWarnings;
+    private rotations;
+    private pendingCompositeNodes;
+    private isPaused;
+    private translations;
+    private faceMesh;
+    private meshes;
+    private model;
+    private meshByName;
+    private morphCache;
+    private bones;
+    private mixWeights;
+    private visemeValues;
+    private static readonly VISEME_JAW_AMOUNTS;
+    private static readonly JAW_MAX_DEGREES;
+    constructor(config?: LoomLargeConfig, animation?: Animation);
+    onReady(payload: ReadyPayload): void;
+    update(deltaSeconds: number): void;
+    dispose(): void;
+    setAU(id: number | string, v: number, balance?: number): void;
+    transitionAU(id: number | string, to: number, durationMs?: number, balance?: number): TransitionHandle;
+    getAU(id: number): number;
+    setMorph(key: string, v: number, meshNames?: string[]): void;
+    transitionMorph(key: string, to: number, durationMs?: number, meshNames?: string[]): TransitionHandle;
+    setViseme(visemeIndex: number, value: number, jawScale?: number): void;
+    transitionViseme(visemeIndex: number, to: number, durationMs?: number, jawScale?: number): TransitionHandle;
+    setAUMixWeight(id: number, weight: number): void;
+    getAUMixWeight(id: number): number;
+    pause(): void;
+    resume(): void;
+    getPaused(): boolean;
+    clearTransitions(): void;
+    getActiveTransitionCount(): number;
+    resetToNeutral(): void;
+    getMeshList(): MeshInfo[];
+    setMeshVisible(meshName: string, visible: boolean): void;
+    setAUMappings(mappings: AUMappingConfig): void;
+    getAUMappings(): AUMappingConfig;
+    private computeSideValues;
+    private getMeshNamesForAU;
+    private getMorphValue;
+    private isMixedAU;
+    private initBoneRotations;
+    private updateBoneRotation;
+    private updateBoneTranslation;
+    private transitionBoneRotation;
+    private transitionBoneTranslation;
+    private flushPendingComposites;
+    private applyCompositeRotation;
+    private resolveBones;
+    private combineHandles;
+}
+/**
+ * Helper function to collect meshes with morph targets from a scene.
+ */
+declare function collectMorphMeshes(root: LoomObject3D): LoomMesh[];
+
+/**
+ * AnimationThree - Lerp-based animation system
+ *
+ * Default implementation of the Animation interface.
+ * Uses simple lerp interpolation with easing functions.
+ */
+
+declare class AnimationThree implements Animation {
+    private transitions;
+    /**
+     * Tick all active transitions by dt seconds.
+     * Applies eased interpolation and removes completed transitions.
+     * Respects individual transition pause state.
+     */
+    tick(dtSeconds: number): void;
+    /**
+     * Add or replace a transition for the given key.
+     * If a transition with the same key exists, it is cancelled and replaced.
+     * @returns TransitionHandle with { promise, pause, resume, cancel }
+     */
+    addTransition(key: string, from: number, to: number, durationMs: number, apply: (value: number) => void, easing?: (t: number) => number): TransitionHandle;
+    /** Clear all running transitions. */
+    clearTransitions(): void;
+    /** Get count of active transitions. */
+    getActiveTransitionCount(): number;
+}
+
+/**
+ * Hair Physics Interface
+ *
+ * Defines the contract for hair physics simulation systems.
+ * Implementations can use different physics models (spring-damper, verlet, etc.)
+ */
+/**
+ * Configuration for hair physics simulation
+ */
+interface HairPhysicsConfig$1 {
+    mass: number;
+    stiffness: number;
+    damping: number;
+    gravity: number;
+    headInfluence: number;
+    windEnabled: boolean;
+    windStrength: number;
+    windDirectionX: number;
+    windDirectionZ: number;
+    windTurbulence: number;
+    windFrequency: number;
+}
+/**
+ * Hair strand definition for multi-strand simulation
+ */
+interface HairStrand {
+    id: string;
+    morphKeys: {
+        left: string;
+        right: string;
+        front?: string;
+        back?: string;
+    };
+    mass?: number;
+    stiffness?: number;
+    damping?: number;
+}
+/**
+ * Current physics state of hair simulation
+ */
+interface HairState {
+    x: number;
+    z: number;
+    vx: number;
+    vz: number;
+}
+/**
+ * Head orientation state for physics input
+ */
+interface HeadState$1 {
+    yaw: number;
+    pitch: number;
+    roll: number;
+    yawVelocity: number;
+    pitchVelocity: number;
+}
+/**
+ * Output morph values from physics simulation
+ */
+interface HairMorphOutput$1 {
+    [morphKey: string]: number;
+}
+/**
+ * Hair Physics simulation interface
+ */
+interface HairPhysics$1 {
+    /**
+     * Update physics simulation
+     * @param dt Delta time in seconds
+     * @param headState Current head orientation and velocity
+     * @returns Morph values to apply to hair meshes
+     */
+    update(dt: number, headState: HeadState$1): HairMorphOutput$1;
+    /**
+     * Get current physics state (for debugging/UI)
+     */
+    getState(): HairState;
+    /**
+     * Update configuration
+     */
+    setConfig(config: Partial<HairPhysicsConfig$1>): void;
+    /**
+     * Get current configuration
+     */
+    getConfig(): HairPhysicsConfig$1;
+    /**
+     * Reset physics state to rest position
+     */
+    reset(): void;
+}
+
+/**
+ * CC4 Preset - Character Creator 4 AU Mappings
+ *
+ * Complete FACS Action Unit to morph target and bone mappings for CC4 rigs.
+ * This includes all the composite rotations, continuum pairs, mesh classifications,
+ * and AU metadata that we painstakingly worked through.
+ */
+
+declare const CC4_PRESET: AUMappingConfig;
+
+/**
+ * HairPhysics - Spring-damper pendulum simulation for hair movement
+ *
+ * This is a pure physics simulation class with no Three.js dependencies.
+ * It outputs normalized morph values (0-1) that can be applied to hair meshes
+ * via EngineThree.setMorph() or transitionMorph().
+ *
+ * Physics model:
+ * - Hair is modeled as a damped pendulum affected by:
+ *   - Gravity (constant downward force based on head orientation)
+ *   - Head velocity (inertia causes hair to lag behind head movement)
+ *   - Wind (oscillating force with turbulence)
+ *   - Spring restoration (hair returns to rest position)
+ *   - Damping (air resistance)
+ */
+interface HairPhysicsConfig {
+    mass: number;
+    stiffness: number;
+    damping: number;
+    gravity: number;
+    headInfluence: number;
+    windEnabled: boolean;
+    windStrength: number;
+    windDirectionX: number;
+    windDirectionZ: number;
+    windTurbulence: number;
+    windFrequency: number;
+}
+interface HairPhysicsState {
+    x: number;
+    z: number;
+    vx: number;
+    vz: number;
+}
+interface HairMorphOutput {
+    L_Hair_Left: number;
+    L_Hair_Right: number;
+    L_Hair_Front: number;
+    R_Hair_Left: number;
+    R_Hair_Right: number;
+    R_Hair_Front: number;
+}
+interface HeadState {
+    yaw: number;
+    pitch: number;
+    roll: number;
+    yawVelocity: number;
+    pitchVelocity: number;
+}
+declare const DEFAULT_HAIR_PHYSICS_CONFIG: HairPhysicsConfig;
+declare class HairPhysics {
+    private config;
+    private state;
+    private time;
+    private prevHeadYaw;
+    private prevHeadPitch;
+    constructor(config?: Partial<HairPhysicsConfig>);
+    /**
+     * Update physics simulation
+     * @param dt Delta time in seconds
+     * @param headState Current head orientation and velocity
+     * @returns Morph values to apply to hair meshes
+     */
+    update(dt: number, headState: HeadState): HairMorphOutput;
+    /**
+     * Convert physics state to morph target values
+     * Maps pendulum position to left/right/front morphs for both sides
+     */
+    private computeMorphOutput;
+    /**
+     * Get current physics state (for debugging/UI)
+     */
+    getState(): HairPhysicsState;
+    /**
+     * Update configuration
+     */
+    setConfig(config: Partial<HairPhysicsConfig>): void;
+    /**
+     * Get current configuration
+     */
+    getConfig(): HairPhysicsConfig;
+    /**
+     * Reset physics state to rest position
+     */
+    reset(): void;
+}
+
+export { type AUInfo, type AUMappingConfig, type Animation, AnimationThree, type BoneBinding, type BoneKey, CC4_PRESET, type CompositeRotation, type CompositeRotationState, DEFAULT_HAIR_PHYSICS_CONFIG, type HairMorphOutput$1 as HairMorphOutput, HairPhysics, type HairPhysicsConfig$1 as HairPhysicsConfig, type HairPhysics$1 as HairPhysicsInterface, type HairMorphOutput as HairPhysicsMorphOutput, type HairPhysicsState, type HairState, type HairStrand, type HeadState$1 as HeadState, type LoomEuler, type LoomLarge, type LoomLargeConfig, LoomLargeThree, type LoomMesh, type LoomObject3D, type LoomQuaternion, type LoomVector3, type MeshInfo, type MorphCategory, type ReadyPayload, type RotationAxis, type RotationAxisState, type RotationsState, type TransitionHandle, collectMorphMeshes, LoomLargeThree as default };