@srsergio/taptapp-ar 1.0.43 → 1.0.50

package/README.md

@@ -1,5 +1,11 @@
 # @srsergio/taptapp-ar
 
+<p align="center">
+  <a href="./docs/technical-paper.pdf">📄 <b>Technical Paper (PDF)</b></a> &nbsp;|&nbsp;
+  <a href="./docs/index.html">🌐 <b>Official Website</b></a> &nbsp;|&nbsp;
+  <a href="./analysis/INDEX.md">📊 <b>Analysis Report</b></a>
+</p>
+
 🚀 **TapTapp AR** is a high-performance Augmented Reality (AR) toolkit for **Node.js** and **Browser** environments. It provides an ultra-fast offline compiler and a lightweight runtime for image tracking.
 
 **100% Pure JavaScript**: This package is now completely independent of **TensorFlow.js** for both compilation and real-time tracking, resulting in massive performance gains and zero-latency initialization.
@@ -8,11 +14,14 @@
 
 ## 🌟 Key Features
 
-- 🖼️ **Hyper-Fast Compiler**: Pure JavaScript compiler that generates `.mind` files in **< 0.9s per image**.
+- 🖼️ **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).
-- 🚀 **Protocol V5.1 (Moonshot LSH)**: 128-bit Locality Sensitive Hashing (LSH) for descriptors, resulting in **5-10x smaller metadata** and ultra-fast binary matching.
-- 🧵 **High-Precision Tracking**: Now using **Float32** coordinate precision for rock-solid tracking stability, even in low-light or extreme angles.
+- 🚀 **Protocol V7 (Moonshot)**: 
+  - **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.
 - 📦 **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).
 
 ---
 
@@ -24,14 +33,14 @@ npm install @srsergio/taptapp-ar
 
 ---
 
-## 📊 Industry-Leading Benchmarks (v5.1 Moonshot)
+## 📊 Industry-Leading Benchmarks (v7 Moonshot)
 
-| Metric | Official MindAR | TapTapp AR V5.1 | Improvement |
+| Metric | Official MindAR | TapTapp AR V7 | Improvement |
 | :--- | :--- | :--- | :--- |
-| **Compilation Time** | ~23.50s | **~0.89s** | 🚀 **26x Faster** |
-| **Output Size (.mind)** | ~770 KB | **~137 KB** | 📉 **82.2% Smaller** |
-| **Descriptor Format** | 84-byte Float | **128-bit LSH** | 🧠 **81% Data Saving** |
-| **Matching Engine** | Iterative Math | **Popcount XOR** | ⚡ **10x Faster Math** |
+| **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** |
+| **Tracking Data** | 8-bit Gray | **4-bit Packed** | 📦 **50% Data Saving** |
 | **Dependency Size** | ~20MB (TFJS) | **< 100KB** | 📦 **99% Smaller Bundle** |
 
 ---
@@ -42,17 +51,17 @@ The latest version has been rigorously tested with an adaptive stress test (`rob
 
 | Metric | Result | Description |
 | :--- | :--- | :--- |
-| **Pass Rate** | **96.3%** | 208/216 Tests passed across all conditions. |
+| **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 (no compression artifacts). |
+| **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) on single core. |
+| **Total Pipeline** | **~64ms** | Complete loop (Detect + Match + Track + Validate). |
 
 ---
 
 ## 🖼️ Compiler Usage (Node.js & Web)
 
-The compiler is designed to run in workers (Node.js or Browser) for maximum performance.
+The compiler is optimized to run in workers for maximum performance.
 
 ```javascript
 import { OfflineCompiler } from '@srsergio/taptapp-ar';
@@ -60,12 +69,13 @@ import { OfflineCompiler } from '@srsergio/taptapp-ar';
 const compiler = new OfflineCompiler();
 
 // Compile target image (provide grayscale pixel data)
+// Input: { width, height, data: Uint8Array }
 await compiler.compileImageTargets(
   [{ width, height, data: grayscaleUint8Array }], 
   (progress) => console.log(`Compiling: ${progress}%`)
 );
 
-// Export to high-efficiency binary format
+// Export to high-efficiency binary format (Protocol V7)
 const binaryBuffer = compiler.exportData(); 
 ```
 
@@ -80,9 +90,9 @@ The easiest way to use TapTapp AR in a web app:
 <script src="https://aframe.io/releases/1.5.0/aframe.min.js"></script>
 <script src="path/to/@srsergio/taptapp-ar/dist/index.js"></script>
 
-<a-scene mindar-image="imageTargetSrc: ./targets.mind;">
+<a-scene taar-image="imageTargetSrc: ./targets.taar;">
   <a-camera position="0 0 0" look-controls="enabled: false"></a-camera>
-  <a-entity mindar-image-target="targetIndex: 0">
+  <a-entity taar-image-target="targetIndex: 0">
     <a-plane position="0 0 0" height="0.552" width="1"></a-plane>
   </a-entity>
 </a-scene>
@@ -92,19 +102,19 @@ The easiest way to use TapTapp AR in a web app:
 For custom Three.js applications:
 
 ```javascript
-import { MindARThree } from '@srsergio/taptapp-ar';
+import { TaarThree } from '@srsergio/taptapp-ar';
 
-const mindarThree = new MindARThree({
+const taarThree = new TaarThree({
   container: document.querySelector("#container"),
-  imageTargetSrc: './targets.mind',
+  imageTargetSrc: './targets.taar',
 });
 
-const {renderer, scene, camera} = mindarThree;
+const {renderer, scene, camera} = taarThree;
 
-const anchor = mindarThree.addAnchor(0);
+const anchor = taarThree.addAnchor(0);
 // Add your 3D models to anchor.group
 
-await mindarThree.start();
+await taarThree.start();
 renderer.setAnimationLoop(() => {
   renderer.render(scene, camera);
 });
@@ -150,10 +160,10 @@ const controller = new Controller({
 });
 
 // Single target
-await controller.addImageTargets('./targets.mind');
+await controller.addImageTargets('./targets.taar');
 
-// OR multiple targets from different .mind files
-await controller.addImageTargets(['./target1.mind', './target2.mind', './target3.mind']);
+// OR multiple targets from different .taar files
+await controller.addImageTargets(['./target1.taar', './target2.taar', './target3.taar']);
 controller.processVideo(videoElement); // Starts the internal RAF loop
 ```
 
@@ -162,7 +172,7 @@ Use this for "Snap and Detect" features without a continuous video loop:
 
 ```javascript
 const controller = new Controller({ inputWidth: 1024, inputHeight: 1024 });
-await controller.addImageTargets('./targets.mind');
+await controller.addImageTargets('./targets.taar');
 
 // 1. Detect features in a static image
 const { featurePoints } = await controller.detect(canvasElement);
@@ -183,7 +193,7 @@ import { SimpleAR } from '@srsergio/taptapp-ar';
 
 const ar = new SimpleAR({
   container: document.getElementById('ar-container'),
-  targetSrc: './my-target.mind',  // Single URL or array: ['./a.mind', './b.mind']
+  targetSrc: './my-target.taar',  // Single URL or array: ['./a.taar', './b.taar']
   overlay: document.getElementById('my-overlay'),
   onFound: ({ targetIndex }) => console.log(`Target ${targetIndex} detected! 🎯`),
   onLost: ({ targetIndex }) => console.log(`Target ${targetIndex} lost 👋`)
@@ -207,7 +217,7 @@ ar.stop();
   
   const ar = new SimpleAR({
     container: document.getElementById('ar-container'),
-    targetSrc: './targets.mind',
+    targetSrc: './targets.taar',
     overlay: document.getElementById('my-overlay'),
   });
   
@@ -219,7 +229,7 @@ ar.stop();
 | Option | Required | Description |
 | :--- | :--- | :--- |
 | `container` | ✅ | DOM element where video + overlay render |
-| `targetSrc` | ✅ | URL to your `.mind` file |
+| `targetSrc` | ✅ | URL to your `.taar` file |
 | `overlay` | ✅ | DOM element to position on the target |
 | `onFound` | ❌ | Callback when target is detected |
 | `onLost` | ❌ | Callback when target is lost |
@@ -228,26 +238,13 @@ ar.stop();
 
 ---
 
-#### 🛠️ Life-cycle Management
-Properly management is crucial to avoid memory leaks:
-
-```javascript
-// Stop the video loop
-controller.stopProcessVideo();
-
-// Clean up workers and internal buffers
-controller.dispose();
-```
-
----
-
-## 🏗️ Protocol V5.1 (Moonshot LSH Format)
+## 🏗️ Protocol V7 (Moonshot Packed Format)
 TapTapp AR uses a proprietary **Moonshot Vision Codec** that is significantly more efficient than standard AR formats.
 
-- **128-bit LSH Fingerprinting**: Each feature point is compressed from 84 bytes to 16 bytes using Locality Sensitive Hashing.
+- **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.
 - **Binary Matching Engine**: Uses hardware-accelerated population count (`popcount`) and `XOR` for near-instant point matching.
 - **Zero-Copy Restoration**: Binary buffers are mapped directly to TypedArrays (Uint32 for descriptors, Float32 for tracking coordinates).
-- **Cache Locality**: Performance is optimized for modern CPUs by keeping coordinates and descriptors adjacent in memory.
 
 ---
 

package/dist/compiler/aframe.js

@@ -1,5 +1,5 @@
 import { Controller, UI } from "./index.js";
-AFRAME.registerSystem("mindar-image-system", {
+AFRAME.registerSystem("taar-image-system", {
     container: null,
     video: null,
     processingImage: false,
@@ -174,8 +174,8 @@ AFRAME.registerSystem("mindar-image-system", {
         this.video.style.height = vh + "px";
     },
 });
-AFRAME.registerComponent("mindar-image", {
-    dependencies: ["mindar-image-system"],
+AFRAME.registerComponent("taar-image", {
+    dependencies: ["taar-image-system"],
     schema: {
         imageTargetSrc: { type: "string" },
         maxTrack: { type: "int", default: 1 },
@@ -190,7 +190,7 @@ AFRAME.registerComponent("mindar-image", {
         uiError: { type: "string", default: "yes" },
     },
     init: function () {
-        const arSystem = this.el.sceneEl.systems["mindar-image-system"];
+        const arSystem = this.el.sceneEl.systems["taar-image-system"];
         arSystem.setup({
             imageTargetSrc: this.data.imageTargetSrc,
             maxTrack: this.data.maxTrack,
@@ -214,14 +214,14 @@ AFRAME.registerComponent("mindar-image", {
         arSystem.stop();
     },
 });
-AFRAME.registerComponent("mindar-image-target", {
-    dependencies: ["mindar-image-system"],
+AFRAME.registerComponent("taar-image-target", {
+    dependencies: ["taar-image-system"],
     schema: {
         targetIndex: { type: "number" },
     },
     postMatrix: null, // rescale the anchor to make width of 1 unit = physical width of card
     init: function () {
-        const arSystem = this.el.sceneEl.systems["mindar-image-system"];
+        const arSystem = this.el.sceneEl.systems["taar-image-system"];
         arSystem.registerAnchor(this, this.data.targetIndex);
         this.invisibleMatrix = new AFRAME.THREE.Matrix4().set(0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0);
         const root = this.el.object3D;
@@ -267,6 +267,6 @@ then A-Frame will process the webpage *before* the system and components get reg
 Resulting in a blank page. This happens because module loading is deferred.
 */
 /* if(needsDOMRefresh){
-  console.log("mindar-face-aframe::Refreshing DOM...")
+  console.log("taar-face-aframe::Refreshing DOM...")
   document.body.innerHTML=document.body.innerHTML;
 } */

package/dist/compiler/controller.d.ts

@@ -1,18 +1,21 @@
-export class Controller {
-    constructor({ inputWidth, inputHeight, onUpdate, debugMode, maxTrack, warmupTolerance, missTolerance, filterMinCF, filterBeta, worker, }: {
-        inputWidth: any;
-        inputHeight: any;
-        onUpdate?: null | undefined;
-        debugMode?: boolean | undefined;
-        maxTrack?: number | undefined;
-        warmupTolerance?: null | undefined;
-        missTolerance?: null | undefined;
-        filterMinCF?: null | undefined;
-        filterBeta?: null | undefined;
-        worker?: null | undefined;
-    });
-    inputWidth: any;
-    inputHeight: any;
+import { Tracker } from "./tracker/tracker.js";
+import { CropDetector } from "./detector/crop-detector.js";
+import { InputLoader } from "./input-loader.js";
+export interface ControllerOptions {
+    inputWidth: number;
+    inputHeight: number;
+    onUpdate?: ((data: any) => void) | null;
+    debugMode?: boolean;
+    maxTrack?: number;
+    warmupTolerance?: number | null;
+    missTolerance?: number | null;
+    filterMinCF?: number | null;
+    filterBeta?: number | null;
+    worker?: any;
+}
+declare class Controller {
+    inputWidth: number;
+    inputHeight: number;
     maxTrack: number;
     filterMinCF: number;
     filterBeta: number;
@@ -20,8 +23,8 @@ export class Controller {
     missTolerance: number;
     cropDetector: CropDetector;
     inputLoader: InputLoader;
-    markerDimensions: any[][] | null;
-    onUpdate: any;
+    markerDimensions: any[] | null;
+    onUpdate: ((data: any) => void) | null;
     debugMode: boolean;
     processingVideo: boolean;
     interestedTargetIndex: number;
@@ -29,48 +32,40 @@ export class Controller {
     worker: any;
     projectionTransform: number[][];
     projectionMatrix: number[];
+    tracker: Tracker | null;
+    matchingDataList: any;
+    workerMatchDone: ((data: any) => void) | null;
+    workerTrackDone: ((data: any) => void) | null;
+    mainThreadMatcher: any;
+    mainThreadEstimator: any;
+    constructor({ inputWidth, inputHeight, onUpdate, debugMode, maxTrack, warmupTolerance, missTolerance, filterMinCF, filterBeta, worker, }: ControllerOptions);
     _setupWorkerListener(): void;
     _ensureWorker(): void;
-    /**
-     * Load image targets from one or multiple .mind files
-     * @param {string|string[]} fileURLs - Single URL or array of URLs to .mind files
-     * @returns {Promise<{dimensions, matchingDataList, trackingDataList}>}
-     */
     addImageTargets(fileURLs: string | string[]): Promise<{
-        dimensions: any;
-        matchingDataList: any;
-        trackingDataList: any;
+        dimensions: any[];
+        matchingDataList: any[];
+        trackingDataList: any[];
     }>;
-    /**
-     * Load image targets from multiple ArrayBuffers
-     * @param {ArrayBuffer[]} buffers - Array of .mind file buffers
-     */
     addImageTargetsFromBuffers(buffers: ArrayBuffer[]): {
-        dimensions: any[][];
+        dimensions: any[];
         matchingDataList: any[];
         trackingDataList: any[];
     };
-    tracker: Tracker | undefined;
-    matchingDataList: any[] | undefined;
-    /**
-     * Load image targets from a single ArrayBuffer (backward compatible)
-     * @param {ArrayBuffer} buffer - Single .mind file buffer
-     */
     addImageTargetsFromBuffer(buffer: ArrayBuffer): {
-        dimensions: any[][];
+        dimensions: any[];
         matchingDataList: any[];
         trackingDataList: any[];
     };
     dispose(): void;
     dummyRun(input: any): void;
     getProjectionMatrix(): number[];
-    getRotatedZ90Matrix(m: any): any[];
-    getWorldMatrix(modelViewTransform: any, targetIndex: any): any[];
-    _detectAndMatch(inputData: any, targetIndexes: any): Promise<{
+    getRotatedZ90Matrix(m: number[]): number[];
+    getWorldMatrix(modelViewTransform: number[][], targetIndex: number): number[];
+    _detectAndMatch(inputData: any, targetIndexes: number[]): Promise<{
         targetIndex: any;
         modelViewTransform: any;
     }>;
-    _trackAndUpdate(inputData: any, lastModelViewTransform: any, targetIndex: any): Promise<any>;
+    _trackAndUpdate(inputData: any, lastModelViewTransform: number[][], targetIndex: number): Promise<any>;
     processVideo(input: any): void;
     stopProcessVideo(): void;
     detect(input: any): Promise<{
@@ -81,14 +76,14 @@ export class Controller {
             projectedImage?: undefined;
         };
     }>;
-    match(featurePoints: any, targetIndex: any): Promise<{
+    match(featurePoints: any, targetIndex: number): Promise<{
         targetIndex: any;
         modelViewTransform: any;
         screenCoords: any;
         worldCoords: any;
         debugExtra: any;
     }>;
-    track(input: any, modelViewTransform: any, targetIndex: any): Promise<{
+    track(input: any, modelViewTransform: number[][], targetIndex: number): Promise<{
         worldCoords: {
             x: number;
             y: number;
@@ -100,39 +95,18 @@ export class Controller {
         }[];
         debugExtra: {};
     }>;
-    trackUpdate(modelViewTransform: any, trackFeatures: any): Promise<any>;
-    _workerMatch(featurePoints: any, targetIndexes: any): Promise<any>;
-    workerMatchDone: ((data: any) => void) | undefined;
-    _matchOnMainThread(featurePoints: any, targetIndexes: any): Promise<{
+    trackUpdate(modelViewTransform: number[][], trackFeatures: any): Promise<any>;
+    _workerMatch(featurePoints: any, targetIndexes: number[]): Promise<any>;
+    _matchOnMainThread(featurePoints: any, targetIndexes: number[]): Promise<{
         targetIndex: number;
-        modelViewTransform: number[][] | null;
-        screenCoords: {
-            x: any;
-            y: any;
-        }[] | null | undefined;
-        worldCoords: {
-            x: number;
-            y: number;
-            z: number;
-        }[] | null | undefined;
-        debugExtra: {
-            frames: never[];
-        } | null;
+        modelViewTransform: any;
+        screenCoords: any;
+        worldCoords: any;
+        debugExtra: any;
     }>;
-    mainThreadMatcher: import("./matching/matcher.js").Matcher | undefined;
-    mainThreadEstimator: import("./estimation/estimator.js").Estimator | undefined;
-    _workerTrackUpdate(modelViewTransform: any, trackingFeatures: any): Promise<any>;
-    workerTrackDone: ((data: any) => void) | undefined;
-    _trackUpdateOnMainThread(modelViewTransform: any, trackingFeatures: any): Promise<never[][] | null>;
-    _glModelViewMatrix(modelViewTransform: any, targetIndex: any): any[];
-    _glProjectionMatrix({ projectionTransform, width, height, near, far }: {
-        projectionTransform: any;
-        width: any;
-        height: any;
-        near: any;
-        far: any;
-    }): number[];
+    _workerTrackUpdate(modelViewTransform: number[][], trackingFeatures: any): Promise<any>;
+    _trackUpdateOnMainThread(modelViewTransform: number[][], trackingFeatures: any): Promise<any>;
+    _glModelViewMatrix(modelViewTransform: number[][], targetIndex: number): number[];
+    _glProjectionMatrix({ projectionTransform, width, height, near, far }: any): number[];
 }
-import { CropDetector } from "./detector/crop-detector.js";
-import { InputLoader } from "./input-loader.js";
-import { Tracker } from "./tracker/tracker.js";
+export { Controller };