@srsergio/taptapp-ar 1.0.34 → 1.0.36

package/dist/compiler/controller.js

@@ -16,7 +16,7 @@ catch (e) {
 const DEFAULT_FILTER_CUTOFF = 0.1; // Menor cutoff para filtrar más ruidos cuando está quieto
 const DEFAULT_FILTER_BETA = 0.01; // Beta bajo para suavizar movimientos rápidos
 const DEFAULT_WARMUP_TOLERANCE = 8; // Más frames de calentamiento para asegurar estabilidad inicial
-const DEFAULT_MISS_TOLERANCE = 5;
+const DEFAULT_MISS_TOLERANCE = 2; // Reducido para que el objeto desaparezca más rápido tras pérdida
 class Controller {
     constructor({ inputWidth, inputHeight, onUpdate = null, debugMode = false, maxTrack = 1, warmupTolerance = null, missTolerance = null, filterMinCF = null, filterBeta = null, worker = null, // Allow custom worker injection
      }) {
@@ -182,8 +182,8 @@ class Controller {
     }
     async _trackAndUpdate(inputData, lastModelViewTransform, targetIndex) {
         const { worldCoords, screenCoords } = this.tracker.track(inputData, lastModelViewTransform, targetIndex);
-        if (worldCoords.length < 4)
-            return null;
+        if (worldCoords.length < 6)
+            return null; // Umbral de puntos mínimos para mantener el seguimiento
         const modelViewTransform = await this._workerTrackUpdate(lastModelViewTransform, {
             worldCoords,
             screenCoords,

package/dist/compiler/offline-compiler.js

@@ -217,9 +217,9 @@ export class OfflineCompiler {
         }
         const dataList = this.data.map((item) => {
             const matchingData = item.matchingData.map((kf) => this._packKeyframe(kf));
-            const trackingData = [item.trackingData[0]].map((td) => {
+            const trackingData = item.trackingData.map((td) => {
                 const count = td.points.length;
-                // Step 1: Packed Coords - Normalize width/height to 16-bit
+                // Packed Coords - Float32 for now as in current import logic
                 const px = new Float32Array(count);
                 const py = new Float32Array(count);
                 for (let i = 0; i < count; i++) {

package/dist/compiler/simple-ar.d.ts

@@ -26,7 +26,7 @@ export class SimpleAR {
      * @param {((data: {targetIndex: number, worldMatrix: number[]}) => void) | null} [options.onUpdate]
      * @param {Object} [options.cameraConfig]
      */
-    constructor({ container, targetSrc, overlay, scale, onFound, onLost, onUpdate, cameraConfig, }: {
+    constructor({ container, targetSrc, overlay, scale, onFound, onLost, onUpdate, cameraConfig, debug, }: {
         container: HTMLElement;
         targetSrc: string | string[];
         overlay: HTMLElement;
@@ -58,6 +58,11 @@ export class SimpleAR {
         worldMatrix: number[];
     }) => void) | null;
     cameraConfig: Object;
+    debug: any;
+    lastTime: number;
+    frameCount: number;
+    fps: number;
+    debugPanel: HTMLDivElement | null;
     video: HTMLVideoElement | null;
     controller: Controller | null;
     isTracking: boolean;
@@ -77,5 +82,7 @@ export class SimpleAR {
     _initController(): void;
     _handleUpdate(data: any): void;
     _positionOverlay(mVT: any, targetIndex: any): void;
+    _createDebugPanel(): void;
+    _updateDebugPanel(isTracking: any): void;
 }
 import { Controller } from "./controller.js";

package/dist/compiler/simple-ar.js

@@ -30,7 +30,7 @@ class SimpleAR {
      * @param {Object} [options.cameraConfig]
      */
     constructor({ container, targetSrc, overlay, scale = 1.0, // Multiplicador de escala personalizado
-    onFound = null, onLost = null, onUpdate = null, cameraConfig = { facingMode: 'environment', width: 1280, height: 720 }, }) {
+    onFound = null, onLost = null, onUpdate = null, cameraConfig = { facingMode: 'environment', width: 1280, height: 720 }, debug = false, }) {
         this.container = container;
         this.targetSrc = targetSrc;
         this.overlay = overlay;
@@ -39,6 +39,13 @@ class SimpleAR {
         this.onLost = onLost;
         this.onUpdateCallback = onUpdate;
         this.cameraConfig = cameraConfig;
+        this.debug = debug;
+        if (this.debug)
+            window.AR_DEBUG = true;
+        this.lastTime = performance.now();
+        this.frameCount = 0;
+        this.fps = 0;
+        this.debugPanel = null;
         this.video = null;
         this.controller = null;
         this.isTracking = false;
@@ -55,6 +62,8 @@ class SimpleAR {
         await this._startCamera();
         // 3. Initialize controller
         this._initController();
+        if (this.debug)
+            this._createDebugPanel();
         // 4. Load targets (supports single URL or array of URLs)
         const targets = Array.isArray(this.targetSrc) ? this.targetSrc : [this.targetSrc];
         const result = await this.controller.addImageTargets(targets);
@@ -114,12 +123,23 @@ class SimpleAR {
         this.controller = new Controller({
             inputWidth: this.video.videoWidth,
             inputHeight: this.video.videoHeight,
+            debugMode: this.debug,
             onUpdate: (data) => this._handleUpdate(data)
         });
     }
     _handleUpdate(data) {
         if (data.type !== 'updateMatrix')
             return;
+        // FPS Calculation
+        const now = performance.now();
+        this.frameCount++;
+        if (now - this.lastTime >= 1000) {
+            this.fps = Math.round((this.frameCount * 1000) / (now - this.lastTime));
+            this.frameCount = 0;
+            this.lastTime = now;
+            if (this.debug)
+                this._updateDebugPanel(this.isTracking);
+        }
         const { targetIndex, worldMatrix, modelViewTransform } = data;
         if (worldMatrix) {
             // Target found
@@ -170,50 +190,104 @@ class SimpleAR {
         const isPortrait = containerRect.height > containerRect.width;
         const isVideoLandscape = videoW > videoH;
         const needsRotation = isPortrait && isVideoLandscape;
-        // 2. Get intrinsic projection from controller
+        // 3. Get intrinsic projection from controller
         const proj = this.controller.projectionTransform;
-        // 3. Project 3 points to determine position, scale, and rotation
-        // Points in Marker Space: Center, Right-Edge, and Down-Edge
-        const pMid = projectToScreen(markerW / 2, markerH / 2, 0, mVT, proj, videoW, videoH, containerRect, needsRotation);
-        const pRight = projectToScreen(markerW / 2 + 100, markerH / 2, 0, mVT, proj, videoW, videoH, containerRect, needsRotation);
-        // 4. Calculate Screen Position
-        const screenX = pMid.sx;
-        const screenY = pMid.sy;
-        // 5. Calculate Rotation and Scale from the projected X-axis vector
-        const dx = pRight.sx - pMid.sx;
-        const dy = pRight.sy - pMid.sy;
-        const rotation = Math.atan2(dy, dx);
-        const pixelDistance100 = Math.sqrt(dx * dx + dy * dy);
-        // Since we projected 100 units, the scale for the whole markerW is:
-        const finalScale = (pixelDistance100 / 100) * this.scaleMultiplier;
-        // DEBUG LOGS
-        if (window.AR_DEBUG) {
-            console.log('--- AR POSITION DEBUG (Point Projection) ---');
-            console.log('Container:', containerRect.width.toFixed(0), 'x', containerRect.height.toFixed(0));
-            console.log('Video:', videoW, 'x', videoH, 'needsRotation:', needsRotation);
-            console.log('Screen Pos:', screenX.toFixed(1), screenY.toFixed(1));
-            console.log('Rotated Angle:', (rotation * 180 / Math.PI).toFixed(1), 'deg');
-            console.log('Final Scale:', finalScale.toFixed(4));
-        }
-        // Apply styles to prevent CSS interference (like max-width: 100%)
+        // 3. Project 4 corners to determine a full 3D perspective (homography)
+        const pUL = projectToScreen(0, 0, 0, mVT, proj, videoW, videoH, containerRect, needsRotation);
+        const pUR = projectToScreen(markerW, 0, 0, mVT, proj, videoW, videoH, containerRect, needsRotation);
+        const pLL = projectToScreen(0, markerH, 0, mVT, proj, videoW, videoH, containerRect, needsRotation);
+        const pLR = projectToScreen(markerW, markerH, 0, mVT, proj, videoW, videoH, containerRect, needsRotation);
+        // Helper to solve for 2D Homography (maps 0..1 square to pUL, pUR, pLL, pLR)
+        const solveHomography = (w, h, p1, p2, p3, p4) => {
+            const x1 = p1.sx, y1 = p1.sy;
+            const x2 = p2.sx, y2 = p2.sy;
+            const x3 = p3.sx, y3 = p3.sy;
+            const x4 = p4.sx, y4 = p4.sy;
+            const dx1 = x2 - x4, dx2 = x3 - x4, dx3 = x1 - x2 + x4 - x3;
+            const dy1 = y2 - y4, dy2 = y3 - y4, dy3 = y1 - y2 + y4 - y3;
+            let a, b, c, d, e, f, g, h_coeff;
+            if (dx3 === 0 && dy3 === 0) {
+                a = x2 - x1;
+                b = x3 - x1;
+                c = x1;
+                d = y2 - y1;
+                e = y3 - y1;
+                f = y1;
+                g = 0;
+                h_coeff = 0;
+            }
+            else {
+                const det = dx1 * dy2 - dx2 * dy1;
+                g = (dx3 * dy2 - dx2 * dy3) / det;
+                h_coeff = (dx1 * dy3 - dx3 * dy1) / det;
+                a = x2 - x1 + g * x2;
+                b = x3 - x1 + h_coeff * x3;
+                c = x1;
+                d = y2 - y1 + g * y2;
+                e = y3 - y1 + h_coeff * y3;
+                f = y1;
+            }
+            // This maps unit square (0..1) to the quadrilateral.
+            // We need to scale it by 1/w and 1/h to map (0..w, 0..h)
+            return [
+                a / w, d / w, 0, g / w,
+                b / h, e / h, 0, h_coeff / h,
+                0, 0, 1, 0,
+                c, f, 0, 1
+            ];
+        };
+        const matrix = solveHomography(markerW, markerH, pUL, pUR, pLL, pLR);
+        // Apply styles
         this.overlay.style.maxWidth = 'none';
-        this.overlay.style.maxHeight = 'none';
         this.overlay.style.width = `${markerW}px`;
-        this.overlay.style.height = 'auto'; // Maintain aspect ratio if user has a custom overlay
+        this.overlay.style.height = `${markerH}px`;
         this.overlay.style.position = 'absolute';
-        this.overlay.style.transformOrigin = 'center center';
-        this.overlay.style.display = 'block';
-        this.overlay.style.margin = '0';
+        this.overlay.style.transformOrigin = '0 0';
         this.overlay.style.left = '0';
         this.overlay.style.top = '0';
-        // Apply final transform
-        // We use translate to move the center of the elements to 0,0 
-        // Then apply our calculated screen position
+        this.overlay.style.display = 'block';
+        // Apply 3D transform with matrix3d
+        // We also apply the user's custom scaleMultiplier AFTER the perspective transform
+        // but since we want to scale around the marker center, we apply it as a prefix/suffix
+        // Scale around top-left (0,0) is easy. Scale around center requires offset.
         this.overlay.style.transform = `
-            translate(${screenX}px, ${screenY}px)
-            translate(-50%, -50%)
-            rotate(${rotation}rad)
-            scale(${finalScale})
+            matrix3d(${matrix.join(',')})
+            translate(${markerW / 2}px, ${markerH / 2}px)
+            scale(${this.scaleMultiplier})
+            translate(${-markerW / 2}px, ${-markerH / 2}px)
+        `;
+    }
+    // Unified projection logic moved to ./utils/projection.js
+    _createDebugPanel() {
+        this.debugPanel = document.createElement('div');
+        this.debugPanel.style.cssText = `
+            position: absolute;
+            top: 10px;
+            left: 10px;
+            background: rgba(0, 0, 0, 0.8);
+            color: #0f0;
+            font-family: monospace;
+            font-size: 12px;
+            padding: 8px;
+            border-radius: 4px;
+            z-index: 99999;
+            pointer-events: none;
+            line-height: 1.5;
+        `;
+        this.container.appendChild(this.debugPanel);
+    }
+    _updateDebugPanel(isTracking) {
+        if (!this.debugPanel)
+            return;
+        const memory = performance.memory ? Math.round(performance.memory.usedJSHeapSize / 1024 / 1024) : '?';
+        const color = isTracking ? '#0f0' : '#f00';
+        const status = isTracking ? 'TRACKING' : 'SEARCHING';
+        this.debugPanel.innerHTML = `
+            <div>HEAD-UP DISPLAY</div>
+            <div>----------------</div>
+            <div>FPS:    ${this.fps}</div>
+            <div>STATUS: <span style="color:${color}">${status}</span></div>
+            <div>MEM:    ${memory} MB</div>
         `;
     }
 }

package/dist/compiler/tracker/tracker.d.ts

@@ -7,15 +7,7 @@ export class Tracker {
     inputHeight: any;
     debugMode: boolean;
     trackingKeyframeList: any[];
-    prebuiltData: {
-        px: Float32Array<any>;
-        py: Float32Array<any>;
-        data: Uint8Array<any>;
-        width: any;
-        height: any;
-        scale: any;
-        projectedImage: Float32Array<ArrayBuffer>;
-    }[];
+    prebuiltData: any[];
     templateBuffer: Float32Array<ArrayBuffer>;
     dummyRun(inputData: any): void;
     track(inputData: any, lastModelViewTransform: any, targetIndex: any): {

package/dist/compiler/tracker/tracker.js

@@ -1,7 +1,7 @@
 import { buildModelViewProjectionTransform, computeScreenCoordiate } from "../estimation/utils.js";
 const AR2_DEFAULT_TS = 6;
 const AR2_DEFAULT_TS_GAP = 1;
-const AR2_SEARCH_SIZE = 10;
+const AR2_SEARCH_SIZE = 18;
 const AR2_SEARCH_GAP = 1;
 const AR2_SIM_THRESH = 0.6;
 const TRACKING_KEYFRAME = 0; // 0: 128px (optimized)
@@ -13,15 +13,12 @@ class Tracker {
         this.inputWidth = inputWidth;
         this.inputHeight = inputHeight;
         this.debugMode = debugMode;
-        this.trackingKeyframeList = [];
+        this.trackingKeyframeList = []; // All octaves for all targets: [targetIndex][octaveIndex]
+        this.prebuiltData = []; // [targetIndex][octaveIndex]
         for (let i = 0; i < trackingDataList.length; i++) {
-            this.trackingKeyframeList.push(trackingDataList[i][TRACKING_KEYFRAME]);
-        }
-        // Prebuild TypedArrays for features and pixels
-        this.prebuiltData = [];
-        for (let i = 0; i < this.trackingKeyframeList.length; i++) {
-            const keyframe = this.trackingKeyframeList[i];
-            this.prebuiltData[i] = {
+            const targetOctaves = trackingDataList[i];
+            this.trackingKeyframeList[i] = targetOctaves;
+            this.prebuiltData[i] = targetOctaves.map(keyframe => ({
                 px: new Float32Array(keyframe.px),
                 py: new Float32Array(keyframe.py),
                 data: new Uint8Array(keyframe.d),
@@ -30,7 +27,7 @@ class Tracker {
                 scale: keyframe.s,
                 // Recyclable projected image buffer
                 projectedImage: new Float32Array(keyframe.w * keyframe.h)
-            };
+            }));
         }
         // Pre-allocate template data buffer to avoid garbage collection
         const templateOneSize = AR2_DEFAULT_TS;
@@ -49,14 +46,31 @@ class Tracker {
     }
     track(inputData, lastModelViewTransform, targetIndex) {
         let debugExtra = {};
+        // Select the best octave based on current estimated distance/scale
+        // We want the octave where the marker size is closest to its projected size on screen
         const modelViewProjectionTransform = buildModelViewProjectionTransform(this.projectionTransform, lastModelViewTransform);
-        const prebuilt = this.prebuiltData[targetIndex];
+        // Estimate current marker width on screen
+        const [mW, mH] = this.markerDimensions[targetIndex];
+        const p0 = computeScreenCoordiate(modelViewProjectionTransform, 0, 0);
+        const p1 = computeScreenCoordiate(modelViewProjectionTransform, mW, 0);
+        const screenW = Math.sqrt((p1.x - p0.x) ** 2 + (p1.y - p0.y) ** 2);
+        // Select octave whose image width is closest to screenW
+        let octaveIndex = 0;
+        let minDiff = Infinity;
+        for (let i = 0; i < this.prebuiltData[targetIndex].length; i++) {
+            const diff = Math.abs(this.prebuiltData[targetIndex][i].width - screenW);
+            if (diff < minDiff) {
+                minDiff = diff;
+                octaveIndex = i;
+            }
+        }
+        const prebuilt = this.prebuiltData[targetIndex][octaveIndex];
         // 1. Compute Projection (Warping)
         this._computeProjection(modelViewProjectionTransform, inputData, prebuilt);
         const projectedImage = prebuilt.projectedImage;
         // 2. Compute Matching (NCC)
         const { matchingPoints, sim } = this._computeMatching(prebuilt, projectedImage);
-        const trackingFrame = this.trackingKeyframeList[targetIndex];
+        const trackingFrame = this.trackingKeyframeList[targetIndex][octaveIndex];
         const worldCoords = [];
         const screenCoords = [];
         const goodTrack = [];
@@ -75,6 +89,7 @@ class Tracker {
         }
         if (this.debugMode) {
             debugExtra = {
+                octaveIndex,
                 projectedImage: Array.from(projectedImage),
                 matchingPoints,
                 goodTrack,

package/package.json

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

package/src/compiler/controller.js

@@ -20,7 +20,7 @@ const DEFAULT_FILTER_BETA = 0.01;  // Beta bajo para suavizar movimientos rápid
 
 const DEFAULT_WARMUP_TOLERANCE = 8; // Más frames de calentamiento para asegurar estabilidad inicial
 
-const DEFAULT_MISS_TOLERANCE = 5;
+const DEFAULT_MISS_TOLERANCE = 2; // Reducido para que el objeto desaparezca más rápido tras pérdida
 
 class Controller {
   constructor({
@@ -231,7 +231,7 @@ class Controller {
       lastModelViewTransform,
       targetIndex,
     );
-    if (worldCoords.length < 4) return null;
+    if (worldCoords.length < 6) return null; // Umbral de puntos mínimos para mantener el seguimiento
     const modelViewTransform = await this._workerTrackUpdate(lastModelViewTransform, {
       worldCoords,
       screenCoords,

package/src/compiler/offline-compiler.js

@@ -260,9 +260,9 @@ export class OfflineCompiler {
     const dataList = this.data.map((item) => {
       const matchingData = item.matchingData.map((kf) => this._packKeyframe(kf));
 
-      const trackingData = [item.trackingData[0]].map((td) => {
+      const trackingData = item.trackingData.map((td) => {
         const count = td.points.length;
-        // Step 1: Packed Coords - Normalize width/height to 16-bit
+        // Packed Coords - Float32 for now as in current import logic
         const px = new Float32Array(count);
         const py = new Float32Array(count);
         for (let i = 0; i < count; i++) {

package/src/compiler/simple-ar.js

@@ -39,6 +39,7 @@ class SimpleAR {
         onLost = null,
         onUpdate = null,
         cameraConfig = { facingMode: 'environment', width: 1280, height: 720 },
+        debug = false,
     }) {
         this.container = container;
         this.targetSrc = targetSrc;
@@ -48,6 +49,13 @@ class SimpleAR {
         this.onLost = onLost;
         this.onUpdateCallback = onUpdate;
         this.cameraConfig = cameraConfig;
+        this.debug = debug;
+        if (this.debug) window.AR_DEBUG = true;
+
+        this.lastTime = performance.now();
+        this.frameCount = 0;
+        this.fps = 0;
+        this.debugPanel = null;
 
         this.video = null;
         this.controller = null;
@@ -69,6 +77,8 @@ class SimpleAR {
         // 3. Initialize controller
         this._initController();
 
+        if (this.debug) this._createDebugPanel();
+
         // 4. Load targets (supports single URL or array of URLs)
         const targets = Array.isArray(this.targetSrc) ? this.targetSrc : [this.targetSrc];
         const result = await this.controller.addImageTargets(targets);
@@ -134,6 +144,7 @@ class SimpleAR {
         this.controller = new Controller({
             inputWidth: this.video.videoWidth,
             inputHeight: this.video.videoHeight,
+            debugMode: this.debug,
             onUpdate: (data) => this._handleUpdate(data)
         });
     }
@@ -141,6 +152,16 @@ class SimpleAR {
     _handleUpdate(data) {
         if (data.type !== 'updateMatrix') return;
 
+        // FPS Calculation
+        const now = performance.now();
+        this.frameCount++;
+        if (now - this.lastTime >= 1000) {
+            this.fps = Math.round((this.frameCount * 1000) / (now - this.lastTime));
+            this.frameCount = 0;
+            this.lastTime = now;
+            if (this.debug) this._updateDebugPanel(this.isTracking);
+        }
+
         const { targetIndex, worldMatrix, modelViewTransform } = data;
 
         if (worldMatrix) {
@@ -198,62 +219,111 @@ class SimpleAR {
         const isVideoLandscape = videoW > videoH;
         const needsRotation = isPortrait && isVideoLandscape;
 
-        // 2. Get intrinsic projection from controller
+        // 3. Get intrinsic projection from controller
         const proj = this.controller.projectionTransform;
 
-        // 3. Project 3 points to determine position, scale, and rotation
-        // Points in Marker Space: Center, Right-Edge, and Down-Edge
-        const pMid = projectToScreen(markerW / 2, markerH / 2, 0, mVT, proj, videoW, videoH, containerRect, needsRotation);
-        const pRight = projectToScreen(markerW / 2 + 100, markerH / 2, 0, mVT, proj, videoW, videoH, containerRect, needsRotation);
-
-        // 4. Calculate Screen Position
-        const screenX = pMid.sx;
-        const screenY = pMid.sy;
-
-        // 5. Calculate Rotation and Scale from the projected X-axis vector
-        const dx = pRight.sx - pMid.sx;
-        const dy = pRight.sy - pMid.sy;
-
-        const rotation = Math.atan2(dy, dx);
-        const pixelDistance100 = Math.sqrt(dx * dx + dy * dy);
-
-        // Since we projected 100 units, the scale for the whole markerW is:
-        const finalScale = (pixelDistance100 / 100) * this.scaleMultiplier;
-
-        // DEBUG LOGS
-        if (window.AR_DEBUG) {
-            console.log('--- AR POSITION DEBUG (Point Projection) ---');
-            console.log('Container:', containerRect.width.toFixed(0), 'x', containerRect.height.toFixed(0));
-            console.log('Video:', videoW, 'x', videoH, 'needsRotation:', needsRotation);
-            console.log('Screen Pos:', screenX.toFixed(1), screenY.toFixed(1));
-            console.log('Rotated Angle:', (rotation * 180 / Math.PI).toFixed(1), 'deg');
-            console.log('Final Scale:', finalScale.toFixed(4));
-        }
+        // 3. Project 4 corners to determine a full 3D perspective (homography)
+        const pUL = projectToScreen(0, 0, 0, mVT, proj, videoW, videoH, containerRect, needsRotation);
+        const pUR = projectToScreen(markerW, 0, 0, mVT, proj, videoW, videoH, containerRect, needsRotation);
+        const pLL = projectToScreen(0, markerH, 0, mVT, proj, videoW, videoH, containerRect, needsRotation);
+        const pLR = projectToScreen(markerW, markerH, 0, mVT, proj, videoW, videoH, containerRect, needsRotation);
+
+        // Helper to solve for 2D Homography (maps 0..1 square to pUL, pUR, pLL, pLR)
+        const solveHomography = (w, h, p1, p2, p3, p4) => {
+            const x1 = p1.sx, y1 = p1.sy;
+            const x2 = p2.sx, y2 = p2.sy;
+            const x3 = p3.sx, y3 = p3.sy;
+            const x4 = p4.sx, y4 = p4.sy;
+
+            const dx1 = x2 - x4, dx2 = x3 - x4, dx3 = x1 - x2 + x4 - x3;
+            const dy1 = y2 - y4, dy2 = y3 - y4, dy3 = y1 - y2 + y4 - y3;
+
+            let a, b, c, d, e, f, g, h_coeff;
+
+            if (dx3 === 0 && dy3 === 0) {
+                a = x2 - x1; b = x3 - x1; c = x1;
+                d = y2 - y1; e = y3 - y1; f = y1;
+                g = 0; h_coeff = 0;
+            } else {
+                const det = dx1 * dy2 - dx2 * dy1;
+                g = (dx3 * dy2 - dx2 * dy3) / det;
+                h_coeff = (dx1 * dy3 - dx3 * dy1) / det;
+                a = x2 - x1 + g * x2;
+                b = x3 - x1 + h_coeff * x3;
+                c = x1;
+                d = y2 - y1 + g * y2;
+                e = y3 - y1 + h_coeff * y3;
+                f = y1;
+            }
+            // This maps unit square (0..1) to the quadrilateral.
+            // We need to scale it by 1/w and 1/h to map (0..w, 0..h)
+            return [
+                a / w, d / w, 0, g / w,
+                b / h, e / h, 0, h_coeff / h,
+                0, 0, 1, 0,
+                c, f, 0, 1
+            ];
+        };
+
+        const matrix = solveHomography(markerW, markerH, pUL, pUR, pLL, pLR);
 
-        // Apply styles to prevent CSS interference (like max-width: 100%)
+        // Apply styles
         this.overlay.style.maxWidth = 'none';
-        this.overlay.style.maxHeight = 'none';
         this.overlay.style.width = `${markerW}px`;
-        this.overlay.style.height = 'auto'; // Maintain aspect ratio if user has a custom overlay
+        this.overlay.style.height = `${markerH}px`;
         this.overlay.style.position = 'absolute';
-        this.overlay.style.transformOrigin = 'center center';
-        this.overlay.style.display = 'block';
-        this.overlay.style.margin = '0';
+        this.overlay.style.transformOrigin = '0 0';
         this.overlay.style.left = '0';
         this.overlay.style.top = '0';
+        this.overlay.style.display = 'block';
 
-        // Apply final transform
-        // We use translate to move the center of the elements to 0,0 
-        // Then apply our calculated screen position
+        // Apply 3D transform with matrix3d
+        // We also apply the user's custom scaleMultiplier AFTER the perspective transform
+        // but since we want to scale around the marker center, we apply it as a prefix/suffix
+        // Scale around top-left (0,0) is easy. Scale around center requires offset.
         this.overlay.style.transform = `
-            translate(${screenX}px, ${screenY}px)
-            translate(-50%, -50%)
-            rotate(${rotation}rad)
-            scale(${finalScale})
+            matrix3d(${matrix.join(',')})
+            translate(${markerW / 2}px, ${markerH / 2}px)
+            scale(${this.scaleMultiplier})
+            translate(${-markerW / 2}px, ${-markerH / 2}px)
         `;
     }
 
     // Unified projection logic moved to ./utils/projection.js
+
+    _createDebugPanel() {
+        this.debugPanel = document.createElement('div');
+        this.debugPanel.style.cssText = `
+            position: absolute;
+            top: 10px;
+            left: 10px;
+            background: rgba(0, 0, 0, 0.8);
+            color: #0f0;
+            font-family: monospace;
+            font-size: 12px;
+            padding: 8px;
+            border-radius: 4px;
+            z-index: 99999;
+            pointer-events: none;
+            line-height: 1.5;
+        `;
+        this.container.appendChild(this.debugPanel);
+    }
+
+    _updateDebugPanel(isTracking) {
+        if (!this.debugPanel) return;
+        const memory = performance.memory ? Math.round(performance.memory.usedJSHeapSize / 1024 / 1024) : '?';
+        const color = isTracking ? '#0f0' : '#f00';
+        const status = isTracking ? 'TRACKING' : 'SEARCHING';
+
+        this.debugPanel.innerHTML = `
+            <div>HEAD-UP DISPLAY</div>
+            <div>----------------</div>
+            <div>FPS:    ${this.fps}</div>
+            <div>STATUS: <span style="color:${color}">${status}</span></div>
+            <div>MEM:    ${memory} MB</div>
+        `;
+    }
 }
 
 export { SimpleAR };

package/src/compiler/tracker/tracker.js

@@ -2,7 +2,7 @@ import { buildModelViewProjectionTransform, computeScreenCoordiate } from "../es
 
 const AR2_DEFAULT_TS = 6;
 const AR2_DEFAULT_TS_GAP = 1;
-const AR2_SEARCH_SIZE = 10;
+const AR2_SEARCH_SIZE = 18;
 const AR2_SEARCH_GAP = 1;
 const AR2_SIM_THRESH = 0.6;
 
@@ -24,16 +24,13 @@ class Tracker {
     this.inputHeight = inputHeight;
     this.debugMode = debugMode;
 
-    this.trackingKeyframeList = [];
-    for (let i = 0; i < trackingDataList.length; i++) {
-      this.trackingKeyframeList.push(trackingDataList[i][TRACKING_KEYFRAME]);
-    }
+    this.trackingKeyframeList = []; // All octaves for all targets: [targetIndex][octaveIndex]
+    this.prebuiltData = []; // [targetIndex][octaveIndex]
 
-    // Prebuild TypedArrays for features and pixels
-    this.prebuiltData = [];
-    for (let i = 0; i < this.trackingKeyframeList.length; i++) {
-      const keyframe = this.trackingKeyframeList[i];
-      this.prebuiltData[i] = {
+    for (let i = 0; i < trackingDataList.length; i++) {
+      const targetOctaves = trackingDataList[i];
+      this.trackingKeyframeList[i] = targetOctaves;
+      this.prebuiltData[i] = targetOctaves.map(keyframe => ({
         px: new Float32Array(keyframe.px),
         py: new Float32Array(keyframe.py),
         data: new Uint8Array(keyframe.d),
@@ -42,7 +39,7 @@ class Tracker {
         scale: keyframe.s,
         // Recyclable projected image buffer
         projectedImage: new Float32Array(keyframe.w * keyframe.h)
-      };
+      }));
     }
 
     // Pre-allocate template data buffer to avoid garbage collection
@@ -65,12 +62,31 @@ class Tracker {
   track(inputData, lastModelViewTransform, targetIndex) {
     let debugExtra = {};
 
+    // Select the best octave based on current estimated distance/scale
+    // We want the octave where the marker size is closest to its projected size on screen
     const modelViewProjectionTransform = buildModelViewProjectionTransform(
       this.projectionTransform,
       lastModelViewTransform,
     );
 
-    const prebuilt = this.prebuiltData[targetIndex];
+    // Estimate current marker width on screen
+    const [mW, mH] = this.markerDimensions[targetIndex];
+    const p0 = computeScreenCoordiate(modelViewProjectionTransform, 0, 0);
+    const p1 = computeScreenCoordiate(modelViewProjectionTransform, mW, 0);
+    const screenW = Math.sqrt((p1.x - p0.x) ** 2 + (p1.y - p0.y) ** 2);
+
+    // Select octave whose image width is closest to screenW
+    let octaveIndex = 0;
+    let minDiff = Infinity;
+    for (let i = 0; i < this.prebuiltData[targetIndex].length; i++) {
+      const diff = Math.abs(this.prebuiltData[targetIndex][i].width - screenW);
+      if (diff < minDiff) {
+        minDiff = diff;
+        octaveIndex = i;
+      }
+    }
+
+    const prebuilt = this.prebuiltData[targetIndex][octaveIndex];
 
     // 1. Compute Projection (Warping)
     this._computeProjection(
@@ -87,7 +103,7 @@ class Tracker {
       projectedImage
     );
 
-    const trackingFrame = this.trackingKeyframeList[targetIndex];
+    const trackingFrame = this.trackingKeyframeList[targetIndex][octaveIndex];
     const worldCoords = [];
     const screenCoords = [];
     const goodTrack = [];
@@ -113,6 +129,7 @@ class Tracker {
 
     if (this.debugMode) {
       debugExtra = {
+        octaveIndex,
         projectedImage: Array.from(projectedImage),
         matchingPoints,
         goodTrack,