@mentra/sdk 2.1.2-alpha.1 → 2.1.3

package/dist/utils/animation-utils.js

@@ -0,0 +1,339 @@
+"use strict";
+/**
+ * 🎬 Animation Utilities Module
+ *
+ * Provides helper functions for creating and managing bitmap animations in MentraOS applications.
+ * Includes timing utilities, animation factories, and performance optimization helpers.
+ *
+ * @example
+ * ```typescript
+ * import { AnimationUtils } from '@mentra/sdk';
+ *
+ * // Create animation from files
+ * const animation = await AnimationUtils.createBitmapAnimation(
+ *   session, './frames', 10, 1750, true
+ * );
+ *
+ * // Simple delay utility
+ * await AnimationUtils.delay(2000);
+ *
+ * // Stop animation
+ * animation.stop();
+ * ```
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AnimationUtils = void 0;
+const bitmap_utils_1 = require("./bitmap-utils");
+/**
+ * Utility class for creating and managing animations in MentraOS applications
+ */
+class AnimationUtils {
+    /**
+     * Simple async delay helper
+     *
+     * @param ms - Milliseconds to delay
+     * @returns Promise that resolves after the specified delay
+     *
+     * @example
+     * ```typescript
+     * console.log('Starting...');
+     * await AnimationUtils.delay(2000);
+     * console.log('2 seconds later!');
+     * ```
+     */
+    static delay(ms) {
+        return new Promise(resolve => setTimeout(resolve, ms));
+    }
+    /**
+     * Create bitmap animation from files with advanced configuration
+     *
+     * @param session - MentraOS app session
+     * @param basePath - Directory containing animation frames
+     * @param frameCount - Number of frames to load
+     * @param config - Animation configuration options
+     * @returns Promise resolving to animation controller
+     *
+     * @example
+     * ```typescript
+     * // Simple animation
+     * const animation = await AnimationUtils.createBitmapAnimation(
+     *   session, './animations', 10
+     * );
+     *
+     * // Advanced configuration
+     * const advancedAnimation = await AnimationUtils.createBitmapAnimation(
+     *   session, './sprites', 8, {
+     *     intervalMs: 1000,
+     *     repeat: true,
+     *     loadOptions: { filePattern: 'sprite_{i}.bmp', startFrame: 0 },
+     *     onFrame: (frame, total) => console.log(`Frame ${frame}/${total}`),
+     *     onError: (error) => console.error('Animation error:', error)
+     *   }
+     * );
+     * ```
+     */
+    static async createBitmapAnimation(session, basePath, frameCount, config = {}) {
+        const { intervalMs = 1750, // Optimized for MentraOS hardware
+        repeat = false, validateFrames = true, loadOptions = {}, onStart, onStop, onFrame, onError } = config;
+        try {
+            console.log(`🎬 Loading ${frameCount} animation frames from ${basePath}...`);
+            // Load frames with validation
+            const frames = await bitmap_utils_1.BitmapUtils.loadBmpFrames(basePath, frameCount, {
+                validateFrames,
+                ...loadOptions
+            });
+            if (frames.length === 0) {
+                throw new Error('No frames loaded for animation');
+            }
+            console.log(`📚 Animation ready: ${frames.length} frames at ${intervalMs}ms intervals`);
+            // Create enhanced animation with the loaded frames
+            return this.createBitmapAnimationFromFrames(session, frames, {
+                intervalMs,
+                repeat,
+                onStart,
+                onStop,
+                onFrame,
+                onError
+            });
+        }
+        catch (error) {
+            const errorMsg = `Failed to create animation: ${error instanceof Error ? error.message : 'Unknown error'}`;
+            console.error(`❌ ${errorMsg}`);
+            if (onError) {
+                onError(errorMsg);
+            }
+            throw new Error(errorMsg);
+        }
+    }
+    /**
+     * Create bitmap animation from pre-loaded frame data
+     *
+     * @param session - MentraOS app session
+     * @param frames - Array of hex-encoded bitmap data
+     * @param config - Animation configuration options
+     * @returns Animation controller
+     *
+     * @example
+     * ```typescript
+     * const frames = ['424d461a...', '424d461b...', '424d461c...'];
+     * const animation = AnimationUtils.createBitmapAnimationFromFrames(
+     *   session, frames, { intervalMs: 1500, repeat: true }
+     * );
+     * ```
+     */
+    static createBitmapAnimationFromFrames(session, frames, config = {}) {
+        const { intervalMs = 1750, repeat = false, onStart, onStop, onFrame, onError } = config;
+        let isRunning = false;
+        let currentFrame = 0;
+        let animationController = null;
+        const controller = {
+            stop: () => {
+                if (animationController) {
+                    animationController.stop();
+                    animationController = null;
+                }
+                isRunning = false;
+                if (onStop) {
+                    onStop();
+                }
+                console.log('🛑 Animation stopped');
+            },
+            isRunning: () => isRunning,
+            getCurrentFrame: () => currentFrame,
+            getTotalFrames: () => frames.length
+        };
+        try {
+            // Start the animation using the session's built-in method
+            animationController = session.layouts.showBitmapAnimation(frames, intervalMs, repeat);
+            isRunning = true;
+            if (onStart) {
+                onStart();
+            }
+            console.log(`🎬 Animation started: ${frames.length} frames at ${intervalMs}ms${repeat ? ' (repeating)' : ''}`);
+            // If we have frame callbacks, we need to track timing manually
+            // This is a limitation of the current SDK - we can't hook into individual frame displays
+            if (onFrame) {
+                let frameTracker = 0;
+                // Call onFrame for the first frame immediately
+                onFrame(frameTracker, frames.length);
+                const frameInterval = setInterval(() => {
+                    if (!isRunning) {
+                        clearInterval(frameInterval);
+                        return;
+                    }
+                    frameTracker = (frameTracker + 1) % frames.length;
+                    onFrame(frameTracker, frames.length);
+                    // If not repeating and we've shown all frames, stop tracking
+                    if (!repeat && frameTracker === frames.length - 1) {
+                        clearInterval(frameInterval);
+                    }
+                }, intervalMs);
+                // Override stop to also clear frame tracking
+                const originalStop = controller.stop;
+                controller.stop = () => {
+                    clearInterval(frameInterval);
+                    originalStop();
+                };
+            }
+        }
+        catch (error) {
+            const errorMsg = `Failed to start animation: ${error instanceof Error ? error.message : 'Unknown error'}`;
+            console.error(`❌ ${errorMsg}`);
+            if (onError) {
+                onError(errorMsg);
+            }
+            throw new Error(errorMsg);
+        }
+        return controller;
+    }
+    /**
+     * Create a sequence of bitmap displays with custom timing
+     *
+     * @param session - MentraOS app session
+     * @param sequence - Array of frame data with individual timing
+     * @returns Promise that resolves when sequence completes
+     *
+     * @example
+     * ```typescript
+     * await AnimationUtils.createBitmapSequence(session, [
+     *   { frame: frame1Hex, duration: 1000 },
+     *   { frame: frame2Hex, duration: 500 },
+     *   { frame: frame3Hex, duration: 2000 }
+     * ]);
+     * ```
+     */
+    static async createBitmapSequence(session, sequence) {
+        console.log(`🎭 Starting bitmap sequence: ${sequence.length} frames with custom timing`);
+        for (let i = 0; i < sequence.length; i++) {
+            const { frame, duration } = sequence[i];
+            try {
+                console.log(`📽️ Sequence frame ${i + 1}/${sequence.length} (${duration}ms)`);
+                session.layouts.showBitmapView(frame);
+                if (i < sequence.length - 1) { // Don't delay after the last frame
+                    await this.delay(duration);
+                }
+            }
+            catch (error) {
+                console.error(`❌ Error in sequence frame ${i + 1}:`, error);
+                throw error;
+            }
+        }
+        console.log('✅ Bitmap sequence completed');
+    }
+    /**
+     * Measure animation timing performance
+     *
+     * @param targetInterval - Expected interval between frames in ms
+     * @param measureDuration - How long to measure in ms (default: 10 seconds)
+     * @returns Promise resolving to timing performance data
+     *
+     * @example
+     * ```typescript
+     * const timing = await AnimationUtils.measureTiming(1750, 10000);
+     * console.log(`Target: ${timing.targetInterval}ms, Actual: ${timing.actualInterval}ms`);
+     * console.log(`Drift: ${timing.drift}ms, FPS: ${timing.fps.toFixed(1)}`);
+     * ```
+     */
+    static async measureTiming(targetInterval, measureDuration = 10000) {
+        return new Promise((resolve) => {
+            const timestamps = [];
+            let startTime = Date.now();
+            const measureInterval = setInterval(() => {
+                timestamps.push(Date.now());
+            }, targetInterval);
+            setTimeout(() => {
+                clearInterval(measureInterval);
+                if (timestamps.length < 2) {
+                    resolve({
+                        targetInterval,
+                        actualInterval: targetInterval,
+                        drift: 0,
+                        fps: 1000 / targetInterval
+                    });
+                    return;
+                }
+                // Calculate actual interval
+                const intervals = [];
+                for (let i = 1; i < timestamps.length; i++) {
+                    intervals.push(timestamps[i] - timestamps[i - 1]);
+                }
+                const actualInterval = intervals.reduce((a, b) => a + b, 0) / intervals.length;
+                const drift = actualInterval - targetInterval;
+                const fps = 1000 / actualInterval;
+                resolve({
+                    targetInterval,
+                    actualInterval,
+                    drift,
+                    fps
+                });
+            }, measureDuration);
+        });
+    }
+    /**
+     * Create optimized animation settings for different hardware
+     *
+     * @param deviceType - Target device type
+     * @returns Recommended animation configuration
+     *
+     * @example
+     * ```typescript
+     * const config = AnimationUtils.getOptimizedConfig('even-realities-g1');
+     * const animation = await AnimationUtils.createBitmapAnimation(
+     *   session, './frames', 10, config
+     * );
+     * ```
+     */
+    static getOptimizedConfig(deviceType) {
+        switch (deviceType) {
+            case 'even-realities-g1':
+                return {
+                    intervalMs: 1650, // Tested optimal timing for Even Realities G1
+                    repeat: false,
+                    validateFrames: true,
+                    loadOptions: {
+                        validateFrames: true,
+                        skipMissingFrames: false
+                    }
+                };
+            case 'generic':
+            default:
+                return {
+                    intervalMs: 1000,
+                    repeat: false,
+                    validateFrames: true,
+                    loadOptions: {
+                        validateFrames: true,
+                        skipMissingFrames: false
+                    }
+                };
+        }
+    }
+    /**
+     * Preload and cache animation frames for better performance
+     *
+     * @param basePath - Directory containing frames
+     * @param frameCount - Number of frames to preload
+     * @param options - Loading options
+     * @returns Promise resolving to cached frame data
+     *
+     * @example
+     * ```typescript
+     * // Preload frames
+     * const cachedFrames = await AnimationUtils.preloadFrames('./animations', 10);
+     *
+     * // Use cached frames multiple times
+     * const animation1 = AnimationUtils.createBitmapAnimationFromFrames(session, cachedFrames);
+     * const animation2 = AnimationUtils.createBitmapAnimationFromFrames(session, cachedFrames);
+     * ```
+     */
+    static async preloadFrames(basePath, frameCount, options = {}) {
+        console.log(`📦 Preloading ${frameCount} frames from ${basePath}...`);
+        const frames = await bitmap_utils_1.BitmapUtils.loadBmpFrames(basePath, frameCount, {
+            validateFrames: true,
+            ...options
+        });
+        console.log(`✅ Preloaded ${frames.length} frames (${frames.reduce((total, frame) => total + frame.length, 0)} total characters)`);
+        return frames;
+    }
+}
+exports.AnimationUtils = AnimationUtils;

package/dist/utils/bitmap-utils.d.ts

@@ -0,0 +1,147 @@
+/**
+ * 🎨 Bitmap Utilities Module
+ *
+ * Provides helper functions for working with bitmap images in MentraOS applications.
+ * Includes file loading, data validation, and format conversion utilities.
+ *
+ * @example
+ * ```typescript
+ * import { BitmapUtils } from '@mentra/sdk';
+ *
+ * // Load a single BMP file
+ * const bmpHex = await BitmapUtils.loadBmpAsHex('./my-image.bmp');
+ * session.layouts.showBitmapView(bmpHex);
+ *
+ * // Load multiple animation frames
+ * const frames = await BitmapUtils.loadBmpFrames('./animations', 10);
+ * session.layouts.showBitmapAnimation(frames, 1500, true);
+ * ```
+ */
+/**
+ * Validation result for bitmap data
+ */
+export interface BitmapValidation {
+    /** Whether the bitmap data is valid */
+    isValid: boolean;
+    /** Total byte count of the bitmap */
+    byteCount: number;
+    /** Number of black (non-FF) pixels found */
+    blackPixels: number;
+    /** Array of validation error messages */
+    errors: string[];
+    /** Additional metadata about the bitmap */
+    metadata?: {
+        /** Expected bitmap dimensions (if detectable) */
+        dimensions?: {
+            width: number;
+            height: number;
+        };
+        /** Bitmap file format info */
+        format?: string;
+    };
+}
+/**
+ * Options for loading bitmap frames
+ */
+export interface LoadFramesOptions {
+    /** File name pattern (default: 'animation_10_frame_{i}.bmp') */
+    filePattern?: string;
+    /** Starting frame number (default: 1) */
+    startFrame?: number;
+    /** Validate each frame during loading (default: true) */
+    validateFrames?: boolean;
+    /** Continue loading if a frame is missing (default: false) */
+    skipMissingFrames?: boolean;
+}
+/**
+ * Utility class for working with bitmap images in MentraOS applications
+ */
+export declare class BitmapUtils {
+    /**
+     * Load a BMP file as hex string from filesystem
+     *
+     * @param filePath - Path to the BMP file
+     * @returns Promise resolving to hex-encoded bitmap data
+     * @throws Error if file cannot be read or is not a valid BMP
+     *
+     * @example
+     * ```typescript
+     * const bmpHex = await BitmapUtils.loadBmpAsHex('./assets/icon.bmp');
+     * session.layouts.showBitmapView(bmpHex);
+     * ```
+     */
+    static loadBmpAsHex(filePath: string): Promise<string>;
+    /**
+     * Load multiple BMP frames as hex array for animations
+     *
+     * @param basePath - Directory containing the frame files
+     * @param frameCount - Number of frames to load
+     * @param options - Loading options and configuration
+     * @returns Promise resolving to array of hex-encoded bitmap data
+     *
+     * @example
+     * ```typescript
+     * // Load 10 frames with default pattern
+     * const frames = await BitmapUtils.loadBmpFrames('./animations', 10);
+     *
+     * // Load with custom pattern
+     * const customFrames = await BitmapUtils.loadBmpFrames('./sprites', 8, {
+     *   filePattern: 'sprite_{i}.bmp',
+     *   startFrame: 0
+     * });
+     * ```
+     */
+    static loadBmpFrames(basePath: string, frameCount: number, options?: LoadFramesOptions): Promise<string[]>;
+    /**
+     * Validate BMP hex data integrity and extract metadata
+     *
+     * @param hexString - Hex-encoded bitmap data
+     * @returns Validation result with detailed information
+     *
+     * @example
+     * ```typescript
+     * const validation = BitmapUtils.validateBmpHex(bmpHex);
+     * if (!validation.isValid) {
+     *   console.error('Invalid bitmap:', validation.errors);
+     * } else {
+     *   console.log(`Valid bitmap: ${validation.blackPixels} black pixels`);
+     * }
+     * ```
+     */
+    static validateBmpHex(hexString: string): BitmapValidation;
+    /**
+     * Convert bitmap data between different formats
+     *
+     * @param data - Input bitmap data
+     * @param fromFormat - Source format ('hex' | 'base64' | 'buffer')
+     * @param toFormat - Target format ('hex' | 'base64' | 'buffer')
+     * @returns Converted bitmap data
+     *
+     * @example
+     * ```typescript
+     * const base64Data = BitmapUtils.convertFormat(hexData, 'hex', 'base64');
+     * const bufferData = BitmapUtils.convertFormat(base64Data, 'base64', 'buffer');
+     * ```
+     */
+    static convertFormat(data: string | Buffer, fromFormat: 'hex' | 'base64' | 'buffer', toFormat: 'hex' | 'base64' | 'buffer'): string | Buffer;
+    /**
+     * Get bitmap information without full validation
+     *
+     * @param hexString - Hex-encoded bitmap data
+     * @returns Basic bitmap information
+     *
+     * @example
+     * ```typescript
+     * const info = BitmapUtils.getBitmapInfo(bmpHex);
+     * console.log(`Bitmap: ${info.width}x${info.height}, ${info.blackPixels} black pixels`);
+     * ```
+     */
+    static getBitmapInfo(hexString: string): {
+        byteCount: number;
+        blackPixels: number;
+        width?: number;
+        height?: number;
+        isValidBmp: boolean;
+    };
+}
+//# sourceMappingURL=bitmap-utils.d.ts.map

package/dist/utils/bitmap-utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bitmap-utils.d.ts","sourceRoot":"","sources":["../../src/utils/bitmap-utils.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAKH;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,uCAAuC;IACvC,OAAO,EAAE,OAAO,CAAC;IACjB,qCAAqC;IACrC,SAAS,EAAE,MAAM,CAAC;IAClB,4CAA4C;IAC5C,WAAW,EAAE,MAAM,CAAC;IACpB,yCAAyC;IACzC,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,2CAA2C;IAC3C,QAAQ,CAAC,EAAE;QACT,iDAAiD;QACjD,UAAU,CAAC,EAAE;YAAE,KAAK,EAAE,MAAM,CAAC;YAAC,MAAM,EAAE,MAAM,CAAA;SAAE,CAAC;QAC/C,8BAA8B;QAC9B,MAAM,CAAC,EAAE,MAAM,CAAC;KACjB,CAAC;CACH;AAED;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,gEAAgE;IAChE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,yCAAyC;IACzC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,yDAAyD;IACzD,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,8DAA8D;IAC9D,iBAAiB,CAAC,EAAE,OAAO,CAAC;CAC7B;AAED;;GAEG;AACH,qBAAa,WAAW;IAEtB;;;;;;;;;;;;OAYG;WACU,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAqB5D;;;;;;;;;;;;;;;;;;;OAmBG;WACU,aAAa,CACxB,QAAQ,EAAE,MAAM,EAChB,UAAU,EAAE,MAAM,EAClB,OAAO,GAAE,iBAAsB,GAC9B,OAAO,CAAC,MAAM,EAAE,CAAC;IA0DpB;;;;;;;;;;;;;;;OAeG;IACH,MAAM,CAAC,cAAc,CAAC,SAAS,EAAE,MAAM,GAAG,gBAAgB;IAkF1D;;;;;;;;;;;;;OAaG;IACH,MAAM,CAAC,aAAa,CAClB,IAAI,EAAE,MAAM,GAAG,MAAM,EACrB,UAAU,EAAE,KAAK,GAAG,QAAQ,GAAG,QAAQ,EACvC,QAAQ,EAAE,KAAK,GAAG,QAAQ,GAAG,QAAQ,GACpC,MAAM,GAAG,MAAM;IA+BlB;;;;;;;;;;;OAWG;IACH,MAAM,CAAC,aAAa,CAAC,SAAS,EAAE,MAAM,GAAG;QACvC,SAAS,EAAE,MAAM,CAAC;QAClB,WAAW,EAAE,MAAM,CAAC;QACpB,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,UAAU,EAAE,OAAO,CAAC;KACrB;CAmCF"}