@myned-ai/gsplat-flame-avatar-renderer 1.0.5 → 1.0.6

package/src/errors/ApplicationError.js

@@ -0,0 +1,185 @@
+/**
+ * ApplicationError - Base error class for all application errors
+ *
+ * Provides structured error handling with error codes and cause tracking.
+ * All domain-specific errors should extend this class.
+ *
+ * @extends Error
+ */
+export class ApplicationError extends Error {
+    /**
+     * Create an ApplicationError
+     * @param {string} message - Human-readable error message
+     * @param {string} code - Machine-readable error code for programmatic handling
+     * @param {Error} [cause=null] - Original error that caused this error (for error chaining)
+     */
+    constructor(message, code, cause = null) {
+        super(message);
+        this.name = this.constructor.name;
+        this.code = code;
+        this.cause = cause;
+
+        // Capture stack trace, excluding constructor call from it
+        if (Error.captureStackTrace) {
+            Error.captureStackTrace(this, this.constructor);
+        }
+    }
+
+    /**
+     * Convert error to JSON for logging/transmission
+     * @returns {object} JSON representation of error
+     */
+    toJSON() {
+        return {
+            name: this.name,
+            message: this.message,
+            code: this.code,
+            stack: this.stack,
+            cause: this.cause ? {
+                name: this.cause.name,
+                message: this.cause.message
+            } : null
+        };
+    }
+}
+
+/**
+ * ValidationError - Thrown when input validation fails
+ *
+ * Used for invalid parameters, out-of-range values, or malformed data.
+ *
+ * @extends ApplicationError
+ */
+export class ValidationError extends ApplicationError {
+    /**
+     * Create a ValidationError
+     * @param {string} message - Validation failure description
+     * @param {string} field - Name of the field that failed validation
+     * @param {Error} [cause=null] - Original error that caused this validation failure
+     */
+    constructor(message, field, cause = null) {
+        super(message, 'VALIDATION_ERROR', cause);
+        this.field = field;
+    }
+}
+
+/**
+ * NetworkError - Thrown when network operations fail
+ *
+ * Used for fetch failures, timeouts, or HTTP error responses.
+ *
+ * @extends ApplicationError
+ */
+export class NetworkError extends ApplicationError {
+    /**
+     * Create a NetworkError
+     * @param {string} message - Network error description
+     * @param {number} [statusCode=0] - HTTP status code (if applicable)
+     * @param {Error} [cause=null] - Original error that caused this network failure
+     */
+    constructor(message, statusCode = 0, cause = null) {
+        super(message, 'NETWORK_ERROR', cause);
+        this.statusCode = statusCode;
+    }
+}
+
+/**
+ * AssetLoadError - Thrown when asset loading fails
+ *
+ * Used for failures loading models, textures, or other asset files.
+ *
+ * @extends ApplicationError
+ */
+export class AssetLoadError extends ApplicationError {
+    /**
+     * Create an AssetLoadError
+     * @param {string} message - Asset load failure description
+     * @param {string} assetPath - Path to the asset that failed to load
+     * @param {Error} [cause=null] - Original error that caused this load failure
+     */
+    constructor(message, assetPath, cause = null) {
+        super(message, 'ASSET_LOAD_ERROR', cause);
+        this.assetPath = assetPath;
+    }
+}
+
+/**
+ * ResourceDisposedError - Thrown when attempting to use a disposed resource
+ *
+ * Used to prevent use-after-dispose bugs.
+ *
+ * @extends ApplicationError
+ */
+export class ResourceDisposedError extends ApplicationError {
+    /**
+     * Create a ResourceDisposedError
+     * @param {string} resourceName - Name of the disposed resource
+     */
+    constructor(resourceName) {
+        super(
+            `Cannot use ${resourceName}: resource has been disposed`,
+            'RESOURCE_DISPOSED_ERROR'
+        );
+        this.resourceName = resourceName;
+    }
+}
+
+/**
+ * InitializationError - Thrown when initialization fails
+ *
+ * Used when required setup steps fail or prerequisites are not met.
+ *
+ * @extends ApplicationError
+ */
+export class InitializationError extends ApplicationError {
+    /**
+     * Create an InitializationError
+     * @param {string} message - Initialization failure description
+     * @param {string} component - Name of component that failed to initialize
+     * @param {Error} [cause=null] - Original error that caused this initialization failure
+     */
+    constructor(message, component, cause = null) {
+        super(message, 'INITIALIZATION_ERROR', cause);
+        this.component = component;
+    }
+}
+
+/**
+ * ParseError - Thrown when parsing data fails
+ *
+ * Used for malformed file formats, invalid JSON, or corrupt data.
+ *
+ * @extends ApplicationError
+ */
+export class ParseError extends ApplicationError {
+    /**
+     * Create a ParseError
+     * @param {string} message - Parse failure description
+     * @param {string} dataType - Type of data being parsed (e.g., 'JSON', 'PLY', 'GLB')
+     * @param {Error} [cause=null] - Original error that caused this parse failure
+     */
+    constructor(message, dataType, cause = null) {
+        super(message, 'PARSE_ERROR', cause);
+        this.dataType = dataType;
+    }
+}
+
+/**
+ * ConfigurationError - Thrown when configuration is invalid
+ *
+ * Used for invalid settings, missing required configuration, or conflicting options.
+ *
+ * @extends ApplicationError
+ */
+export class ConfigurationError extends ApplicationError {
+    /**
+     * Create a ConfigurationError
+     * @param {string} message - Configuration error description
+     * @param {string} configKey - Configuration key that is invalid
+     * @param {Error} [cause=null] - Original error
+     */
+    constructor(message, configKey, cause = null) {
+        super(message, 'CONFIGURATION_ERROR', cause);
+        this.configKey = configKey;
+    }
+}

package/src/errors/index.js

@@ -0,0 +1,17 @@
+/**
+ * Error classes for structured error handling
+ *
+ * This module exports all custom error classes used throughout the application.
+ * All errors extend ApplicationError for consistent error handling.
+ */
+
+export {
+    ApplicationError,
+    ValidationError,
+    NetworkError,
+    AssetLoadError,
+    ResourceDisposedError,
+    InitializationError,
+    ParseError,
+    ConfigurationError
+} from './ApplicationError.js';

package/src/flame/FlameAnimator.js

@@ -1,60 +1,158 @@
 /**
- * FlameAnimator
- * 
+ * FlameAnimator - FLAME Parametric Head Model Animation Controller
+ *
  * Derived from gaussian-splat-renderer-for-lam
- * 
- * Handles FLAME model animation and skeleton updates:
- * - Bone rotation from FLAME parameters
- * - Blendshape weight updates
- * - Skeleton synchronization with gaussian splat mesh
+ *
+ * Manages FLAME (Faces Learned with an Articulated Model and Expressions) model animation:
+ * - Skeletal bone rotation from FLAME parameters
+ * - Blendshape weight updates for facial expressions
+ * - Skeleton-mesh synchronization for gaussian splat rendering
+ * - Linear blend skinning (LBS) with bone weights
+ *
+ * FLAME uses 5 bones: root, neck, jaw, left eye, right eye
  */
 
 import {
-    Vector3,
-    Quaternion,
     Matrix4,
     Bone,
     Skeleton
 } from 'three';
 
 import { FlameTextureManager } from './FlameTextureManager.js';
+import { getLogger } from '../utils/Logger.js';
+import { ValidationError, ResourceDisposedError } from '../errors/index.js';
+import { validateRequiredProperties } from '../utils/ValidationUtils.js';
+import { vector3Pool, quaternionPool } from '../utils/ObjectPool.js';
+
+const logger = getLogger('FlameAnimator');
 
 /**
  * FlameAnimator - Manages FLAME parametric head model animation
+ *
+ * Provides skeletal animation, blendshape morphing, and mesh deformation
+ * for FLAME-based avatar heads with gaussian splatting rendering.
  */
 export class FlameAnimator {
+    /**
+     * Create a FlameAnimator instance
+     *
+     * @constructor
+     */
     constructor() {
+        /** @type {THREE.Skeleton|null} FLAME skeleton with 5 bones */
         this.skeleton = null;
+
+        /** @type {THREE.Bone[]|null} Array of skeleton bones */
         this.bones = null;
+
+        /** @type {Object|null} FLAME animation parameters (rotation, expr, neck_pose, jaw_pose, eyes_pose) */
         this.flameParams = null;
+
+        /** @type {Array|null} Linear blend skinning weights */
         this.lbsWeight = null;
+
+        /** @type {number} Current animation frame */
         this.frame = 0;
+
+        /** @type {number} Total frames in animation sequence */
         this.totalFrames = 0;
+
+        /** @type {boolean} Whether FLAME mode is enabled */
         this.useFlame = true;
+
+        /** @type {THREE.SkinnedMesh|null} The FLAME avatar mesh */
         this.avatarMesh = null;
+
+        /** @type {number} Number of gaussian splats in the mesh */
         this.gaussianSplatCount = 0;
+
+        /** @type {boolean} Whether animator has been disposed */
+        this._disposed = false;
+
+        logger.debug('FlameAnimator instance created');
+    }
+
+    /**
+     * Assert animator is not disposed
+     * @private
+     * @throws {ResourceDisposedError} If animator has been disposed
+     */
+    _assertNotDisposed() {
+        if (this._disposed) {
+            throw new ResourceDisposedError('FlameAnimator has been disposed');
+        }
     }
 
     /**
-     * Initialize with FLAME parameters and LBS weights
-     * @param {object} flameParams - FLAME animation parameters
-     * @param {object} boneTree - Skeleton hierarchy data
-     * @param {Array} lbsWeight - LBS weights for each vertex
+     * Initialize animator with FLAME parameters and skeleton data
+     *
+     * Sets up the FLAME animation system with parameters for bone rotations,
+     * expressions, and linear blend skinning weights.
+     *
+     * @param {Object} flameParams - FLAME animation parameters
+     * @param {Array} flameParams.rotation - Root bone rotations per frame (axis-angle)
+     * @param {Array} flameParams.expr - Expression blendshape weights per frame
+     * @param {Array} flameParams.neck_pose - Neck bone rotations per frame
+     * @param {Array} flameParams.jaw_pose - Jaw bone rotations per frame
+     * @param {Array} flameParams.eyes_pose - Eye bone rotations per frame (6 values: left 3, right 3)
+     * @param {Object|Array} boneTree - Skeleton hierarchy definition
+     * @param {Array} lbsWeight - Linear blend skinning weights for each vertex
      * @param {THREE.SkinnedMesh} avatarMesh - The FLAME avatar mesh
+     * @throws {ValidationError} If required parameters are missing or invalid
+     * @returns {void}
      */
     initialize(flameParams, boneTree, lbsWeight, avatarMesh) {
+        this._assertNotDisposed();
+
+        // Validate required parameters
+        try {
+            validateRequiredProperties(flameParams, ['rotation', 'expr', 'neck_pose', 'jaw_pose', 'eyes_pose'], 'flameParams');
+        } catch (error) {
+            logger.error('Invalid flameParams', error);
+            throw error;
+        }
+
+        if (!avatarMesh || !avatarMesh.geometry || !avatarMesh.geometry.attributes || !avatarMesh.geometry.attributes.position) {
+            const error = new ValidationError(
+                'avatarMesh must have geometry with position attribute',
+                'avatarMesh'
+            );
+            logger.error('Invalid avatarMesh', error);
+            throw error;
+        }
+
+        logger.info('Initializing FlameAnimator', {
+            frameCount: flameParams.rotation?.length,
+            splatCount: avatarMesh.geometry.attributes.position.count
+        });
+
         this.flameParams = flameParams;
         this.lbsWeight = lbsWeight;
         this.avatarMesh = avatarMesh;
-        
-        if (flameParams && flameParams.rotation) {
+
+        // Calculate total frames from rotation data
+        if (flameParams.rotation && Array.isArray(flameParams.rotation)) {
             this.totalFrames = flameParams.rotation.length;
+            logger.debug('Animation has frames', { totalFrames: this.totalFrames });
+        } else {
+            logger.warn('No rotation data found, totalFrames set to 0');
+            this.totalFrames = 0;
         }
 
         this.gaussianSplatCount = avatarMesh.geometry.attributes.position.count;
-        
+
         // Build skeleton from bone tree
-        this.buildSkeleton(boneTree);
+        try {
+            this.buildSkeleton(boneTree);
+            logger.debug('Skeleton built successfully', { boneCount: this.bones?.length });
+        } catch (error) {
+            logger.error('Failed to build skeleton', error);
+            throw new ValidationError(
+                `Failed to build skeleton: ${error.message}`,
+                'boneTree',
+                error
+            );
+        }
     }
 
     /**
@@ -139,58 +237,115 @@ export class FlameAnimator {
     }
 
     /**
-     * Set bone rotation from axis-angle or quaternion
-     * @param {THREE.Bone} bone - Target bone
-     * @param {Array} angles - Rotation values
-     * @param {boolean} isQuat - Whether angles are quaternion
+     * Set bone rotation from axis-angle or quaternion representation
+     *
+     * Converts rotation data to quaternion and applies it to the bone.
+     * Uses object pooling to avoid allocations in animation loop.
+     *
+     * @param {THREE.Bone} bone - Target bone to rotate
+     * @param {Array<number>} angles - Rotation values (3 for axis-angle, 4 for quaternion)
+     * @param {boolean} [isQuat=false] - Whether angles are quaternion [x, y, z, w]
+     * @throws {ValidationError} If bone or angles are invalid
+     * @returns {void}
      */
     setBoneRotation(bone, angles, isQuat = false) {
-        let quaternion;
-        
-        if (isQuat) {
-            quaternion = new Quaternion(angles[0], angles[1], angles[2], angles[3]);
-        } else {
-            // Axis-angle representation
-            const value = new Vector3(angles[0], angles[1], angles[2]);
-            const angleInRadians = value.length();
-            const axis = value.normalize();
-            quaternion = new Quaternion().setFromAxisAngle(axis, angleInRadians);
+        this._assertNotDisposed();
+
+        if (!bone || !angles || !Array.isArray(angles)) {
+            throw new ValidationError(
+                'bone and angles array are required',
+                'bone/angles'
+            );
+        }
+
+        // Use object pooling for temp objects
+        const quaternion = quaternionPool.acquire();
+
+        try {
+            if (isQuat) {
+                // Direct quaternion (XYZW format)
+                if (angles.length < 4) {
+                    throw new ValidationError('Quaternion requires 4 values', 'angles');
+                }
+                quaternion.set(angles[0], angles[1], angles[2], angles[3]);
+            } else {
+                // Axis-angle representation: [x, y, z] where magnitude is angle
+                if (angles.length < 3) {
+                    throw new ValidationError('Axis-angle requires 3 values', 'angles');
+                }
+
+                const axis = vector3Pool.acquire();
+                try {
+                    axis.set(angles[0], angles[1], angles[2]);
+                    const angleInRadians = axis.length();
+                    axis.normalize();
+                    quaternion.setFromAxisAngle(axis, angleInRadians);
+                } finally {
+                    vector3Pool.release(axis);
+                }
+            }
+
+            // Apply rotation to bone
+            bone.quaternion.copy(quaternion);
+            bone.updateMatrixWorld(true);
+        } finally {
+            quaternionPool.release(quaternion);
         }
-        
-        bone.quaternion.copy(quaternion);
-        bone.updateMatrixWorld(true);
     }
 
     /**
      * Update FLAME bones from current frame parameters
+     *
+     * Applies bone rotations for all 5 FLAME bones (root, neck, jaw, left eye, right eye)
+     * from the current animation frame. Updates skeleton matrices and returns data
+     * needed for mesh deformation.
+     *
+     * @returns {Object} Bone and blendshape data for rendering
+     * @returns {Array} return.bsWeight - Expression blendshape weights for current frame
+     * @returns {Float32Array} return.bonesMatrix - Updated bone transformation matrices
+     * @returns {number} return.bonesNum - Number of bones (always 5 for FLAME)
+     * @returns {Array} return.bonesWeight - LBS weights for vertices
      */
     updateFlameBones() {
-        if (!this.flameParams || !this.skeleton) return {};
+        this._assertNotDisposed();
 
-        const frame = this.frame;
-        const bsWeight = this.flameParams['expr'][frame];
-
-        // Root bone rotation
-        const rootAngle = this.flameParams['rotation'][frame];
-        this.setBoneRotation(this.skeleton.bones[0], rootAngle);
+        if (!this.flameParams || !this.skeleton) {
+            logger.warn('Cannot update bones: flameParams or skeleton not initialized');
+            return {};
+        }
 
-        // Neck rotation
-        const neckAngle = this.flameParams['neck_pose'][frame];
-        this.setBoneRotation(this.skeleton.bones[1], neckAngle);
+        const frame = this.frame;
 
-        // Jaw rotation
-        const jawAngle = this.flameParams['jaw_pose'][frame];
-        this.setBoneRotation(this.skeleton.bones[2], jawAngle);
+        // Get blendshape weights for this frame
+        const bsWeight = this.flameParams['expr'][frame];
 
-        // Eyes rotation (combined in eyes_pose array)
-        const eyesAngle = this.flameParams['eyes_pose'][frame];
-        this.setBoneRotation(this.skeleton.bones[3], eyesAngle);
-        this.setBoneRotation(this.skeleton.bones[4], [eyesAngle[3], eyesAngle[4], eyesAngle[5]]);
+        // Apply bone rotations for current frame
+        try {
+            // Root bone rotation (global head orientation)
+            const rootAngle = this.flameParams['rotation'][frame];
+            this.setBoneRotation(this.skeleton.bones[0], rootAngle);
+
+            // Neck rotation
+            const neckAngle = this.flameParams['neck_pose'][frame];
+            this.setBoneRotation(this.skeleton.bones[1], neckAngle);
+
+            // Jaw rotation
+            const jawAngle = this.flameParams['jaw_pose'][frame];
+            this.setBoneRotation(this.skeleton.bones[2], jawAngle);
+
+            // Eyes rotation (6 values: left eye xyz, right eye xyz)
+            const eyesAngle = this.flameParams['eyes_pose'][frame];
+            this.setBoneRotation(this.skeleton.bones[3], eyesAngle.slice(0, 3));          // Left eye
+            this.setBoneRotation(this.skeleton.bones[4], eyesAngle.slice(3, 6));          // Right eye
+        } catch (error) {
+            logger.error('Error setting bone rotations', { frame, error });
+            throw error;
+        }
 
-        // Update skeleton matrices
+        // Update skeleton matrices after all rotations are set
         this.skeleton.update();
 
-        // Get updated bone matrices
+        // Get updated bone matrices for shader
         const numBones = 5;
         const bonesMatrix = FlameTextureManager.getUpdatedBoneMatrices(this.skeleton, numBones);
 
@@ -233,39 +388,109 @@ export class FlameAnimator {
 
     /**
      * Set current animation frame
-     * @param {number} frame - Frame number
+     *
+     * @param {number} frame - Frame number to set (will wrap if exceeds totalFrames)
+     * @throws {ValidationError} If frame is not a valid number
+     * @returns {void}
      */
     setFrame(frame) {
-        this.frame = frame % this.totalFrames;
+        this._assertNotDisposed();
+
+        if (typeof frame !== 'number' || isNaN(frame)) {
+            throw new ValidationError('frame must be a valid number', 'frame');
+        }
+
+        if (this.totalFrames > 0) {
+            this.frame = ((frame % this.totalFrames) + this.totalFrames) % this.totalFrames; // Handle negative
+        } else {
+            this.frame = 0;
+        }
     }
 
     /**
-     * Advance to next frame
+     * Advance to next frame in animation sequence
+     *
+     * Automatically wraps to frame 0 after reaching totalFrames.
+     *
+     * @returns {void}
      */
     nextFrame() {
-        this.frame = (this.frame + 1) % this.totalFrames;
+        this._assertNotDisposed();
+
+        if (this.totalFrames > 0) {
+            this.frame = (this.frame + 1) % this.totalFrames;
+        }
     }
 
     /**
      * Get skeleton for external use
+     *
+     * @returns {THREE.Skeleton|null} The FLAME skeleton or null if not initialized
      */
     getSkeleton() {
+        this._assertNotDisposed();
         return this.skeleton;
     }
 
     /**
      * Get current frame number
+     *
+     * @returns {number} Current animation frame index
      */
     getFrame() {
+        this._assertNotDisposed();
         return this.frame;
     }
 
     /**
      * Get total frame count
+     *
+     * @returns {number} Total number of animation frames
      */
     getTotalFrames() {
+        this._assertNotDisposed();
         return this.totalFrames;
     }
+
+    /**
+     * Dispose animator and free resources
+     *
+     * Properly cleans up:
+     * - Skeleton and bones
+     * - References to meshes and parameters
+     *
+     * @returns {void}
+     */
+    dispose() {
+        if (this._disposed) {
+            logger.warn('FlameAnimator.dispose() called on already disposed instance');
+            return;
+        }
+
+        logger.info('Disposing FlameAnimator');
+
+        // Dispose skeleton (bones are part of skeleton)
+        if (this.skeleton) {
+            this.skeleton.dispose();
+            this.skeleton = null;
+        }
+
+        // Nullify all references to aid GC
+        this.bones = null;
+        this.flameParams = null;
+        this.lbsWeight = null;
+        this.avatarMesh = null;
+
+        // Reset state
+        this.frame = 0;
+        this.totalFrames = 0;
+        this.gaussianSplatCount = 0;
+
+        // Mark as disposed
+        this._disposed = true;
+
+        logger.debug('FlameAnimator disposed successfully');
+    }
 }
 
 export default FlameAnimator;