@ume-group/contracts 0.2.1

package/dist/segmentation/MediaPipeSegmenter.d.ts

@@ -0,0 +1,201 @@
+/**
+ * MediaPipeSegmenter.ts - AI-based background segmentation using MediaPipe
+ *
+ * Wraps MediaPipe Image Segmenter to process webcam frames and produce
+ * segmentation masks for background removal.
+ *
+ * Key features:
+ * - Async initialization (model loading)
+ * - Frame-by-frame processing with mask output
+ * - Mobile-optimized resolution scaling
+ * - Temporal smoothing with anti-flicker measures
+ * - Proper resource cleanup
+ *
+ * ArchiMate: Application Component (AI Segmentation Engine)
+ */
+/**
+ * AI model quality mode
+ * - 'fast': selfie_segmenter (float16, 256x256) — quick, good for close-up
+ * - 'quality': DeepLabV3 (float32, PASCAL VOC 21-class) — better at distance, slower
+ */
+export type AIModelType = 'fast' | 'quality';
+/**
+ * Asset URLs for MediaPipe loading
+ * Can be configured to use self-hosted assets for better reliability at scale
+ */
+export interface MediaPipeAssetUrls {
+    /** WASM files URL (default: jsdelivr CDN) */
+    wasmUrl: string;
+    /** Model file URL (default: Google Storage) */
+    modelUrl: string;
+}
+/**
+ * Default asset URLs - external CDNs
+ * For production at scale, self-host these on Cloudflare R2
+ */
+export declare const DEFAULT_ASSET_URLS: MediaPipeAssetUrls;
+/**
+ * DeepLabV3 model URL — PASCAL VOC 21-class segmentation
+ * Person = class index 15. Float32, heavier but better at distance.
+ */
+export declare const DEEPLAB_MODEL_URL = "https://storage.googleapis.com/mediapipe-models/image_segmenter/deeplab_v3/float32/latest/deeplab_v3.tflite";
+/**
+ * Self-hosted asset URLs on Includu R2 (for enterprise scale)
+ * TODO: Upload MediaPipe assets to R2 and enable these URLs
+ */
+export declare const SELF_HOSTED_ASSET_URLS: MediaPipeAssetUrls;
+/**
+ * Configuration for the segmenter
+ */
+export interface SegmenterConfig {
+    /** Processing resolution width (default: 640) */
+    width: number;
+    /** Processing resolution height (default: 480) */
+    height: number;
+    /** Mask threshold 0-1 (default: 0.7) */
+    threshold: number;
+    /** Edge blur radius in pixels (default: 3) */
+    edgeBlur: number;
+    /** Asset URLs for MediaPipe (default: external CDNs) */
+    assetUrls?: MediaPipeAssetUrls;
+    /** Model type: 'fast' (selfie_segmenter) or 'quality' (DeepLabV3) */
+    modelType?: AIModelType;
+}
+/**
+ * Default configuration optimized for balance of quality and performance
+ */
+export declare const DEFAULT_SEGMENTER_CONFIG: SegmenterConfig;
+/**
+ * Result from segmentation processing
+ */
+export interface SegmentationResult {
+    /** The mask as ImageData (grayscale, white = person) */
+    maskData: ImageData;
+    /** The mask canvas element (can be used as texture source) */
+    maskCanvas: HTMLCanvasElement;
+    /** Processing time in milliseconds */
+    processingTimeMs: number;
+}
+/**
+ * MediaPipe-based background segmentation
+ *
+ * Usage:
+ * ```typescript
+ * const segmenter = new MediaPipeSegmenter();
+ * await segmenter.initialize();
+ *
+ * // In render loop
+ * const result = segmenter.process(videoElement);
+ * // Use result.maskCanvas as texture source
+ *
+ * // Cleanup
+ * segmenter.dispose();
+ * ```
+ */
+export declare class MediaPipeSegmenter {
+    private segmenter;
+    private workCanvas;
+    private workCtx;
+    private outputCanvas;
+    private outputCtx;
+    private tempCanvas;
+    private tempCtx;
+    private config;
+    private isInitialized;
+    private isInitializing;
+    private _modelType;
+    private static readonly DEEPLAB_PERSON_INDEX;
+    private previousAlpha;
+    private backgroundPersistence;
+    private readonly persistenceThreshold;
+    private readonly persistenceThresholdLowLatency;
+    private readonly temporalBlendNormal;
+    private readonly temporalBlendLowLatency;
+    private readonly hysteresisOffset;
+    private lowLatencyMode;
+    constructor(config?: Partial<SegmenterConfig>);
+    /**
+     * Initialize MediaPipe model
+     */
+    initialize(): Promise<void>;
+    /**
+     * Process a video frame and return segmentation mask
+     */
+    process(video: HTMLVideoElement): SegmentationResult | null;
+    /**
+     * Process MediaPipe result into a usable mask
+     */
+    private processMask;
+    /**
+     * Copy work canvas to output canvas
+     */
+    private copyWorkToOutput;
+    /**
+     * Apply morphological dilation to fill small holes in the mask.
+     * Uses a 4-connected max-filter: draws the mask shifted 1px in each
+     * cardinal direction with 'lighten' blend (pixel max). This expands
+     * bright regions by 1px, filling 1-2px holes common at distance.
+     */
+    private applyDilation;
+    /**
+     * Apply Gaussian blur to soften mask edges
+     */
+    private applyEdgeBlur;
+    /**
+     * Reset temporal smoothing buffers.
+     * Call when the video source changes (camera switch) to avoid
+     * stale mask data from the previous camera bleeding into the new one.
+     */
+    reset(): void;
+    /**
+     * Update segmentation threshold
+     */
+    setThreshold(threshold: number): void;
+    /**
+     * Update edge blur radius
+     */
+    setEdgeBlur(edgeBlur: number): void;
+    /**
+     * Enable/disable low latency mode
+     */
+    setLowLatency(enabled: boolean): void;
+    /**
+     * Switch between fast (selfie_segmenter) and quality (DeepLabV3) models.
+     * Disposes the current model and re-initializes with the new one.
+     * Returns a promise that resolves when the new model is ready.
+     */
+    switchModel(modelType: AIModelType): Promise<void>;
+    /**
+     * Get the current model type
+     */
+    get currentModelType(): AIModelType;
+    /**
+     * Get current configuration
+     */
+    getConfig(): SegmenterConfig;
+    /**
+     * Check if segmenter is ready
+     */
+    get ready(): boolean;
+    /**
+     * Check if segmenter is currently loading
+     */
+    get loading(): boolean;
+    /**
+     * Get the output mask canvas for use as texture source
+     */
+    getMaskCanvas(): HTMLCanvasElement;
+    /**
+     * Clean up resources
+     */
+    dispose(): void;
+}
+/**
+ * Detect if running on mobile device
+ */
+export declare function isMobileDevice(): boolean;
+/**
+ * Get optimal processing configuration based on device
+ */
+export declare function getOptimalConfig(): Partial<SegmenterConfig>;
+//# sourceMappingURL=MediaPipeSegmenter.d.ts.map

package/dist/segmentation/MediaPipeSegmenter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"MediaPipeSegmenter.d.ts","sourceRoot":"","sources":["../../src/segmentation/MediaPipeSegmenter.ts"],"names":[],"mappings":"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"}

package/dist/segmentation/MediaPipeSegmenter.js

@@ -0,0 +1,434 @@
+/**
+ * MediaPipeSegmenter.ts - AI-based background segmentation using MediaPipe
+ *
+ * Wraps MediaPipe Image Segmenter to process webcam frames and produce
+ * segmentation masks for background removal.
+ *
+ * Key features:
+ * - Async initialization (model loading)
+ * - Frame-by-frame processing with mask output
+ * - Mobile-optimized resolution scaling
+ * - Temporal smoothing with anti-flicker measures
+ * - Proper resource cleanup
+ *
+ * ArchiMate: Application Component (AI Segmentation Engine)
+ */
+import { DEBUG } from '../index';
+import { ImageSegmenter, FilesetResolver } from '@mediapipe/tasks-vision';
+/**
+ * Default asset URLs - external CDNs
+ * For production at scale, self-host these on Cloudflare R2
+ */
+export const DEFAULT_ASSET_URLS = {
+    wasmUrl: 'https://cdn.jsdelivr.net/npm/@mediapipe/tasks-vision@0.10.32/wasm',
+    modelUrl: 'https://storage.googleapis.com/mediapipe-models/image_segmenter/selfie_segmenter/float16/latest/selfie_segmenter.tflite'
+};
+/**
+ * DeepLabV3 model URL — PASCAL VOC 21-class segmentation
+ * Person = class index 15. Float32, heavier but better at distance.
+ */
+export const DEEPLAB_MODEL_URL = 'https://storage.googleapis.com/mediapipe-models/image_segmenter/deeplab_v3/float32/latest/deeplab_v3.tflite';
+/**
+ * Self-hosted asset URLs on Includu R2 (for enterprise scale)
+ * TODO: Upload MediaPipe assets to R2 and enable these URLs
+ */
+export const SELF_HOSTED_ASSET_URLS = {
+    wasmUrl: 'https://pub-55570832bee446f4a0bb149a53ad7050.r2.dev/mediapipe/wasm',
+    modelUrl: 'https://pub-55570832bee446f4a0bb149a53ad7050.r2.dev/mediapipe/models/selfie_segmenter.tflite'
+};
+/**
+ * Default configuration optimized for balance of quality and performance
+ */
+export const DEFAULT_SEGMENTER_CONFIG = {
+    width: 640,
+    height: 480,
+    threshold: 0.7,
+    edgeBlur: 3,
+    assetUrls: DEFAULT_ASSET_URLS
+};
+/**
+ * MediaPipe-based background segmentation
+ *
+ * Usage:
+ * ```typescript
+ * const segmenter = new MediaPipeSegmenter();
+ * await segmenter.initialize();
+ *
+ * // In render loop
+ * const result = segmenter.process(videoElement);
+ * // Use result.maskCanvas as texture source
+ *
+ * // Cleanup
+ * segmenter.dispose();
+ * ```
+ */
+export class MediaPipeSegmenter {
+    segmenter = null;
+    // Double-buffered mask canvases to prevent flickering
+    workCanvas;
+    workCtx;
+    outputCanvas;
+    outputCtx;
+    tempCanvas;
+    tempCtx;
+    config;
+    isInitialized = false;
+    isInitializing = false;
+    _modelType = 'fast';
+    // DeepLabV3 PASCAL VOC person class index
+    static DEEPLAB_PERSON_INDEX = 15;
+    // Temporal smoothing buffers
+    previousAlpha = null;
+    backgroundPersistence = null;
+    // Anti-flicker settings — tuned to prevent "big chunk" flicker at ~1m distance
+    // where the model's confidence oscillates on large body regions.
+    // Persistence: how many consecutive low-confidence frames before converting to background
+    // Higher values = more stable but slower to remove background when person moves out
+    persistenceThreshold = 8;
+    persistenceThresholdLowLatency = 4;
+    // Temporal blend: how much of current frame vs previous (1.0 = all current, 0.0 = all previous)
+    // Lower values = smoother but more lag; critical for noisy confidence at distance
+    temporalBlendNormal = 0.40;
+    temporalBlendLowLatency = 0.65;
+    // Hysteresis: once a pixel is "person", it needs to drop further to become background
+    // Higher values = more stable at edges where confidence fluctuates
+    hysteresisOffset = 0.25;
+    lowLatencyMode = true;
+    constructor(config = {}) {
+        this.config = { ...DEFAULT_SEGMENTER_CONFIG, ...config };
+        this._modelType = this.config.modelType ?? 'fast';
+        // Create work canvas
+        this.workCanvas = document.createElement('canvas');
+        this.workCanvas.width = this.config.width;
+        this.workCanvas.height = this.config.height;
+        this.workCtx = this.workCanvas.getContext('2d', { willReadFrequently: true });
+        // Create output canvas
+        this.outputCanvas = document.createElement('canvas');
+        this.outputCanvas.width = this.config.width;
+        this.outputCanvas.height = this.config.height;
+        this.outputCtx = this.outputCanvas.getContext('2d', { willReadFrequently: true });
+        // Create temp canvas
+        this.tempCanvas = document.createElement('canvas');
+        this.tempCanvas.width = this.config.width;
+        this.tempCanvas.height = this.config.height;
+        this.tempCtx = this.tempCanvas.getContext('2d', { willReadFrequently: true });
+        // Initialize buffers
+        this.previousAlpha = new Uint8Array(this.config.width * this.config.height);
+        this.backgroundPersistence = new Uint8Array(this.config.width * this.config.height);
+    }
+    /**
+     * Initialize MediaPipe model
+     */
+    async initialize() {
+        if (this.isInitialized || this.isInitializing) {
+            return;
+        }
+        this.isInitializing = true;
+        try {
+            const assetUrls = this.config.assetUrls ?? DEFAULT_ASSET_URLS;
+            if (DEBUG)
+                console.log('[MediaPipeSegmenter] Loading MediaPipe vision WASM from:', assetUrls.wasmUrl);
+            const vision = await FilesetResolver.forVisionTasks(assetUrls.wasmUrl);
+            // Select model URL based on modelType
+            const modelUrl = this._modelType === 'quality'
+                ? DEEPLAB_MODEL_URL
+                : assetUrls.modelUrl;
+            if (DEBUG)
+                console.log(`[MediaPipeSegmenter] Creating image segmenter (${this._modelType}) with model:`, modelUrl);
+            // CPU delegate avoids WebGL context conflicts with Three.js.
+            // GPU delegate creates its own WebGL context which can produce
+            // all-zero inference results when sharing the GPU with Three.js.
+            this.segmenter = await ImageSegmenter.createFromOptions(vision, {
+                baseOptions: {
+                    modelAssetPath: modelUrl,
+                    delegate: 'CPU'
+                },
+                runningMode: 'VIDEO',
+                outputCategoryMask: false,
+                outputConfidenceMasks: true
+            });
+            this.isInitialized = true;
+            if (DEBUG)
+                console.log(`[MediaPipeSegmenter] Initialization complete (${this._modelType})`);
+        }
+        catch (error) {
+            console.error('[MediaPipeSegmenter] Failed to initialize:', error);
+            throw error;
+        }
+        finally {
+            this.isInitializing = false;
+        }
+    }
+    /**
+     * Process a video frame and return segmentation mask
+     */
+    process(video) {
+        if (!this.isInitialized || !this.segmenter) {
+            console.warn('[MediaPipeSegmenter] Not initialized, skipping frame');
+            return null;
+        }
+        if (video.readyState < 2) {
+            return null;
+        }
+        const startTime = performance.now();
+        try {
+            // Contrast enhancement: mild boost helps the model distinguish
+            // person from background, especially at distance or in flat lighting.
+            // Applied before inference so the model sees a clearer input.
+            this.tempCtx.filter = 'contrast(1.15) saturate(1.1)';
+            this.tempCtx.drawImage(video, 0, 0, this.config.width, this.config.height);
+            this.tempCtx.filter = 'none';
+            const result = this.segmenter.segmentForVideo(this.tempCanvas, performance.now());
+            this.processMask(result);
+            const processingTimeMs = performance.now() - startTime;
+            return {
+                maskData: this.outputCtx.getImageData(0, 0, this.config.width, this.config.height),
+                maskCanvas: this.outputCanvas,
+                processingTimeMs
+            };
+        }
+        catch (error) {
+            console.error('[MediaPipeSegmenter] Processing error:', error);
+            return null;
+        }
+    }
+    /**
+     * Process MediaPipe result into a usable mask
+     */
+    processMask(result) {
+        const confidenceMasks = result.confidenceMasks;
+        if (!confidenceMasks || confidenceMasks.length === 0) {
+            this.workCtx.clearRect(0, 0, this.config.width, this.config.height);
+            this.copyWorkToOutput();
+            return;
+        }
+        // selfie_segmenter: person = confidenceMasks[0]
+        // DeepLabV3 PASCAL VOC: person = confidenceMasks[15] (21 classes)
+        const personIndex = this._modelType === 'quality'
+            ? MediaPipeSegmenter.DEEPLAB_PERSON_INDEX
+            : 0;
+        if (personIndex >= confidenceMasks.length) {
+            this.workCtx.clearRect(0, 0, this.config.width, this.config.height);
+            this.copyWorkToOutput();
+            return;
+        }
+        const personMask = confidenceMasks[personIndex];
+        const maskData = personMask.getAsFloat32Array();
+        const imageData = this.workCtx.createImageData(this.config.width, this.config.height);
+        const data = imageData.data;
+        const threshold = this.config.threshold;
+        const blendFactor = this.lowLatencyMode ? this.temporalBlendLowLatency : this.temporalBlendNormal;
+        const prevAlpha = this.previousAlpha;
+        const persistence = this.backgroundPersistence;
+        const persistThreshold = this.lowLatencyMode ? this.persistenceThresholdLowLatency : this.persistenceThreshold;
+        const hysteresis = this.hysteresisOffset;
+        for (let i = 0; i < maskData.length; i++) {
+            const confidence = maskData[i];
+            const wasPerson = prevAlpha && prevAlpha[i] > 127;
+            const effectiveThreshold = wasPerson ? threshold - hysteresis : threshold;
+            const isPersonThisFrame = confidence >= effectiveThreshold;
+            let alpha;
+            if (isPersonThisFrame) {
+                if (persistence) {
+                    persistence[i] = 0;
+                }
+                if (confidence >= effectiveThreshold + 0.1) {
+                    alpha = 255;
+                }
+                else {
+                    alpha = Math.round(((confidence - effectiveThreshold) / 0.1) * 127.5 + 127.5);
+                }
+            }
+            else {
+                if (persistence) {
+                    persistence[i] = Math.min(255, persistence[i] + 1);
+                    if (persistence[i] < persistThreshold) {
+                        alpha = prevAlpha ? prevAlpha[i] : 0;
+                    }
+                    else {
+                        if (confidence <= effectiveThreshold - 0.1) {
+                            alpha = 0;
+                        }
+                        else {
+                            alpha = Math.round(((confidence - (effectiveThreshold - 0.1)) / 0.1) * 127.5);
+                        }
+                    }
+                }
+                else {
+                    alpha = confidence <= effectiveThreshold - 0.1 ? 0 :
+                        Math.round(((confidence - (effectiveThreshold - 0.1)) / 0.2) * 255);
+                }
+            }
+            if (prevAlpha) {
+                alpha = Math.round(alpha * blendFactor + prevAlpha[i] * (1 - blendFactor));
+                prevAlpha[i] = alpha;
+            }
+            data[i * 4] = alpha;
+            data[i * 4 + 1] = alpha;
+            data[i * 4 + 2] = alpha;
+            data[i * 4 + 3] = 255;
+        }
+        this.workCtx.putImageData(imageData, 0, 0);
+        // Dilation pass: fills small 1-2px holes common when subject is far from camera
+        this.applyDilation();
+        if (this.config.edgeBlur > 0) {
+            this.applyEdgeBlur();
+        }
+        this.copyWorkToOutput();
+        // Close all returned masks to free memory.
+        // DeepLabV3 returns 21 masks (PASCAL VOC classes), selfie_segmenter returns 1.
+        for (const mask of confidenceMasks) {
+            mask.close();
+        }
+    }
+    /**
+     * Copy work canvas to output canvas
+     */
+    copyWorkToOutput() {
+        this.outputCtx.drawImage(this.workCanvas, 0, 0);
+    }
+    /**
+     * Apply morphological dilation to fill small holes in the mask.
+     * Uses a 4-connected max-filter: draws the mask shifted 1px in each
+     * cardinal direction with 'lighten' blend (pixel max). This expands
+     * bright regions by 1px, filling 1-2px holes common at distance.
+     */
+    applyDilation() {
+        // Copy current mask to temp canvas as read-only source
+        // (tempCanvas is safe to reuse — video frame processing is complete)
+        this.tempCtx.clearRect(0, 0, this.config.width, this.config.height);
+        this.tempCtx.drawImage(this.workCanvas, 0, 0);
+        // Draw 4 shifted copies using 'lighten' (takes max per-pixel)
+        this.workCtx.save();
+        this.workCtx.globalCompositeOperation = 'lighten';
+        this.workCtx.drawImage(this.tempCanvas, -1, 0);
+        this.workCtx.drawImage(this.tempCanvas, 1, 0);
+        this.workCtx.drawImage(this.tempCanvas, 0, -1);
+        this.workCtx.drawImage(this.tempCanvas, 0, 1);
+        this.workCtx.restore();
+    }
+    /**
+     * Apply Gaussian blur to soften mask edges
+     */
+    applyEdgeBlur() {
+        this.workCtx.filter = `blur(${this.config.edgeBlur}px)`;
+        this.workCtx.drawImage(this.workCanvas, 0, 0);
+        this.workCtx.filter = 'none';
+    }
+    /**
+     * Reset temporal smoothing buffers.
+     * Call when the video source changes (camera switch) to avoid
+     * stale mask data from the previous camera bleeding into the new one.
+     */
+    reset() {
+        if (this.previousAlpha)
+            this.previousAlpha.fill(0);
+        if (this.backgroundPersistence)
+            this.backgroundPersistence.fill(0);
+    }
+    /**
+     * Update segmentation threshold
+     */
+    setThreshold(threshold) {
+        this.config.threshold = Math.max(0, Math.min(1, threshold));
+    }
+    /**
+     * Update edge blur radius
+     */
+    setEdgeBlur(edgeBlur) {
+        this.config.edgeBlur = Math.max(0, Math.min(20, edgeBlur));
+    }
+    /**
+     * Enable/disable low latency mode
+     */
+    setLowLatency(enabled) {
+        this.lowLatencyMode = enabled;
+    }
+    /**
+     * Switch between fast (selfie_segmenter) and quality (DeepLabV3) models.
+     * Disposes the current model and re-initializes with the new one.
+     * Returns a promise that resolves when the new model is ready.
+     */
+    async switchModel(modelType) {
+        if (modelType === this._modelType && this.isInitialized) {
+            return;
+        }
+        this._modelType = modelType;
+        // Dispose current model and re-initialize
+        if (this.segmenter) {
+            this.segmenter.close();
+            this.segmenter = null;
+        }
+        this.isInitialized = false;
+        this.reset();
+        await this.initialize();
+    }
+    /**
+     * Get the current model type
+     */
+    get currentModelType() {
+        return this._modelType;
+    }
+    /**
+     * Get current configuration
+     */
+    getConfig() {
+        return { ...this.config };
+    }
+    /**
+     * Check if segmenter is ready
+     */
+    get ready() {
+        return this.isInitialized;
+    }
+    /**
+     * Check if segmenter is currently loading
+     */
+    get loading() {
+        return this.isInitializing;
+    }
+    /**
+     * Get the output mask canvas for use as texture source
+     */
+    getMaskCanvas() {
+        return this.outputCanvas;
+    }
+    /**
+     * Clean up resources
+     */
+    dispose() {
+        if (this.segmenter) {
+            this.segmenter.close();
+            this.segmenter = null;
+        }
+        this.isInitialized = false;
+        if (DEBUG)
+            console.log('[MediaPipeSegmenter] Disposed');
+    }
+}
+/**
+ * Detect if running on mobile device
+ */
+export function isMobileDevice() {
+    if (typeof navigator === 'undefined')
+        return false;
+    return (/iPhone|iPad|Android/i.test(navigator.userAgent) ||
+        (typeof window !== 'undefined' && window.innerWidth < 768));
+}
+/**
+ * Get optimal processing configuration based on device
+ */
+export function getOptimalConfig() {
+    if (isMobileDevice()) {
+        return {
+            width: 320,
+            height: 240,
+            edgeBlur: 2
+        };
+    }
+    return {
+        width: 640,
+        height: 480,
+        edgeBlur: 3
+    };
+}

package/dist/segmentation/index.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Segmentation module exports
+ */
+export { MediaPipeSegmenter, type SegmenterConfig, type SegmentationResult, type MediaPipeAssetUrls, type AIModelType, DEFAULT_SEGMENTER_CONFIG, DEFAULT_ASSET_URLS, DEEPLAB_MODEL_URL, SELF_HOSTED_ASSET_URLS, isMobileDevice, getOptimalConfig } from './MediaPipeSegmenter';
+//# sourceMappingURL=index.d.ts.map

package/dist/segmentation/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/segmentation/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EACN,kBAAkB,EAClB,KAAK,eAAe,EACpB,KAAK,kBAAkB,EACvB,KAAK,kBAAkB,EACvB,KAAK,WAAW,EAChB,wBAAwB,EACxB,kBAAkB,EAClB,iBAAiB,EACjB,sBAAsB,EACtB,cAAc,EACd,gBAAgB,EAChB,MAAM,sBAAsB,CAAC"}

package/dist/segmentation/index.js

@@ -0,0 +1,4 @@
+/**
+ * Segmentation module exports
+ */
+export { MediaPipeSegmenter, DEFAULT_SEGMENTER_CONFIG, DEFAULT_ASSET_URLS, DEEPLAB_MODEL_URL, SELF_HOSTED_ASSET_URLS, isMobileDevice, getOptimalConfig } from './MediaPipeSegmenter';