@srsergio/taptapp-ar 1.0.77 → 1.0.79

package/dist/compiler/offline-compiler.js

@@ -10,7 +10,6 @@ import { extractTrackingFeatures } from "./tracker/extract-utils.js";
 import { DetectorLite } from "./detector/detector-lite.js";
 import { build as hierarchicalClusteringBuild } from "./matching/hierarchical-clustering.js";
 import * as msgpack from "@msgpack/msgpack";
-import { WorkerPool } from "./utils/worker-pool.js";
 // Detect environment
 const isNode = typeof process !== "undefined" &&
     process.versions != null &&
@@ -18,35 +17,8 @@ const isNode = typeof process !== "undefined" &&
 const CURRENT_VERSION = 7; // Protocol v7: Moonshot - 4-bit Packed Tracking Data
 export class OfflineCompiler {
     data = null;
-    workerPool = null;
     constructor() {
-        // Workers only in Node.js
-        if (!isNode) {
-            console.log("🌐 OfflineCompiler: Browser mode (no workers)");
-        }
-    }
-    async _initNodeWorkers() {
-        try {
-            const pathModule = "path";
-            const urlModule = "url";
-            const osModule = "os";
-            const workerThreadsModule = "node:worker_threads";
-            const [path, url, os, { Worker }] = await Promise.all([
-                import(/* @vite-ignore */ pathModule),
-                import(/* @vite-ignore */ urlModule),
-                import(/* @vite-ignore */ osModule),
-                import(/* @vite-ignore */ workerThreadsModule)
-            ]);
-            const __filename = url.fileURLToPath(import.meta.url);
-            const __dirname = path.dirname(__filename);
-            const workerPath = path.join(__dirname, "node-worker.js");
-            // Limit workers to avoid freezing system
-            const numWorkers = Math.min(os.cpus().length, 4);
-            this.workerPool = new WorkerPool(workerPath, numWorkers, Worker);
-        }
-        catch (e) {
-            console.log("⚡ OfflineCompiler: Running without workers (initialization failed)", e);
-        }
+        console.log("⚡ OfflineCompiler: Main thread mode (no workers)");
     }
     async compileImageTargets(images, progressCallback) {
         console.time("⏱️ Compilación total");
@@ -86,24 +58,7 @@ export class OfflineCompiler {
         return this.data;
     }
     async _compileTarget(targetImages, progressCallback) {
-        if (isNode)
-            await this._initNodeWorkers();
-        if (this.workerPool) {
-            const progressMap = new Float32Array(targetImages.length);
-            const wrappedPromises = targetImages.map((targetImage, index) => {
-                return this.workerPool.runTask({
-                    type: 'compile-all', // 🚀 MOONSHOT: Combined task
-                    targetImage,
-                    onProgress: (p) => {
-                        progressMap[index] = p;
-                        const sum = progressMap.reduce((a, b) => a + b, 0);
-                        progressCallback(sum / targetImages.length);
-                    }
-                });
-            });
-            return Promise.all(wrappedPromises);
-        }
-        // Fallback or non-worker implementation: run match and track sequentially
+        // Run match and track sequentially to match browser behavior exactly
         const matchingResults = await this._compileMatch(targetImages, (p) => progressCallback(p * 0.5));
         const trackingResults = await this._compileTrack(targetImages, (p) => progressCallback(50 + p * 0.5));
         return targetImages.map((_, i) => ({
@@ -114,25 +69,6 @@ export class OfflineCompiler {
     async _compileMatch(targetImages, progressCallback) {
         const percentPerImage = 100 / targetImages.length;
         let currentPercent = 0;
-        if (isNode)
-            await this._initNodeWorkers();
-        if (this.workerPool) {
-            const progressMap = new Float32Array(targetImages.length);
-            const wrappedPromises = targetImages.map((targetImage, index) => {
-                return this.workerPool.runTask({
-                    type: 'match',
-                    targetImage,
-                    percentPerImage,
-                    basePercent: 0,
-                    onProgress: (p) => {
-                        progressMap[index] = p;
-                        const sum = progressMap.reduce((a, b) => a + b, 0);
-                        progressCallback(sum);
-                    }
-                });
-            });
-            return Promise.all(wrappedPromises);
-        }
         const results = [];
         for (let i = 0; i < targetImages.length; i++) {
             const targetImage = targetImages[i];
@@ -165,23 +101,6 @@ export class OfflineCompiler {
     async _compileTrack(targetImages, progressCallback) {
         const percentPerImage = 100 / targetImages.length;
         let currentPercent = 0;
-        if (this.workerPool) {
-            const progressMap = new Float32Array(targetImages.length);
-            const wrappedPromises = targetImages.map((targetImage, index) => {
-                return this.workerPool.runTask({
-                    type: 'compile',
-                    targetImage,
-                    percentPerImage,
-                    basePercent: 0,
-                    onProgress: (p) => {
-                        progressMap[index] = p;
-                        const sum = progressMap.reduce((a, b) => a + b, 0);
-                        progressCallback(sum);
-                    }
-                });
-            });
-            return Promise.all(wrappedPromises);
-        }
         const results = [];
         for (let i = 0; i < targetImages.length; i++) {
             const targetImage = targetImages[i];
@@ -407,9 +326,7 @@ export class OfflineCompiler {
         };
     }
     async destroy() {
-        if (this.workerPool) {
-            await this.workerPool.destroy();
-        }
+        // No workers to destroy
     }
     _pack4Bit(data) {
         const length = data.length;

package/dist/react/TaptappAR.js

@@ -92,6 +92,9 @@ export const TaptappAR = ({ config, className = "", showScanningOverlay = true,
                     display: block;
                     width: 100%;
                     height: auto;
+                    opacity: 0;
+                    pointer-events: none;
+                    transition: opacity 0.3s ease;
                 }
             ` })] }));
 };

package/dist/react/use-ar.js

@@ -38,6 +38,7 @@ export const useAR = (config) => {
                     targetSrc: config.targetTaarSrc,
                     overlay: overlayRef.current,
                     scale: config.scale,
+                    debug: false,
                     onFound: async ({ targetIndex }) => {
                         console.log(`🎯 Target ${targetIndex} detected!`);
                         if (!isMounted)

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@srsergio/taptapp-ar",
-    "version": "1.0.77",
+    "version": "1.0.79",
     "description": "AR Compiler for Node.js and Browser",
     "repository": {
         "type": "git",

package/src/compiler/FEATURES.md

@@ -0,0 +1,40 @@
+# Taptapp AR Controller Features
+
+Este documento detalla las características modulares y mejoras de rendimiento implementadas en el controlador de Taptapp AR. Cada una de estas funcionalidades puede ser activada o desactivada rápidamente desde el código para pruebas de rendimiento o debugging.
+
+## 1. One Euro Filter (Smoothing)
+- **Trata de:** Un filtro adaptativo de primer orden para suavizar señales ruidosas.
+- **Qué aporta:** Reduce drásticamente el "jitter" (temblor) visual del objeto AR cuando el marcador está estático o se mueve lentamente. Proporciona una experiencia mucho más estable y premium.
+- **Requisito / Dependencia:** Ninguno. Es independiente.
+- **Archivo:** `features/one-euro-filter-feature.ts`
+
+## 2. Temporal Filter (Warmup & Miss Tolerance)
+- **Trata de:** Lógica de persistencia temporal que gestiona estados de "calentamiento" y "pérdida".
+- **Qué aporta:**
+    - **Warmup:** Evita falsos positivos al requerir que el marcador sea detectado consistentemente durante N cuadros antes de mostrarlo.
+    - **Miss Tolerance:** Mantiene el objeto visible durante breves oclusiones o fallos rápidos del tracker, evitando que el objeto parpadee o desaparezca instantáneamente.
+- **Requisito / Dependencia:** Ninguno.
+- **Archivo:** `features/temporal-filter-feature.ts`
+
+## 3. Crop Detection (Movement Optimization)
+- **Trata de:** Optimización que analiza solo regiones con movimiento en lugar de procesar toda la imagen.
+- **Qué aporta:** Mejora significativa en el rendimiento (FPS) y reduce el uso de CPU. Al detectar puntos de interés solo en áreas activas, se ignora el fondo estático.
+- **Requisito / Dependencia:** Depende de `CropDetector`.
+- **Archivo:** `features/crop-detection-feature.ts`
+
+## 4. Auto Rotation Matrix
+- **Trata de:** Ajuste automático de la matriz de transformación basada en la orientación del video de entrada.
+- **Qué aporta:** Permite que el AR funcione correctamente tanto en modo horizontal como vertical (Portrait) sin que el desarrollador tenga que rotar manualmente las coordenadas.
+- **Requisito / Dependencia:** Ninguno.
+- **Archivo:** `features/auto-rotation-feature.ts`
+
+---
+
+## Cómo desactivar una característica rápidamente
+
+En `packages/taptapp-ar/src/compiler/controller.ts`, puedes comentar la línea donde se añade la característica en el constructor o configurar el flag `enabled: false` en la instancia.
+
+```typescript
+// Ejemplo para desactivar suavizado
+this.featureManager.getFeature("one-euro-filter").enabled = false;
+```

package/src/compiler/controller.ts

@@ -2,7 +2,11 @@ import { Tracker } from "./tracker/tracker.js";
 import { CropDetector } from "./detector/crop-detector.js";
 import { OfflineCompiler as Compiler } from "./offline-compiler.js";
 import { InputLoader } from "./input-loader.js";
-import { OneEuroFilter } from "../libs/one-euro-filter.js";
+import { FeatureManager } from "./features/feature-manager.js";
+import { OneEuroFilterFeature } from "./features/one-euro-filter-feature.js";
+import { TemporalFilterFeature } from "./features/temporal-filter-feature.js";
+import { AutoRotationFeature } from "./features/auto-rotation-feature.js";
+import { CropDetectionFeature } from "./features/crop-detection-feature.js";
 
 let ControllerWorker: any;
 
@@ -41,11 +45,6 @@ class Controller {
     inputWidth: number;
     inputHeight: number;
     maxTrack: number;
-    filterMinCF: number;
-    filterBeta: number;
-    warmupTolerance: number;
-    missTolerance: number;
-    cropDetector: CropDetector;
     inputLoader: InputLoader;
     markerDimensions: any[] | null = null;
     onUpdate: ((data: any) => void) | null;
@@ -62,6 +61,7 @@ class Controller {
     workerTrackDone: ((data: any) => void) | null = null;
     mainThreadMatcher: any;
     mainThreadEstimator: any;
+    featureManager: FeatureManager;
 
     constructor({
         inputWidth,
@@ -78,17 +78,32 @@ class Controller {
         this.inputWidth = inputWidth;
         this.inputHeight = inputHeight;
         this.maxTrack = maxTrack;
-        this.filterMinCF = filterMinCF === null ? DEFAULT_FILTER_CUTOFF : filterMinCF;
-        this.filterBeta = filterBeta === null ? DEFAULT_FILTER_BETA : filterBeta;
-        this.warmupTolerance = warmupTolerance === null ? DEFAULT_WARMUP_TOLERANCE : warmupTolerance;
-        this.missTolerance = missTolerance === null ? DEFAULT_MISS_TOLERANCE : missTolerance;
-        this.cropDetector = new CropDetector(this.inputWidth, this.inputHeight, debugMode);
+
+        this.featureManager = new FeatureManager();
+        this.featureManager.addFeature(new OneEuroFilterFeature(
+            filterMinCF === null ? DEFAULT_FILTER_CUTOFF : filterMinCF,
+            filterBeta === null ? DEFAULT_FILTER_BETA : filterBeta
+        ));
+        this.featureManager.addFeature(new TemporalFilterFeature(
+            warmupTolerance === null ? DEFAULT_WARMUP_TOLERANCE : warmupTolerance,
+            missTolerance === null ? DEFAULT_MISS_TOLERANCE : missTolerance
+        ));
+        this.featureManager.addFeature(new AutoRotationFeature());
+        this.featureManager.addFeature(new CropDetectionFeature());
+
         this.inputLoader = new InputLoader(this.inputWidth, this.inputHeight);
         this.onUpdate = onUpdate;
         this.debugMode = debugMode;
         this.worker = worker;
         if (this.worker) this._setupWorkerListener();
 
+        this.featureManager.init({
+            inputWidth: this.inputWidth,
+            inputHeight: this.inputHeight,
+            projectionTransform: [], // Will be set below
+            debugMode: this.debugMode
+        });
+
         const near = 10;
         const far = 100000;
         const fovy = (45.0 * Math.PI) / 180;
@@ -100,6 +115,13 @@ class Controller {
             [0, 0, 1],
         ];
 
+        this.featureManager.init({
+            inputWidth: this.inputWidth,
+            inputHeight: this.inputHeight,
+            projectionTransform: this.projectionTransform,
+            debugMode: this.debugMode
+        });
+
         this.projectionMatrix = this._glProjectionMatrix({
             projectionTransform: this.projectionTransform,
             width: this.inputWidth,
@@ -197,7 +219,8 @@ class Controller {
 
     dummyRun(input: any) {
         const inputData = this.inputLoader.loadInput(input);
-        this.cropDetector.detect(inputData);
+        const cropFeature = this.featureManager.getFeature<CropDetectionFeature>("crop-detection");
+        cropFeature?.detect(inputData, false);
         this.tracker!.dummyRun(inputData);
     }
 
@@ -219,7 +242,8 @@ class Controller {
     }
 
     async _detectAndMatch(inputData: any, targetIndexes: number[]) {
-        const { featurePoints } = this.cropDetector.detectMoving(inputData);
+        const cropFeature = this.featureManager.getFeature<CropDetectionFeature>("crop-detection");
+        const { featurePoints } = cropFeature!.detect(inputData, true);
         const { targetIndex: matchedTargetIndex, modelViewTransform } = await this._workerMatch(
             featurePoints,
             targetIndexes,
@@ -253,7 +277,6 @@ class Controller {
                 currentModelViewTransform: null,
                 trackCount: 0,
                 trackMiss: 0,
-                filter: new OneEuroFilter({ minCutOff: this.filterMinCF, beta: this.filterBeta }),
             });
         }
 
@@ -298,46 +321,34 @@ class Controller {
                         }
                     }
 
-                    if (!trackingState.showing) {
-                        if (trackingState.isTracking) {
-                            trackingState.trackMiss = 0;
-                            trackingState.trackCount += 1;
-                            if (trackingState.trackCount > this.warmupTolerance) {
-                                trackingState.showing = true;
-                                trackingState.trackingMatrix = null;
-                                trackingState.filter.reset();
-                            }
-                        }
-                    }
+                    const wasShowing = trackingState.showing;
+                    trackingState.showing = this.featureManager.shouldShow(i, trackingState.isTracking);
 
-                    if (trackingState.showing) {
-                        if (!trackingState.isTracking) {
-                            trackingState.trackCount = 0;
-                            trackingState.trackMiss += 1;
-                            if (trackingState.trackMiss > this.missTolerance) {
-                                trackingState.showing = false;
-                                trackingState.trackingMatrix = null;
-                                this.onUpdate && this.onUpdate({ type: "updateMatrix", targetIndex: i, worldMatrix: null });
-                            }
-                        } else {
-                            trackingState.trackMiss = 0;
-                        }
+                    if (wasShowing && !trackingState.showing) {
+                        trackingState.trackingMatrix = null;
+                        this.onUpdate && this.onUpdate({ type: "updateMatrix", targetIndex: i, worldMatrix: null });
+                        this.featureManager.notifyUpdate({ type: "reset", targetIndex: i });
                     }
 
                     if (trackingState.showing) {
                         const worldMatrix = this._glModelViewMatrix(trackingState.currentModelViewTransform, i);
-                        trackingState.trackingMatrix = trackingState.filter.filter(Date.now(), worldMatrix);
-                        let clone = [...trackingState.trackingMatrix];
+                        const filteredMatrix = this.featureManager.applyWorldMatrixFilters(i, worldMatrix);
+                        trackingState.trackingMatrix = filteredMatrix;
+
+                        let finalMatrix = [...filteredMatrix];
 
                         const isInputRotated = input.width === this.inputHeight && input.height === this.inputWidth;
                         if (isInputRotated) {
-                            clone = this.getRotatedZ90Matrix(clone);
+                            const rotationFeature = this.featureManager.getFeature<AutoRotationFeature>("auto-rotation");
+                            if (rotationFeature) {
+                                finalMatrix = rotationFeature.rotate(finalMatrix);
+                            }
                         }
 
                         this.onUpdate && this.onUpdate({
                             type: "updateMatrix",
                             targetIndex: i,
-                            worldMatrix: clone,
+                            worldMatrix: finalMatrix,
                             modelViewTransform: trackingState.currentModelViewTransform
                         });
                     }
@@ -361,7 +372,8 @@ class Controller {
 
     async detect(input: any) {
         const inputData = this.inputLoader.loadInput(input);
-        const { featurePoints, debugExtra } = this.cropDetector.detect(inputData);
+        const cropFeature = this.featureManager.getFeature<CropDetectionFeature>("crop-detection");
+        const { featurePoints, debugExtra } = cropFeature!.detect(inputData, false);
         return { featurePoints, debugExtra };
     }
 

package/src/compiler/features/auto-rotation-feature.ts

@@ -0,0 +1,36 @@
+import { ControllerFeature } from "./feature-base.js";
+
+export class AutoRotationFeature implements ControllerFeature {
+    id = "auto-rotation";
+    name = "Auto Rotation Matrix";
+    description = "Automatically adjusts the world matrix if the input video is rotated (e.g. portrait mode).";
+    enabled = true;
+
+    private inputWidth: number = 0;
+    private inputHeight: number = 0;
+
+    init(context: { inputWidth: number; inputHeight: number }) {
+        this.inputWidth = context.inputWidth;
+        this.inputHeight = context.inputHeight;
+    }
+
+    filterWorldMatrix(targetIndex: number, worldMatrix: number[]): number[] {
+        if (!this.enabled) return worldMatrix;
+
+        // Check if input is rotated (this logic might need the actual current input dimensions)
+        // For now, we'll assume the controller passes the 'isRotated' info or we detect it
+        // But since this is a matrix post-process, we can just apply it if needed.
+        return worldMatrix;
+    }
+
+    // We might need a way to pass the 'currentInput' to the feature.
+    // Actually, the controller can just call this if it detects rotation.
+    rotate(m: number[]): number[] {
+        return [
+            -m[1], m[0], m[2], m[3],
+            -m[5], m[4], m[6], m[7],
+            -m[9], m[8], m[10], m[11],
+            -m[13], m[12], m[14], m[15],
+        ];
+    }
+}

package/src/compiler/features/crop-detection-feature.ts

@@ -0,0 +1,31 @@
+import { ControllerFeature, FeatureContext } from "./feature-base.js";
+import { CropDetector } from "../detector/crop-detector.js";
+
+export class CropDetectionFeature implements ControllerFeature {
+    id = "crop-detection";
+    name = "Crop Detection";
+    description = "Optimizes detection by focusing on areas with motion, reducing CPU usage.";
+    enabled = true;
+
+    private cropDetector: CropDetector | null = null;
+    private debugMode: boolean = false;
+
+    init(context: FeatureContext) {
+        this.debugMode = context.debugMode;
+        this.cropDetector = new CropDetector(context.inputWidth, context.inputHeight, this.debugMode);
+    }
+
+    detect(inputData: any, isMoving: boolean = true) {
+        if (!this.enabled || !this.cropDetector) {
+            // Fallback to full detection if disabled? 
+            // Actually CropDetector.detect is just full detection.
+            // We'll expose the methods here.
+        }
+
+        if (isMoving && this.enabled) {
+            return this.cropDetector!.detectMoving(inputData);
+        } else {
+            return this.cropDetector!.detect(inputData);
+        }
+    }
+}

package/src/compiler/features/feature-base.ts

@@ -0,0 +1,48 @@
+export interface FeatureContext {
+    inputWidth: number;
+    inputHeight: number;
+    projectionTransform: number[][];
+    debugMode: boolean;
+}
+
+export interface Feature {
+    id: string;
+    name: string;
+    description: string;
+    enabled: boolean;
+
+    // Lifecycle hooks
+    init?(context: FeatureContext): void;
+    onUpdate?(data: any): void;
+    dispose?(): void;
+}
+
+/**
+ * Controller feature interface for processing hooks
+ */
+export interface ControllerFeature extends Feature {
+    /**
+     * Called before processing a frame
+     */
+    beforeProcess?(inputData: any): void;
+
+    /**
+     * Called after detection/matching
+     */
+    afterMatch?(result: { targetIndex: number, modelViewTransform: number[][] | null }): void;
+
+    /**
+     * Called after tracking update
+     */
+    afterTrack?(result: { targetIndex: number, modelViewTransform: number[][] | null }): void;
+
+    /**
+     * Hook to filter or modify the final world matrix
+     */
+    filterWorldMatrix?(targetIndex: number, worldMatrix: number[]): number[];
+
+    /**
+     * Hook to decide if a target should be shown
+     */
+    shouldShow?(targetIndex: number, isTracking: boolean): boolean;
+}

package/src/compiler/features/feature-manager.ts

@@ -0,0 +1,65 @@
+import { ControllerFeature, FeatureContext } from "./feature-base.js";
+
+export class FeatureManager {
+    private features: ControllerFeature[] = [];
+
+    addFeature(feature: ControllerFeature) {
+        this.features.push(feature);
+    }
+
+    getFeature<T extends ControllerFeature>(id: string): T | undefined {
+        return this.features.find(f => f.id === id) as T;
+    }
+
+    init(context: FeatureContext) {
+        for (const feature of this.features) {
+            if (feature.enabled && feature.init) {
+                feature.init(context);
+            }
+        }
+    }
+
+    beforeProcess(inputData: any) {
+        for (const feature of this.features) {
+            if (feature.enabled && feature.beforeProcess) {
+                feature.beforeProcess(inputData);
+            }
+        }
+    }
+
+    applyWorldMatrixFilters(targetIndex: number, worldMatrix: number[]): number[] {
+        let result = worldMatrix;
+        for (const feature of this.features) {
+            if (feature.enabled && feature.filterWorldMatrix) {
+                result = feature.filterWorldMatrix(targetIndex, result);
+            }
+        }
+        return result;
+    }
+
+    shouldShow(targetIndex: number, isTracking: boolean): boolean {
+        let show = isTracking;
+        for (const feature of this.features) {
+            if (feature.enabled && feature.shouldShow) {
+                show = feature.shouldShow(targetIndex, isTracking);
+            }
+        }
+        return show;
+    }
+
+    notifyUpdate(data: any) {
+        for (const feature of this.features) {
+            if (feature.enabled && feature.onUpdate) {
+                feature.onUpdate(data);
+            }
+        }
+    }
+
+    dispose() {
+        for (const feature of this.features) {
+            if (feature.dispose) {
+                feature.dispose();
+            }
+        }
+    }
+}

package/src/compiler/features/one-euro-filter-feature.ts

@@ -0,0 +1,44 @@
+import { ControllerFeature, FeatureContext } from "./feature-base.js";
+import { OneEuroFilter } from "../../libs/one-euro-filter.js";
+
+export class OneEuroFilterFeature implements ControllerFeature {
+    id = "one-euro-filter";
+    name = "One Euro Filter";
+    description = "Smooths the tracking matrix to reduce jitter using a One Euro Filter.";
+    enabled = true;
+
+    private filters: OneEuroFilter[] = [];
+    private minCutOff: number;
+    private beta: number;
+
+    constructor(minCutOff: number = 0.5, beta: number = 0.1) {
+        this.minCutOff = minCutOff;
+        this.beta = beta;
+    }
+
+    init(context: FeatureContext) {
+        // We'll initialize filters lazily or based on target count if known
+    }
+
+    private getFilter(targetIndex: number): OneEuroFilter {
+        if (!this.filters[targetIndex]) {
+            this.filters[targetIndex] = new OneEuroFilter({
+                minCutOff: this.minCutOff,
+                beta: this.beta
+            });
+        }
+        return this.filters[targetIndex];
+    }
+
+    filterWorldMatrix(targetIndex: number, worldMatrix: number[]): number[] {
+        if (!this.enabled) return worldMatrix;
+        const filter = this.getFilter(targetIndex);
+        return filter.filter(Date.now(), worldMatrix);
+    }
+
+    onUpdate(data: any) {
+        if (data.type === "reset" && data.targetIndex !== undefined) {
+            this.filters[data.targetIndex]?.reset();
+        }
+    }
+}