@srsergio/taptapp-ar 1.0.88 → 1.0.90

package/README.md

@@ -29,14 +29,18 @@
 
 ## 🌟 Key Features
 
-- 🖼️ **Hyper-Fast Compiler**: Pure JavaScript compiler that generates `.taar` files in **< 3s**.
+- 🎭 **Non-Rigid Surface Tracking**: Supports curved and deformable surfaces using **Delaunay Meshes** and **Mass-Spring Relaxation**.
+- 🚀 **Hyper-Fast Compiler**: Pure JavaScript compiler that generates `.taar` files in **< 3s**.
 - ⚡ **No TensorFlow Dependency**: No TFJS at all. Works natively in any JS environment (Node, Browser, Workers).
 - 🧬 **Fourier Positional Encoding**: Uses high-frequency sine/cosine mappings (GPT-style) for neural-like spatial consistency.
 - 🚀 **Protocol V7 (Moonshot)**: 
+  - **Delaunay Triangular Grid**: Adaptive mesh that tracks surface deformations.
   - **16-bit Fourier Signatures**: Spatial ADN embedded in every feature for harmonic matching.
   - **4-bit Packed Tracking Data**: Grayscale images are compressed to 4-bit depth, slashing file size.
   - **64-bit LSH Descriptors**: Optimized Locality Sensitive Hashing for descriptors.
-- 🧵 **High-Precision Tracking**: Now using **Float32** coordinate precision for rock-solid tracking stability.
+- 🧵 **High-Precision Tracking**: Now using **Float32** coordinate precision with sub-pixel resolution and multi-octave verification (1%, 50%, 25%, 12.5% scales).
+- 📏 **Ultra-Wide Scaling**: Enhanced Hough Transform supporting a massive scale range from **1% (distant targets)** to **1000% (extreme close-up)**.
+- ⚡ **Immediate AR Detection**: Optimized "warm-up" period (15 frames) with relaxed inlier thresholds (6 pts) for instant tracking lock.
 - 📦 **Framework Agnostic**: Includes wrappers for **A-Frame**, **Three.js**, and a raw **Controller** for custom engines.
 - 📉 **Ultra-Compact Files**: Output `.taar` files are **~50KB** (vs ~380KB+ previously).
 
@@ -54,9 +58,9 @@ npm install @srsergio/taptapp-ar
 
 | Metric | Official MindAR | TapTapp AR V7 | Improvement |
 | :--- | :--- | :--- | :--- |
-| **Compilation Time** | ~23.50s | **~2.61s** | 🚀 **~9x Faster** |
-| **Output Size (.taar)** | ~770 KB | **~50 KB** | 📉 **93% Smaller** |
-| **Descriptor Format** | 84-byte Float | **64-bit LSH** | 🧠 **Massive Data Saving** |
+| **Compilation Time** | ~23.50s | **~0.93s** | 🚀 **~25x Faster** |
+| **Output Size (.taar)** | ~770 KB | **~338 KB** | 📉 **56% Smaller** |
+| **Descriptor Format** | 84-byte Float | **128-bit LSH** | 🧠 **Massive Data Saving** |
 | **Tracking Data** | 8-bit Gray | **4-bit Packed** | 📦 **50% Data Saving** |
 | **Dependency Size** | ~20MB (TFJS) | **< 100KB** | 📦 **99% Smaller Bundle** |
 
@@ -68,11 +72,11 @@ The latest version has been rigorously tested with an adaptive stress test (`rob
 
 | Metric | Result | Description |
 | :--- | :--- | :--- |
-| **Pass Rate** | **96.3%** | High success rate across resolutions. |
-| **Drift Tolerance** | **< 15%** | Validated geometrically against ground truth metadata. |
-| **Tracking Precision** | **Float32** | Full 32-bit precision for optical flow tracking. |
-| **Detection Time** | **~21ms** | Ultra-fast initial detection on standard CPU. |
-| **Total Pipeline** | **~64ms** | Complete loop (Detect + Match + Track + Validate). |
+| **Pass Rate** | **96.8%** | High success rate across resolutions (209/216). |
+| **Drift Tolerance** | **< 2%** | Validated via sub-pixel coordinate system restoration. |
+| **Tracking Precision** | **Double-Precision Fix** | Corrected coordinate scaling for all image octaves. |
+| **Detection Time** | **< 10ms** | Ultra-fast initial detection on standard CPU. |
+| **Total Pipeline** | **~35ms** | Complete loop (Detect + Match + Track + Validate). |
 
 ---
 
@@ -258,6 +262,8 @@ ar.stop();
 ## 🏗️ Protocol V7 (Moonshot Packed Format)
 TapTapp AR uses a proprietary **Moonshot Vision Codec** that is significantly more efficient than standard AR formats.
 
+- **Non-Rigid Surface Tracking**: Replaces the standard rigid homography with a dynamic **Delaunay Mesh**. This allows the tracker to follow the curvature of posters on cylinders, t-shirts, or slightly bent magazines.
+- **Mass-Spring Relaxation**: The tracking mesh is optimized using physical relaxation, minimizing L2 distance between predicted and tracked points while maintaining topological rigidity.
 - **Fourier Positional Encoding**: Maps 2D coordinates into a 16-dimensional frequency space. This creates a "Neural Consistency Check" that filters out noise and motion blur by checking for harmonic spatial agreement.
 - **4-bit Packed Tracking Data**: Image data used for optical flow is compressed to 4-bit depth.
 - **64-bit LSH Fingerprinting**: Feature descriptors are compressed to just 8 bytes using LSH.
@@ -271,3 +277,4 @@ TapTapp AR uses a proprietary **Moonshot Vision Codec** that is significantly mo
 MIT © [srsergiolazaro](https://github.com/srsergiolazaro)
 
 Based on the core research of MindAR, but completely re-written for high-performance binary processing and JS-only execution.
+

package/dist/compiler/offline-compiler.js

@@ -11,6 +11,7 @@ import { DetectorLite } from "../core/detector/detector-lite.js";
 import { build as hierarchicalClusteringBuild } from "../core/matching/hierarchical-clustering.js";
 import * as protocol from "../core/protocol.js";
 import { triangulate, getEdges } from "../core/utils/delaunay.js";
+import { generateBasis, projectDescriptor, compressToSignature } from "../core/matching/hdc.js";
 // Detect environment
 const isNode = typeof process !== "undefined" &&
     process.versions != null &&
@@ -72,12 +73,22 @@ export class OfflineCompiler {
         const results = [];
         for (let i = 0; i < targetImages.length; i++) {
             const targetImage = targetImages[i];
-            const imageList = buildImageList(targetImage);
+            const fullImageList = buildImageList(targetImage);
+            // 🚀 MOONSHOT: Keep many scales for better robustness
+            const imageList = fullImageList;
             const percentPerImageScale = percentPerImage / imageList.length;
             const keyframes = [];
             for (const image of imageList) {
-                const detector = new DetectorLite(image.width, image.height, { useLSH: true, maxFeaturesPerBucket: 20 });
+                const detector = new DetectorLite(image.width, image.height, { useLSH: true, maxFeaturesPerBucket: 40 });
                 const { featurePoints: ps } = detector.detect(image.data);
+                // HDC Pre-calculation
+                const hdcBasis = generateBasis(protocol.HDC_SEED, 1024);
+                for (const p of ps) {
+                    if (p.descriptors) {
+                        const hv = projectDescriptor(p.descriptors, hdcBasis);
+                        p.hdcSignature = compressToSignature(hv);
+                    }
+                }
                 const maximaPoints = ps.filter((p) => p.maxima);
                 const minimaPoints = ps.filter((p) => !p.maxima);
                 const maximaPointsCluster = hierarchicalClusteringBuild({ points: maximaPoints });
@@ -168,8 +179,9 @@ export class OfflineCompiler {
                     w: kf.width,
                     h: kf.height,
                     s: kf.scale,
-                    max: protocol.columnarize(kf.maximaPoints, kf.maximaPointsCluster, kf.width, kf.height),
-                    min: protocol.columnarize(kf.minimaPoints, kf.minimaPointsCluster, kf.width, kf.height),
+                    hdc: false,
+                    max: protocol.columnarize(kf.maximaPoints, kf.maximaPointsCluster, kf.width, kf.height, false),
+                    min: protocol.columnarize(kf.minimaPoints, kf.minimaPointsCluster, kf.width, kf.height, false),
                 })),
             };
         });

package/dist/core/detector/detector-lite.d.ts

@@ -8,6 +8,7 @@ export class DetectorLite {
     height: any;
     useGPU: any;
     useLSH: any;
+    useHDC: any;
     maxFeaturesPerBucket: any;
     numOctaves: number;
     /**

package/dist/core/detector/detector-lite.js

@@ -12,10 +12,12 @@
 import { FREAKPOINTS } from "./freak.js";
 import { gpuCompute } from "../utils/gpu-compute.js";
 import { computeLSH64, computeFullFREAK, packLSHIntoDescriptor } from "../utils/lsh-direct.js";
+import { generateBasis, projectDescriptor, compressToSignature } from "../matching/hdc.js";
+import { HDC_SEED } from "../protocol.js";
 const PYRAMID_MIN_SIZE = 4; // Restored to 4 for better small-scale detection
 // PYRAMID_MAX_OCTAVE ya no es necesario, el límite lo da PYRAMID_MIN_SIZE
-const NUM_BUCKETS_PER_DIMENSION = 10;
-const DEFAULT_MAX_FEATURES_PER_BUCKET = 8;
+const NUM_BUCKETS_PER_DIMENSION = 15; // Increased from 10 to 15 for better local detail
+const DEFAULT_MAX_FEATURES_PER_BUCKET = 12; // Increased from 8 to 12
 const ORIENTATION_NUM_BINS = 36;
 const FREAK_EXPANSION_FACTOR = 7.0;
 // Global GPU mode flag
@@ -37,6 +39,7 @@ export class DetectorLite {
         this.useGPU = options.useGPU !== undefined ? options.useGPU : globalUseGPU;
         // Protocol V6 (Moonshot): 64-bit LSH is the standard descriptor format
         this.useLSH = options.useLSH !== undefined ? options.useLSH : true;
+        this.useHDC = options.useHDC !== undefined ? options.useHDC : true; // Enabled by default for Moonshot
         this.maxFeaturesPerBucket = options.maxFeaturesPerBucket !== undefined ? options.maxFeaturesPerBucket : DEFAULT_MAX_FEATURES_PER_BUCKET;
         let numOctaves = 0;
         let w = width, h = height;
@@ -79,6 +82,16 @@ export class DetectorLite {
         this._computeOrientations(prunedExtremas, pyramidImages);
         // 6. Calcular descriptores FREAK
         this._computeFreakDescriptors(prunedExtremas, pyramidImages);
+        // 7. 🚀 MOONSHOT: HDC Hyper-projection
+        if (this.useHDC) {
+            const hdcBasis = generateBasis(HDC_SEED, 1024);
+            for (const ext of prunedExtremas) {
+                if (ext.lsh) {
+                    const hv = projectDescriptor(ext.lsh, hdcBasis);
+                    ext.hdcSignature = compressToSignature(hv);
+                }
+            }
+        }
         // Convertir a formato de salida
         const featurePoints = prunedExtremas.map(ext => {
             const scale = Math.pow(2, ext.octave);
@@ -88,7 +101,9 @@ export class DetectorLite {
                 y: ext.y * scale + scale * 0.5 - 0.5,
                 scale: scale,
                 angle: ext.angle || 0,
-                descriptors: (this.useLSH && ext.lsh) ? ext.lsh : (ext.descriptors || [])
+                descriptors: (this.useLSH && ext.lsh) ? ext.lsh : (ext.descriptors || []),
+                hdcSignature: ext.hdcSignature || 0,
+                imageData: data // Pass source image for refinement
             };
         });
         return { featurePoints, pyramid: pyramidImages };
@@ -154,35 +169,36 @@ export class DetectorLite {
         // Horizontal pass - Speed optimized with manual border handling
         for (let y = 0; y < height; y++) {
             const rowOffset = y * width;
-            // Left border
-            temp[rowOffset] = data[rowOffset] * (k0 + k1 + k2) + data[rowOffset + 1] * k1 + data[rowOffset + 2] * k0;
-            temp[rowOffset + 1] = data[rowOffset] * k1 + data[rowOffset + 1] * k2 + data[rowOffset + 2] * k1 + data[rowOffset + 3] * k0;
+            // Left border (Normalized)
+            const sumL0 = k0 + k1 + k2 + k1 + k0; // Ideal sum
+            temp[rowOffset] = (data[rowOffset] * (k0 + k1 + k2) + data[rowOffset + 1] * k1 + data[rowOffset + 2] * k0) * (1.0 / (k0 + k1 + k2));
+            temp[rowOffset + 1] = (data[rowOffset] * k1 + data[rowOffset + 1] * k2 + data[rowOffset + 2] * k1 + data[rowOffset + 3] * k0) * (1.0 / (k1 + k2 + k1 + k0));
             // Main loop - NO boundary checks
             for (let x = 2; x < width - 2; x++) {
                 const pos = rowOffset + x;
                 temp[pos] = data[pos - 2] * k0 + data[pos - 1] * k1 + data[pos] * k2 + data[pos + 1] * k1 + data[pos + 2] * k0;
             }
-            // Right border
+            // Right border (Normalized)
             const r2 = rowOffset + width - 2;
             const r1 = rowOffset + width - 1;
-            temp[r2] = data[r2 - 2] * k0 + data[r2 - 1] * k1 + data[r2] * k2 + data[r1] * k1;
-            temp[r1] = data[r1 - 2] * k0 + data[r1 - 1] * k1 + data[r1] * (k2 + k1 + k0);
+            temp[r2] = (data[r2 - 2] * k0 + data[r2 - 1] * k1 + data[r2] * k2 + data[r1] * k1) * (1.0 / (k0 + k1 + k2 + k1));
+            temp[r1] = (data[r1 - 2] * k0 + data[r1 - 1] * k1 + data[r1] * (k2 + k1 + k0)) * (1.0 / (k0 + k1 + k2));
         }
         // Vertical pass - Speed optimized
         for (let x = 0; x < width; x++) {
-            // Top border
-            output[x] = temp[x] * (k0 + k1 + k2) + temp[x + width] * k1 + temp[x + width * 2] * k0;
-            output[x + width] = temp[x] * k1 + temp[x + width] * k2 + temp[x + width * 2] * k1 + temp[x + width * 3] * k0;
+            // Top border (Normalized)
+            output[x] = (temp[x] * (k0 + k1 + k2) + temp[x + width] * k1 + temp[x + width * 2] * k0) * (1.0 / (k0 + k1 + k2));
+            output[x + width] = (temp[x] * k1 + temp[x + width] * k2 + temp[x + width * 2] * k1 + temp[x + width * 3] * k0) * (1.0 / (k1 + k2 + k1 + k0));
             // Main loop - NO boundary checks
             for (let y = 2; y < height - 2; y++) {
                 const p = y * width + x;
                 output[p] = temp[p - width * 2] * k0 + temp[p - width] * k1 + temp[p] * k2 + temp[p + width] * k1 + temp[p + width * 2] * k0;
             }
-            // Bottom border
+            // Bottom border (Normalized)
             const b2 = (height - 2) * width + x;
             const b1 = (height - 1) * width + x;
-            output[b2] = temp[b2 - width * 2] * k0 + temp[b2 - width] * k1 + temp[b2] * k2 + temp[b1] * k1;
-            output[b1] = temp[b1 - width * 2] * k0 + temp[b1 - width] * k1 + temp[b1] * (k2 + k1 + k0);
+            output[b2] = (temp[b2 - width * 2] * k0 + temp[b2 - width] * k1 + temp[b2] * k2 + temp[b1] * k1) * (1.0 / (k0 + k1 + k2 + k1));
+            output[b1] = (temp[b1 - width * 2] * k0 + temp[b1 - width] * k1 + temp[b1] * (k2 + k1 + k0)) * (1.0 / (k0 + k1 + k2));
         }
         return { data: output, width, height };
     }

package/dist/core/estimation/estimate.d.ts

@@ -1,3 +1,10 @@
+/**
+ * 🚀 MOONSHOT: Direct PnP Solver for AR
+ *
+ * Instead of estimating a 2D Homography and decomposing it,
+ * we solve for the 3D Pose [R|t] directly using the
+ * Perspective-n-Point algorithm.
+ */
 export function estimate({ screenCoords, worldCoords, projectionTransform }: {
     screenCoords: any;
     worldCoords: any;

package/dist/core/estimation/estimate.js

@@ -1,51 +1,16 @@
-import { Matrix, inverse } from "ml-matrix";
-import { solveHomography } from "../utils/homography.js";
-// build world matrix with list of matching worldCoords|screenCoords
-//
-// Step 1. estimate homography with list of pairs
-// Ref: https://www.uio.no/studier/emner/matnat/its/TEK5030/v19/lect/lecture_4_3-estimating-homographies-from-feature-correspondences.pdf  (Basic homography estimation from points)
-//
-// Step 2. decompose homography into rotation and translation matrixes (i.e. world matrix)
-// Ref: can anyone provide reference?
+import { solvePosePnP } from "./pnp-solver.js";
+/**
+ * 🚀 MOONSHOT: Direct PnP Solver for AR
+ *
+ * Instead of estimating a 2D Homography and decomposing it,
+ * we solve for the 3D Pose [R|t] directly using the
+ * Perspective-n-Point algorithm.
+ */
 const estimate = ({ screenCoords, worldCoords, projectionTransform }) => {
-    const Harray = solveHomography(worldCoords.map((p) => [p.x, p.y]), screenCoords.map((p) => [p.x, p.y]));
-    const H = new Matrix([
-        [Harray[0], Harray[1], Harray[2]],
-        [Harray[3], Harray[4], Harray[5]],
-        [Harray[6], Harray[7], Harray[8]],
-    ]);
-    const K = new Matrix(projectionTransform);
-    const KInv = inverse(K);
-    const _KInvH = KInv.mmul(H);
-    const KInvH = _KInvH.to1DArray();
-    const norm1 = Math.sqrt(KInvH[0] * KInvH[0] + KInvH[3] * KInvH[3] + KInvH[6] * KInvH[6]);
-    const norm2 = Math.sqrt(KInvH[1] * KInvH[1] + KInvH[4] * KInvH[4] + KInvH[7] * KInvH[7]);
-    const tnorm = (norm1 + norm2) / 2;
-    const rotate = [];
-    rotate[0] = KInvH[0] / norm1;
-    rotate[3] = KInvH[3] / norm1;
-    rotate[6] = KInvH[6] / norm1;
-    rotate[1] = KInvH[1] / norm2;
-    rotate[4] = KInvH[4] / norm2;
-    rotate[7] = KInvH[7] / norm2;
-    rotate[2] = rotate[3] * rotate[7] - rotate[6] * rotate[4];
-    rotate[5] = rotate[6] * rotate[1] - rotate[0] * rotate[7];
-    rotate[8] = rotate[0] * rotate[4] - rotate[1] * rotate[3];
-    const norm3 = Math.sqrt(rotate[2] * rotate[2] + rotate[5] * rotate[5] + rotate[8] * rotate[8]);
-    rotate[2] /= norm3;
-    rotate[5] /= norm3;
-    rotate[8] /= norm3;
-    // TODO: artoolkit has check_rotation() that somehow switch the rotate vector. not sure what that does. Can anyone advice?
-    // https://github.com/artoolkitx/artoolkit5/blob/5bf0b671ff16ead527b9b892e6aeb1a2771f97be/lib/SRC/ARICP/icpUtil.c#L215
-    const tran = [];
-    tran[0] = KInvH[2] / tnorm;
-    tran[1] = KInvH[5] / tnorm;
-    tran[2] = KInvH[8] / tnorm;
-    let initialModelViewTransform = [
-        [rotate[0], rotate[1], rotate[2], tran[0]],
-        [rotate[3], rotate[4], rotate[5], tran[1]],
-        [rotate[6], rotate[7], rotate[8], tran[2]],
-    ];
-    return initialModelViewTransform;
+    return solvePosePnP({
+        screenCoords,
+        worldCoords,
+        projectionTransform
+    });
 };
 export { estimate };

package/dist/core/estimation/morph-refinement.d.ts

@@ -0,0 +1,8 @@
+export function refineWithMorphology({ imageData, width, height, targetData, initialH, iterations }: {
+    imageData: any;
+    width: any;
+    height: any;
+    targetData: any;
+    initialH: any;
+    iterations?: number | undefined;
+}): any[];

package/dist/core/estimation/morph-refinement.js

@@ -0,0 +1,116 @@
+/**
+ * Morphological Refinement - "Active Edge Alignment"
+ *
+ * This Moonshot algorithm snaps the projected target to the real image edges.
+ * It solves the "Small Box / Drift" problem by maximizing alignment with
+ * local image gradients using a Spring-Mass optimization system.
+ */
+import { Matrix, SingularValueDecomposition } from "ml-matrix";
+export function refineWithMorphology({ imageData, width, height, targetData, initialH, iterations = 3 }) {
+    let currentH = [...initialH];
+    // 1. Boundary Points (The "Anchors" of our elastic malla)
+    const boundaryPoints = [];
+    const step = 0.05;
+    for (let i = 0; i <= 1.0; i += step) {
+        boundaryPoints.push({ x: i * targetData.w, y: 0 });
+        boundaryPoints.push({ x: i * targetData.w, y: targetData.h });
+        boundaryPoints.push({ x: 0, y: i * targetData.h });
+        boundaryPoints.push({ x: targetData.w, y: i * targetData.h });
+    }
+    for (let iter = 0; iter < iterations; iter++) {
+        const correspondences = [];
+        for (const pt of boundaryPoints) {
+            // Project
+            const w = currentH[6] * pt.x + currentH[7] * pt.y + currentH[8];
+            const sx = (currentH[0] * pt.x + currentH[1] * pt.y + currentH[2]) / w;
+            const sy = (currentH[3] * pt.x + currentH[4] * pt.y + currentH[5]) / w;
+            if (sx < 2 || sx >= width - 2 || sy < 2 || sy >= height - 2)
+                continue;
+            // 2. Local Gradient Search (The "Pull" of the image)
+            const searchDist = 10;
+            let bestX = sx;
+            let bestY = sy;
+            let maxGrad = -1;
+            for (let dy = -searchDist; dy <= searchDist; dy += 2) {
+                for (let dx = -searchDist; dx <= searchDist; dx += 2) {
+                    const nx = Math.floor(sx + dx);
+                    const ny = Math.floor(sy + dy);
+                    const idx = ny * width + nx;
+                    // Sobel-like gradient magnitude
+                    const gx = imageData[idx + 1] - imageData[idx - 1];
+                    const gy = imageData[idx + width] - imageData[idx - width];
+                    const grad = gx * gx + gy * gy;
+                    if (grad > maxGrad) {
+                        maxGrad = grad;
+                        bestX = nx;
+                        bestY = ny;
+                    }
+                }
+            }
+            if (maxGrad > 500) {
+                correspondences.push({
+                    src: pt,
+                    dst: { x: bestX, y: bestY },
+                    weight: Math.min(1.0, maxGrad / 15000)
+                });
+            }
+        }
+        if (correspondences.length < 10)
+            break;
+        // 3. Solve for best Homography using SVD
+        const nextH = solveDLTWeight(correspondences);
+        if (nextH) {
+            // Soft-Update (Momentum)
+            for (let i = 0; i < 9; i++) {
+                currentH[i] = currentH[i] * 0.5 + nextH[i] * 0.5;
+            }
+        }
+    }
+    return currentH;
+}
+/**
+ * Direct Linear Transform with Weights
+ */
+function solveDLTWeight(pairs) {
+    const n = pairs.length;
+    const A = new Matrix(n * 2, 9);
+    for (let i = 0; i < n; i++) {
+        const { src, dst, weight: w } = pairs[i];
+        const x = src.x;
+        const y = src.y;
+        const xp = dst.x;
+        const yp = dst.y;
+        // Row 1
+        A.set(i * 2, 0, 0);
+        A.set(i * 2, 1, 0);
+        A.set(i * 2, 2, 0);
+        A.set(i * 2, 3, -x * w);
+        A.set(i * 2, 4, -y * w);
+        A.set(i * 2, 5, -w);
+        A.set(i * 2, 6, yp * x * w);
+        A.set(i * 2, 7, yp * y * w);
+        A.set(i * 2, 8, yp * w);
+        // Row 2
+        A.set(i * 2 + 1, 0, x * w);
+        A.set(i * 2 + 1, 1, y * w);
+        A.set(i * 2 + 1, 2, w);
+        A.set(i * 2 + 1, 3, 0);
+        A.set(i * 2 + 1, 4, 0);
+        A.set(i * 2 + 1, 5, 0);
+        A.set(i * 2 + 1, 6, -xp * x * w);
+        A.set(i * 2 + 1, 7, -xp * y * w);
+        A.set(i * 2 + 1, 8, -xp * w);
+    }
+    try {
+        const svd = new SingularValueDecomposition(A);
+        const V = svd.rightSingularVectors;
+        // Last column of V is the solution
+        const h = V.getColumn(8);
+        // Normalize H[8] to 1
+        const scale = 1.0 / h[8];
+        return h.map(v => v * scale);
+    }
+    catch (e) {
+        return null;
+    }
+}

package/dist/core/estimation/pnp-solver.d.ts

@@ -0,0 +1,5 @@
+export function solvePosePnP({ screenCoords, worldCoords, projectionTransform }: {
+    screenCoords: any;
+    worldCoords: any;
+    projectionTransform: any;
+}): number[][];

package/dist/core/estimation/pnp-solver.js

@@ -0,0 +1,109 @@
+/**
+ * Direct PnP (Perspective-n-Point) Solver for Planar Targets
+ *
+ * This Moonshot algorithm ignores octave-relative scales and works
+ * purely in Physical World Units. It uses the Camera Matrix (K)
+ * to deduce the real-world distance (Z).
+ */
+import { Matrix, SingularValueDecomposition } from "ml-matrix";
+export function solvePosePnP({ screenCoords, worldCoords, projectionTransform }) {
+    const K = new Matrix(projectionTransform);
+    const n = screenCoords.length;
+    // 1. Build the DLT matrix for Pose (Directly estimating [R|t])
+    // We assume worldCoords are [X, Y, 0]
+    // Eq: x = K * [R|t] * X
+    // K^-1 * x = [r1 r2 t] * [X Y 1]^T
+    const KI = Inverse3x3(projectionTransform);
+    const A = new Matrix(n * 2, 9);
+    for (let i = 0; i < n; i++) {
+        const sci = screenCoords[i];
+        const wci = worldCoords[i];
+        // Normalized camera coordinates
+        const nx = KI[0] * sci.x + KI[1] * sci.y + KI[2];
+        const ny = KI[3] * sci.x + KI[4] * sci.y + KI[5];
+        const nz = KI[6] * sci.x + KI[7] * sci.y + KI[8];
+        const unx = nx / nz;
+        const uny = ny / nz;
+        // DLT equations for [r11 r12 r21 r22 r31 r32 t1 t2 t3]
+        const X = wci.x;
+        const Y = wci.y;
+        // Row 1: X*r11 + Y*r12 + t1 - unx*(X*r31 + Y*r32 + t3) = 0
+        A.set(i * 2, 0, X);
+        A.set(i * 2, 1, Y);
+        A.set(i * 2, 2, 1);
+        A.set(i * 2, 3, 0);
+        A.set(i * 2, 4, 0);
+        A.set(i * 2, 5, 0);
+        A.set(i * 2, 6, -unx * X);
+        A.set(i * 2, 7, -unx * Y);
+        A.set(i * 2, 8, -unx);
+        // Row 2: X*r21 + Y*r22 + t2 - uny*(X*r31 + Y*r32 + t3) = 0
+        A.set(i * 2 + 1, 0, 0);
+        A.set(i * 2 + 1, 1, 0);
+        A.set(i * 2 + 1, 2, 0);
+        A.set(i * 2 + 1, 3, X);
+        A.set(i * 2 + 1, 4, Y);
+        A.set(i * 2 + 1, 5, 1);
+        A.set(i * 2 + 1, 6, -uny * X);
+        A.set(i * 2 + 1, 7, -uny * Y);
+        A.set(i * 2 + 1, 8, -uny);
+    }
+    // Solve via SVD
+    const svd = new SingularValueDecomposition(A);
+    const V = svd.rightSingularVectors;
+    const sol = V.getColumn(8); // last column
+    // 3. Extract r1, r2 and t from the DLT solution
+    // Standard DLT has an overall sign ambiguity. We force sol[8] (t3) to be positive.
+    if (sol[8] < 0) {
+        for (let i = 0; i < 9; i++)
+            sol[i] = -sol[i];
+    }
+    const r1_raw = [sol[0], sol[3], sol[6]];
+    const r2_raw = [sol[1], sol[4], sol[7]];
+    const t_raw = [sol[2], sol[5], sol[8]];
+    const scale1 = Math.sqrt(r1_raw[0] ** 2 + r1_raw[1] ** 2 + r1_raw[2] ** 2);
+    const scale2 = Math.sqrt(r2_raw[0] ** 2 + r2_raw[1] ** 2 + r2_raw[2] ** 2);
+    const scale = (scale1 + scale2) / 2;
+    // 4. Construct Rotation Matrix and orthogonalize via SVD
+    const R_approx = new Matrix([
+        [r1_raw[0] / scale1, r2_raw[0] / scale2, 0],
+        [r1_raw[1] / scale1, r2_raw[1] / scale2, 0],
+        [r1_raw[2] / scale1, r2_raw[2] / scale2, 0]
+    ]);
+    // R3 = R1 x R2
+    R_approx.set(0, 2, R_approx.get(1, 0) * R_approx.get(2, 1) - R_approx.get(2, 0) * R_approx.get(1, 1));
+    R_approx.set(1, 2, R_approx.get(2, 0) * R_approx.get(0, 1) - R_approx.get(0, 0) * R_approx.get(2, 1));
+    R_approx.set(2, 2, R_approx.get(0, 0) * R_approx.get(1, 1) - R_approx.get(1, 0) * R_approx.get(0, 1));
+    const svdRot = new SingularValueDecomposition(R_approx);
+    const U = svdRot.leftSingularVectors;
+    const Vrot = svdRot.rightSingularVectors;
+    let R = U.mmul(Vrot.transpose());
+    const getDet3 = (m) => {
+        return m.get(0, 0) * (m.get(1, 1) * m.get(2, 2) - m.get(1, 2) * m.get(2, 1)) -
+            m.get(0, 1) * (m.get(1, 0) * m.get(2, 2) - m.get(1, 2) * m.get(2, 0)) +
+            m.get(0, 2) * (m.get(1, 0) * m.get(2, 1) - m.get(1, 1) * m.get(2, 0));
+    };
+    if (getDet3(R) < 0) {
+        const U_mat = U.clone();
+        for (let i = 0; i < 3; i++)
+            U_mat.set(i, 2, -U_mat.get(i, 2));
+        R = U_mat.mmul(Vrot.transpose());
+    }
+    return [
+        [R.get(0, 0), R.get(0, 1), R.get(0, 2), t_raw[0] / scale],
+        [R.get(1, 0), R.get(1, 1), R.get(1, 2), t_raw[1] / scale],
+        [R.get(2, 0), R.get(2, 1), R.get(2, 2), t_raw[2] / scale]
+    ];
+}
+function Inverse3x3(m) {
+    const k00 = m[0][0], k01 = m[0][1], k02 = m[0][2];
+    const k10 = m[1][0], k11 = m[1][1], k12 = m[1][2];
+    const k20 = m[2][0], k21 = m[2][1], k22 = m[2][2];
+    const det = k00 * (k11 * k22 - k21 * k12) - k01 * (k10 * k22 - k12 * k20) + k02 * (k10 * k21 - k11 * k20);
+    const invDet = 1.0 / det;
+    return [
+        (k11 * k22 - k12 * k21) * invDet, (k02 * k21 - k01 * k22) * invDet, (k01 * k12 - k02 * k11) * invDet,
+        (k12 * k20 - k10 * k22) * invDet, (k00 * k22 - k02 * k20) * invDet, (k10 * k02 - k00 * k12) * invDet,
+        (k10 * k21 - k11 * k20) * invDet, (k20 * k01 - k21 * k00) * invDet, (k00 * k11 - k10 * k01) * invDet
+    ];
+}

package/dist/core/input-loader.js

@@ -32,15 +32,32 @@ class InputLoader {
         if (this.context) {
             this.context.clearRect(0, 0, this.width, this.height);
             const isInputRotated = input.width === this.height && input.height === this.width;
+            const inputW = isInputRotated ? input.height : input.width;
+            const inputH = isInputRotated ? input.width : input.height;
+            const inputAspect = inputW / inputH;
+            const canvasAspect = this.width / this.height;
+            let sx = 0, sy = 0, sw = inputW, sh = inputH;
+            if (inputAspect > canvasAspect) {
+                // Input is wider than canvas - crop sides
+                sw = inputH * canvasAspect;
+                sx = (inputW - sw) / 2;
+            }
+            else if (inputAspect < canvasAspect) {
+                // Input is taller than canvas - crop top/bottom
+                sh = inputW / canvasAspect;
+                sy = (inputH - sh) / 2;
+            }
             if (isInputRotated) {
                 this.context.save();
                 this.context.translate(this.width / 2, this.height / 2);
                 this.context.rotate(Math.PI / 2);
-                this.context.drawImage(input, -input.width / 2, -input.height / 2);
+                // Map source crop (relative to rotated input)
+                // Since input is already rotated, we crop based on the rotated dimensions
+                this.context.drawImage(input, sx, sy, sw, sh, -this.height / 2, -this.width / 2, this.height, this.width);
                 this.context.restore();
             }
             else {
-                this.context.drawImage(input, 0, 0, this.width, this.height);
+                this.context.drawImage(input, sx, sy, sw, sh, 0, 0, this.width, this.height);
             }
             const imageData = this.context.getImageData(0, 0, this.width, this.height);
             this._convertToGrayscale(imageData.data, this.width, this.height);

package/dist/core/matching/hdc.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Hyperdimensional Computing (HDC) Core for AR
+ *
+ * Provides ultra-fast, ultra-compressed feature matching using
+ * High-Dimensional Random Vectors.
+ */
+export declare const HDC_DIMENSION = 1024;
+export declare const HDC_WORDS: number;
+/**
+ * Generates a deterministic basis of Hypervectors
+ */
+export declare function generateBasis(seed: number, count: number): Uint32Array[];
+/**
+ * Projects a 64-bit descriptor into the Hyperdimensional Space
+ * Uses "Random Projection" logic (Locality Sensitive Hashing in HDC)
+ */
+export declare function projectDescriptor(desc: Uint32Array, basis: Uint32Array[]): Uint32Array;
+/**
+ * Compresses an HDC vector into an "Ultra-Short Signature" (32 bits)
+ * This allows storing 1000 points in just 4KB of descriptors.
+ */
+export declare function compressToSignature(hv: Uint32Array): number;
+/**
+ * Bundles multiple points into a single Global Hypervector (The "Image DNA")
+ * This allows checking if an image is present with ONE vector comparison.
+ */
+export declare function bundle(hvs: Uint32Array[]): Uint32Array;