@srsergio/taptapp-ar 1.0.76 → 1.0.78

package/dist/compiler/controller.d.ts

@@ -1,6 +1,6 @@
 import { Tracker } from "./tracker/tracker.js";
-import { CropDetector } from "./detector/crop-detector.js";
 import { InputLoader } from "./input-loader.js";
+import { FeatureManager } from "./features/feature-manager.js";
 export interface ControllerOptions {
     inputWidth: number;
     inputHeight: number;
@@ -17,11 +17,6 @@ declare class Controller {
     inputWidth: number;
     inputHeight: number;
     maxTrack: number;
-    filterMinCF: number;
-    filterBeta: number;
-    warmupTolerance: number;
-    missTolerance: number;
-    cropDetector: CropDetector;
     inputLoader: InputLoader;
     markerDimensions: any[] | null;
     onUpdate: ((data: any) => void) | null;
@@ -38,6 +33,7 @@ declare class Controller {
     workerTrackDone: ((data: any) => void) | null;
     mainThreadMatcher: any;
     mainThreadEstimator: any;
+    featureManager: FeatureManager;
     constructor({ inputWidth, inputHeight, onUpdate, debugMode, maxTrack, warmupTolerance, missTolerance, filterMinCF, filterBeta, worker, }: ControllerOptions);
     _setupWorkerListener(): void;
     _ensureWorker(): void;

package/dist/compiler/controller.js

@@ -1,8 +1,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;
 // Conditional import for worker to avoid crash in non-vite environments
 const getControllerWorker = async () => {
@@ -26,11 +29,6 @@ class Controller {
     inputWidth;
     inputHeight;
     maxTrack;
-    filterMinCF;
-    filterBeta;
-    warmupTolerance;
-    missTolerance;
-    cropDetector;
     inputLoader;
     markerDimensions = null;
     onUpdate;
@@ -47,21 +45,28 @@ class Controller {
     workerTrackDone = null;
     mainThreadMatcher;
     mainThreadEstimator;
+    featureManager;
     constructor({ inputWidth, inputHeight, onUpdate = null, debugMode = false, maxTrack = 1, warmupTolerance = null, missTolerance = null, filterMinCF = null, filterBeta = null, worker = null, }) {
         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;
@@ -71,6 +76,12 @@ class Controller {
             [0, f, this.inputHeight / 2],
             [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,
@@ -149,7 +160,8 @@ class Controller {
     }
     dummyRun(input) {
         const inputData = this.inputLoader.loadInput(input);
-        this.cropDetector.detect(inputData);
+        const cropFeature = this.featureManager.getFeature("crop-detection");
+        cropFeature?.detect(inputData, false);
         this.tracker.dummyRun(inputData);
     }
     getProjectionMatrix() {
@@ -167,14 +179,15 @@ class Controller {
         return this._glModelViewMatrix(modelViewTransform, targetIndex);
     }
     async _detectAndMatch(inputData, targetIndexes) {
-        const { featurePoints } = this.cropDetector.detectMoving(inputData);
+        const cropFeature = this.featureManager.getFeature("crop-detection");
+        const { featurePoints } = cropFeature.detect(inputData, true);
         const { targetIndex: matchedTargetIndex, modelViewTransform } = await this._workerMatch(featurePoints, targetIndexes);
         return { targetIndex: matchedTargetIndex, modelViewTransform };
     }
     async _trackAndUpdate(inputData, lastModelViewTransform, targetIndex) {
         const { worldCoords, screenCoords } = this.tracker.track(inputData, lastModelViewTransform, targetIndex);
-        if (worldCoords.length < 10)
-            return null; // Increased from 6 to 10 for better noise rejection
+        if (worldCoords.length < 8)
+            return null; // Resynced with Matcher (8 points) to allow initial detection
         const modelViewTransform = await this._workerTrackUpdate(lastModelViewTransform, {
             worldCoords,
             screenCoords,
@@ -193,7 +206,6 @@ class Controller {
                 currentModelViewTransform: null,
                 trackCount: 0,
                 trackMiss: 0,
-                filter: new OneEuroFilter({ minCutOff: this.filterMinCF, beta: this.filterBeta }),
             });
         }
         const startProcessing = async () => {
@@ -229,43 +241,29 @@ class Controller {
                             trackingState.currentModelViewTransform = modelViewTransform;
                         }
                     }
-                    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();
-                            }
-                        }
-                    }
-                    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;
-                        }
+                    const wasShowing = trackingState.showing;
+                    trackingState.showing = this.featureManager.shouldShow(i, trackingState.isTracking);
+                    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("auto-rotation");
+                            if (rotationFeature) {
+                                finalMatrix = rotationFeature.rotate(finalMatrix);
+                            }
                         }
                         this.onUpdate && this.onUpdate({
                             type: "updateMatrix",
                             targetIndex: i,
-                            worldMatrix: clone,
+                            worldMatrix: finalMatrix,
                             modelViewTransform: trackingState.currentModelViewTransform
                         });
                     }
@@ -286,7 +284,8 @@ class Controller {
     }
     async detect(input) {
         const inputData = this.inputLoader.loadInput(input);
-        const { featurePoints, debugExtra } = this.cropDetector.detect(inputData);
+        const cropFeature = this.featureManager.getFeature("crop-detection");
+        const { featurePoints, debugExtra } = cropFeature.detect(inputData, false);
         return { featurePoints, debugExtra };
     }
     async match(featurePoints, targetIndex) {

package/dist/compiler/detector/crop-detector.d.ts

@@ -22,6 +22,7 @@ export class CropDetector {
             projectedImage?: undefined;
         };
     };
+    frameCounter: number | undefined;
     _detectGlobal(imageData: any): {
         featurePoints: any[];
         debugExtra: {

package/dist/compiler/detector/crop-detector.js

@@ -24,39 +24,36 @@ class CropDetector {
     }
     detectMoving(input) {
         const imageData = input;
-        // 🚀 MOONSHOT: High Frequency Global Scan
-        // Scan full screen every 2 frames when searching to guarantee instant recovery
-        if (this.lastRandomIndex % 2 === 0) {
-            this.lastRandomIndex = (this.lastRandomIndex + 1) % 25;
+        if (!this.frameCounter)
+            this.frameCounter = 0;
+        this.frameCounter++;
+        // Scan full screen every 2 frames
+        if (this.frameCounter % 2 === 0) {
             return this._detectGlobal(imageData);
         }
-        // Local crops (25 grid)
+        // Local crops: ensure we visit every single cell
         const gridSize = 5;
-        const idx = (this.lastRandomIndex - 1) % (gridSize * gridSize);
-        // ... rest of logic remains but we hit it less often because global scan is more successful
-        const dx = idx % gridSize;
-        const dy = Math.floor(idx / gridSize);
+        const dx = this.lastRandomIndex % gridSize;
+        const dy = Math.floor(this.lastRandomIndex / gridSize);
         const stepX = this.cropSize / 3;
         const stepY = this.cropSize / 3;
         let startY = Math.floor(this.height / 2 - this.cropSize / 2 + (dy - 2) * stepY);
         let startX = Math.floor(this.width / 2 - this.cropSize / 2 + (dx - 2) * stepX);
         startX = Math.max(0, Math.min(this.width - this.cropSize - 1, startX));
         startY = Math.max(0, Math.min(this.height - this.cropSize - 1, startY));
-        this.lastRandomIndex = (this.lastRandomIndex + 1) % 25;
+        this.lastRandomIndex = (this.lastRandomIndex + 1) % (gridSize * gridSize);
         return this._detect(imageData, startX, startY);
     }
     _detectGlobal(imageData) {
         const croppedData = new Float32Array(this.cropSize * this.cropSize);
         const scaleX = this.width / this.cropSize;
         const scaleY = this.height / this.cropSize;
-        // Better sampling: avoid missing edges by jumping too much
+        // Use sharp sampling for better descriptors
         for (let y = 0; y < this.cropSize; y++) {
             const srcY = Math.floor(y * scaleY) * this.width;
             const dstY = y * this.cropSize;
             for (let x = 0; x < this.cropSize; x++) {
-                // Average slightly to preserve gradients
-                const sx = Math.floor(x * scaleX);
-                croppedData[dstY + x] = (imageData[srcY + sx] + imageData[srcY + sx + 1]) * 0.5;
+                croppedData[dstY + x] = imageData[srcY + Math.floor(x * scaleX)];
             }
         }
         const { featurePoints } = this.detector.detect(croppedData);

package/dist/compiler/features/auto-rotation-feature.d.ts

@@ -0,0 +1,15 @@
+import { ControllerFeature } from "./feature-base.js";
+export declare class AutoRotationFeature implements ControllerFeature {
+    id: string;
+    name: string;
+    description: string;
+    enabled: boolean;
+    private inputWidth;
+    private inputHeight;
+    init(context: {
+        inputWidth: number;
+        inputHeight: number;
+    }): void;
+    filterWorldMatrix(targetIndex: number, worldMatrix: number[]): number[];
+    rotate(m: number[]): number[];
+}

package/dist/compiler/features/auto-rotation-feature.js

@@ -0,0 +1,30 @@
+export class AutoRotationFeature {
+    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;
+    inputWidth = 0;
+    inputHeight = 0;
+    init(context) {
+        this.inputWidth = context.inputWidth;
+        this.inputHeight = context.inputHeight;
+    }
+    filterWorldMatrix(targetIndex, worldMatrix) {
+        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) {
+        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/dist/compiler/features/crop-detection-feature.d.ts

@@ -0,0 +1,18 @@
+import { ControllerFeature, FeatureContext } from "./feature-base.js";
+export declare class CropDetectionFeature implements ControllerFeature {
+    id: string;
+    name: string;
+    description: string;
+    enabled: boolean;
+    private cropDetector;
+    private debugMode;
+    init(context: FeatureContext): void;
+    detect(inputData: any, isMoving?: boolean): {
+        featurePoints: any[];
+        debugExtra: {
+            projectedImage: number[];
+        } | {
+            projectedImage?: undefined;
+        };
+    };
+}

package/dist/compiler/features/crop-detection-feature.js

@@ -0,0 +1,26 @@
+import { CropDetector } from "../detector/crop-detector.js";
+export class CropDetectionFeature {
+    id = "crop-detection";
+    name = "Crop Detection";
+    description = "Optimizes detection by focusing on areas with motion, reducing CPU usage.";
+    enabled = true;
+    cropDetector = null;
+    debugMode = false;
+    init(context) {
+        this.debugMode = context.debugMode;
+        this.cropDetector = new CropDetector(context.inputWidth, context.inputHeight, this.debugMode);
+    }
+    detect(inputData, isMoving = 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/dist/compiler/features/feature-base.d.ts

@@ -0,0 +1,46 @@
+export interface FeatureContext {
+    inputWidth: number;
+    inputHeight: number;
+    projectionTransform: number[][];
+    debugMode: boolean;
+}
+export interface Feature {
+    id: string;
+    name: string;
+    description: string;
+    enabled: boolean;
+    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/dist/compiler/features/feature-base.js

@@ -0,0 +1 @@
+export {};

package/dist/compiler/features/feature-manager.d.ts

@@ -0,0 +1,12 @@
+import { ControllerFeature, FeatureContext } from "./feature-base.js";
+export declare class FeatureManager {
+    private features;
+    addFeature(feature: ControllerFeature): void;
+    getFeature<T extends ControllerFeature>(id: string): T | undefined;
+    init(context: FeatureContext): void;
+    beforeProcess(inputData: any): void;
+    applyWorldMatrixFilters(targetIndex: number, worldMatrix: number[]): number[];
+    shouldShow(targetIndex: number, isTracking: boolean): boolean;
+    notifyUpdate(data: any): void;
+    dispose(): void;
+}

package/dist/compiler/features/feature-manager.js

@@ -0,0 +1,55 @@
+export class FeatureManager {
+    features = [];
+    addFeature(feature) {
+        this.features.push(feature);
+    }
+    getFeature(id) {
+        return this.features.find(f => f.id === id);
+    }
+    init(context) {
+        for (const feature of this.features) {
+            if (feature.enabled && feature.init) {
+                feature.init(context);
+            }
+        }
+    }
+    beforeProcess(inputData) {
+        for (const feature of this.features) {
+            if (feature.enabled && feature.beforeProcess) {
+                feature.beforeProcess(inputData);
+            }
+        }
+    }
+    applyWorldMatrixFilters(targetIndex, worldMatrix) {
+        let result = worldMatrix;
+        for (const feature of this.features) {
+            if (feature.enabled && feature.filterWorldMatrix) {
+                result = feature.filterWorldMatrix(targetIndex, result);
+            }
+        }
+        return result;
+    }
+    shouldShow(targetIndex, isTracking) {
+        let show = isTracking;
+        for (const feature of this.features) {
+            if (feature.enabled && feature.shouldShow) {
+                show = feature.shouldShow(targetIndex, isTracking);
+            }
+        }
+        return show;
+    }
+    notifyUpdate(data) {
+        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/dist/compiler/features/one-euro-filter-feature.d.ts

@@ -0,0 +1,15 @@
+import { ControllerFeature, FeatureContext } from "./feature-base.js";
+export declare class OneEuroFilterFeature implements ControllerFeature {
+    id: string;
+    name: string;
+    description: string;
+    enabled: boolean;
+    private filters;
+    private minCutOff;
+    private beta;
+    constructor(minCutOff?: number, beta?: number);
+    init(context: FeatureContext): void;
+    private getFilter;
+    filterWorldMatrix(targetIndex: number, worldMatrix: number[]): number[];
+    onUpdate(data: any): void;
+}

package/dist/compiler/features/one-euro-filter-feature.js

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

package/dist/compiler/features/temporal-filter-feature.d.ts

@@ -0,0 +1,19 @@
+import { ControllerFeature } from "./feature-base.js";
+export interface TemporalState {
+    showing: boolean;
+    trackCount: number;
+    trackMiss: number;
+}
+export declare class TemporalFilterFeature implements ControllerFeature {
+    id: string;
+    name: string;
+    description: string;
+    enabled: boolean;
+    private states;
+    private warmupTolerance;
+    private missTolerance;
+    private onToggleShowing?;
+    constructor(warmup?: number, miss?: number, onToggleShowing?: (targetIndex: number, showing: boolean) => void);
+    private getState;
+    shouldShow(targetIndex: number, isTracking: boolean): boolean;
+}

package/dist/compiler/features/temporal-filter-feature.js

@@ -0,0 +1,57 @@
+export class TemporalFilterFeature {
+    id = "temporal-filter";
+    name = "Temporal Filter";
+    description = "Provides warmup tolerance (to avoid false positives) and miss tolerance (to maintain tracking during brief occlusions).";
+    enabled = true;
+    states = [];
+    warmupTolerance;
+    missTolerance;
+    onToggleShowing;
+    constructor(warmup = 2, miss = 5, onToggleShowing) {
+        this.warmupTolerance = warmup;
+        this.missTolerance = miss;
+        this.onToggleShowing = onToggleShowing;
+    }
+    getState(targetIndex) {
+        if (!this.states[targetIndex]) {
+            this.states[targetIndex] = {
+                showing: false,
+                trackCount: 0,
+                trackMiss: 0,
+            };
+        }
+        return this.states[targetIndex];
+    }
+    shouldShow(targetIndex, isTracking) {
+        if (!this.enabled)
+            return isTracking;
+        const state = this.getState(targetIndex);
+        if (!state.showing) {
+            if (isTracking) {
+                state.trackMiss = 0;
+                state.trackCount += 1;
+                if (state.trackCount > this.warmupTolerance) {
+                    state.showing = true;
+                    this.onToggleShowing?.(targetIndex, true);
+                }
+            }
+            else {
+                state.trackCount = 0;
+            }
+        }
+        else {
+            if (!isTracking) {
+                state.trackCount = 0;
+                state.trackMiss += 1;
+                if (state.trackMiss > this.missTolerance) {
+                    state.showing = false;
+                    this.onToggleShowing?.(targetIndex, false);
+                }
+            }
+            else {
+                state.trackMiss = 0;
+            }
+        }
+        return state.showing;
+    }
+}

package/dist/compiler/tracker/tracker.js

@@ -95,7 +95,7 @@ class Tracker {
             }
         }
         // 2.1 Spatial distribution check: Avoid getting stuck in corners/noise
-        if (screenCoords.length >= 10) {
+        if (screenCoords.length >= 8) {
             let minX = Infinity, minY = Infinity, maxX = -Infinity, maxY = -Infinity;
             for (const p of screenCoords) {
                 if (p.x < minX)

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@srsergio/taptapp-ar",
-    "version": "1.0.76",
+    "version": "1.0.78",
     "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,
@@ -233,7 +257,7 @@ class Controller {
             lastModelViewTransform,
             targetIndex,
         );
-        if (worldCoords.length < 10) return null; // Increased from 6 to 10 for better noise rejection
+        if (worldCoords.length < 8) return null; // Resynced with Matcher (8 points) to allow initial detection
         const modelViewTransform = await this._workerTrackUpdate(lastModelViewTransform, {
             worldCoords,
             screenCoords,
@@ -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/detector/crop-detector.js

@@ -32,20 +32,19 @@ class CropDetector {
 
   detectMoving(input) {
     const imageData = input;
+    if (!this.frameCounter) this.frameCounter = 0;
+    this.frameCounter++;
 
-    // 🚀 MOONSHOT: High Frequency Global Scan
-    // Scan full screen every 2 frames when searching to guarantee instant recovery
-    if (this.lastRandomIndex % 2 === 0) {
-      this.lastRandomIndex = (this.lastRandomIndex + 1) % 25;
+    // Scan full screen every 2 frames
+    if (this.frameCounter % 2 === 0) {
       return this._detectGlobal(imageData);
     }
 
-    // Local crops (25 grid)
+    // Local crops: ensure we visit every single cell
     const gridSize = 5;
-    const idx = (this.lastRandomIndex - 1) % (gridSize * gridSize);
-    // ... rest of logic remains but we hit it less often because global scan is more successful
-    const dx = idx % gridSize;
-    const dy = Math.floor(idx / gridSize);
+    const dx = this.lastRandomIndex % gridSize;
+    const dy = Math.floor(this.lastRandomIndex / gridSize);
+
     const stepX = this.cropSize / 3;
     const stepY = this.cropSize / 3;
 
@@ -55,7 +54,7 @@ class CropDetector {
     startX = Math.max(0, Math.min(this.width - this.cropSize - 1, startX));
     startY = Math.max(0, Math.min(this.height - this.cropSize - 1, startY));
 
-    this.lastRandomIndex = (this.lastRandomIndex + 1) % 25;
+    this.lastRandomIndex = (this.lastRandomIndex + 1) % (gridSize * gridSize);
     return this._detect(imageData, startX, startY);
   }
 
@@ -64,14 +63,12 @@ class CropDetector {
     const scaleX = this.width / this.cropSize;
     const scaleY = this.height / this.cropSize;
 
-    // Better sampling: avoid missing edges by jumping too much
+    // Use sharp sampling for better descriptors
     for (let y = 0; y < this.cropSize; y++) {
       const srcY = Math.floor(y * scaleY) * this.width;
       const dstY = y * this.cropSize;
       for (let x = 0; x < this.cropSize; x++) {
-        // Average slightly to preserve gradients
-        const sx = Math.floor(x * scaleX);
-        croppedData[dstY + x] = (imageData[srcY + sx] + imageData[srcY + sx + 1]) * 0.5;
+        croppedData[dstY + x] = imageData[srcY + Math.floor(x * scaleX)];
       }
     }
 

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();
+        }
+    }
+}

package/src/compiler/features/temporal-filter-feature.ts

@@ -0,0 +1,68 @@
+import { ControllerFeature } from "./feature-base.js";
+
+export interface TemporalState {
+    showing: boolean;
+    trackCount: number;
+    trackMiss: number;
+}
+
+export class TemporalFilterFeature implements ControllerFeature {
+    id = "temporal-filter";
+    name = "Temporal Filter";
+    description = "Provides warmup tolerance (to avoid false positives) and miss tolerance (to maintain tracking during brief occlusions).";
+    enabled = true;
+
+    private states: TemporalState[] = [];
+    private warmupTolerance: number;
+    private missTolerance: number;
+    private onToggleShowing?: (targetIndex: number, showing: boolean) => void;
+
+    constructor(warmup: number = 2, miss: number = 5, onToggleShowing?: (targetIndex: number, showing: boolean) => void) {
+        this.warmupTolerance = warmup;
+        this.missTolerance = miss;
+        this.onToggleShowing = onToggleShowing;
+    }
+
+    private getState(targetIndex: number): TemporalState {
+        if (!this.states[targetIndex]) {
+            this.states[targetIndex] = {
+                showing: false,
+                trackCount: 0,
+                trackMiss: 0,
+            };
+        }
+        return this.states[targetIndex];
+    }
+
+    shouldShow(targetIndex: number, isTracking: boolean): boolean {
+        if (!this.enabled) return isTracking;
+
+        const state = this.getState(targetIndex);
+
+        if (!state.showing) {
+            if (isTracking) {
+                state.trackMiss = 0;
+                state.trackCount += 1;
+                if (state.trackCount > this.warmupTolerance) {
+                    state.showing = true;
+                    this.onToggleShowing?.(targetIndex, true);
+                }
+            } else {
+                state.trackCount = 0;
+            }
+        } else {
+            if (!isTracking) {
+                state.trackCount = 0;
+                state.trackMiss += 1;
+                if (state.trackMiss > this.missTolerance) {
+                    state.showing = false;
+                    this.onToggleShowing?.(targetIndex, false);
+                }
+            } else {
+                state.trackMiss = 0;
+            }
+        }
+
+        return state.showing;
+    }
+}

package/src/compiler/tracker/tracker.js

@@ -137,7 +137,7 @@ class Tracker {
     }
 
     // 2.1 Spatial distribution check: Avoid getting stuck in corners/noise
-    if (screenCoords.length >= 10) {
+    if (screenCoords.length >= 8) {
       let minX = Infinity, minY = Infinity, maxX = -Infinity, maxY = -Infinity;
       for (const p of screenCoords) {
         if (p.x < minX) minX = p.x; if (p.y < minY) minY = p.y;