@mentra/sdk 2.1.2 → 2.1.3

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

@@ -0,0 +1,206 @@
+/**
+ * 🎬 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();
+ * ```
+ */
+import { AppSession } from '../app/session';
+import { LoadFramesOptions } from './bitmap-utils';
+/**
+ * Configuration options for bitmap animations
+ */
+export interface AnimationConfig {
+    /** Time between frames in milliseconds (default: 1750ms - optimized for MentraOS) */
+    intervalMs?: number;
+    /** Whether to loop the animation continuously (default: false) */
+    repeat?: boolean;
+    /** Validate frames before starting animation (default: true) */
+    validateFrames?: boolean;
+    /** Options for loading frames from files */
+    loadOptions?: LoadFramesOptions;
+    /** Callback fired when animation starts */
+    onStart?: () => void;
+    /** Callback fired when animation stops/completes */
+    onStop?: () => void;
+    /** Callback fired on each frame display */
+    onFrame?: (frameIndex: number, totalFrames: number) => void;
+    /** Callback fired if animation encounters an error */
+    onError?: (error: string) => void;
+}
+/**
+ * Animation controller interface
+ */
+export interface AnimationController {
+    /** Stop the animation */
+    stop: () => void;
+    /** Check if animation is currently running */
+    isRunning: () => boolean;
+    /** Get current frame index */
+    getCurrentFrame: () => number;
+    /** Get total frame count */
+    getTotalFrames: () => number;
+}
+/**
+ * Performance timing information
+ */
+export interface TimingInfo {
+    /** Target interval between frames */
+    targetInterval: number;
+    /** Actual measured interval between frames */
+    actualInterval: number;
+    /** Timing drift (difference between target and actual) */
+    drift: number;
+    /** Frame rate (frames per second) */
+    fps: number;
+}
+/**
+ * Utility class for creating and managing animations in MentraOS applications
+ */
+export declare 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: number): Promise<void>;
+    /**
+     * 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 createBitmapAnimation(session: AppSession, basePath: string, frameCount: number, config?: AnimationConfig): Promise<AnimationController>;
+    /**
+     * 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: AppSession, frames: string[], config?: Omit<AnimationConfig, 'loadOptions' | 'validateFrames'>): AnimationController;
+    /**
+     * 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 createBitmapSequence(session: AppSession, sequence: Array<{
+        frame: string;
+        duration: number;
+    }>): Promise<void>;
+    /**
+     * 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 measureTiming(targetInterval: number, measureDuration?: number): Promise<TimingInfo>;
+    /**
+     * 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: 'even-realities-g1' | 'generic'): AnimationConfig;
+    /**
+     * 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 preloadFrames(basePath: string, frameCount: number, options?: LoadFramesOptions): Promise<string[]>;
+}
+//# sourceMappingURL=animation-utils.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"animation-utils.d.ts","sourceRoot":"","sources":["../../src/utils/animation-utils.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAC5C,OAAO,EAAe,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AAEhE;;GAEG;AACH,MAAM,WAAW,eAAe;IAC5B,qFAAqF;IACrF,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,kEAAkE;IAClE,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,gEAAgE;IAChE,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,4CAA4C;IAC5C,WAAW,CAAC,EAAE,iBAAiB,CAAC;IAChC,2CAA2C;IAC3C,OAAO,CAAC,EAAE,MAAM,IAAI,CAAC;IACrB,oDAAoD;IACpD,MAAM,CAAC,EAAE,MAAM,IAAI,CAAC;IACpB,2CAA2C;IAC3C,OAAO,CAAC,EAAE,CAAC,UAAU,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,KAAK,IAAI,CAAC;IAC5D,sDAAsD;IACtD,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;CACrC;AAED;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAChC,yBAAyB;IACzB,IAAI,EAAE,MAAM,IAAI,CAAC;IACjB,8CAA8C;IAC9C,SAAS,EAAE,MAAM,OAAO,CAAC;IACzB,8BAA8B;IAC9B,eAAe,EAAE,MAAM,MAAM,CAAC;IAC9B,4BAA4B;IAC5B,cAAc,EAAE,MAAM,MAAM,CAAC;CAChC;AAED;;GAEG;AACH,MAAM,WAAW,UAAU;IACvB,qCAAqC;IACrC,cAAc,EAAE,MAAM,CAAC;IACvB,8CAA8C;IAC9C,cAAc,EAAE,MAAM,CAAC;IACvB,0DAA0D;IAC1D,KAAK,EAAE,MAAM,CAAC;IACd,qCAAqC;IACrC,GAAG,EAAE,MAAM,CAAC;CACf;AAED;;GAEG;AACH,qBAAa,cAAc;IAEvB;;;;;;;;;;;;OAYG;IACH,MAAM,CAAC,KAAK,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIvC;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2BG;WACU,qBAAqB,CAC9B,OAAO,EAAE,UAAU,EACnB,QAAQ,EAAE,MAAM,EAChB,UAAU,EAAE,MAAM,EAClB,MAAM,GAAE,eAAoB,GAC7B,OAAO,CAAC,mBAAmB,CAAC;IAgD/B;;;;;;;;;;;;;;;OAeG;IACH,MAAM,CAAC,+BAA+B,CAClC,OAAO,EAAE,UAAU,EACnB,MAAM,EAAE,MAAM,EAAE,EAChB,MAAM,GAAE,IAAI,CAAC,eAAe,EAAE,aAAa,GAAG,gBAAgB,CAAM,GACrE,mBAAmB;IAyFtB;;;;;;;;;;;;;;;OAeG;WACU,oBAAoB,CAC7B,OAAO,EAAE,UAAU,EACnB,QAAQ,EAAE,KAAK,CAAC;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAC,GACrD,OAAO,CAAC,IAAI,CAAC;IAuBhB;;;;;;;;;;;;;OAaG;WACU,aAAa,CAAC,cAAc,EAAE,MAAM,EAAE,eAAe,GAAE,MAAc,GAAG,OAAO,CAAC,UAAU,CAAC;IA0CxG;;;;;;;;;;;;;OAaG;IACH,MAAM,CAAC,kBAAkB,CAAC,UAAU,EAAE,mBAAmB,GAAG,SAAS,GAAG,eAAe;IA2BvF;;;;;;;;;;;;;;;;;OAiBG;WACU,aAAa,CACtB,QAAQ,EAAE,MAAM,EAChB,UAAU,EAAE,MAAM,EAClB,OAAO,GAAE,iBAAsB,GAChC,OAAO,CAAC,MAAM,EAAE,CAAC;CAYvB"}

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