@srsergio/taptapp-ar 1.0.95 → 1.0.97

package/README.md

@@ -38,10 +38,11 @@
   - **Dynamic Scale Filtering (LOD)**: Runtime matching engine skips irrelevant octaves based on estimated scale.
   - **4-bit Packed Tracking Data**: Grayscale images are compressed to 4-bit depth, slashing file size.
   - **64-bit LSH Descriptors**: Optimized Locality Sensitive Hashing with XOR folding support.
-- 🧵 **High-Precision Tracking**: Now using **Float32** coordinate precision with sub-pixel resolution and stratified scale coverage.
+- 🧵 **HD Precision Tracking**: Default resolution upgraded to **1280x960 (HD)** for superior sharpness on modern displays.
+- ⚡ **Zero-Config JIT Compilation**: No need for offline tools. Just pass an image URL and the engine compiles it on the fly.
 - 📏 **Virtualized Scale Range**: Stable tracking from **20% (distant targets)** to **1000% (close-up)** using a single high-res keyframe.
 - ⚡ **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.
+- 📦 **Framework Agnostic**: Includes wrappers for **React**, **A-Frame**, **Three.js**, and a raw **Controller**.
 - 📉 **Ultra-Compact Files**: Output `.taar` files are now **~100KB** (vs ~380KB+ previously).
 
 ---
@@ -80,183 +81,84 @@ The latest version has been rigorously tested with an adaptive stress test (`rob
 
 ---
 
-## 🖼️ Compiler Usage (Node.js & Web)
+## 🖼️ Compiler Usage (Automatic / JIT)
 
-The compiler is optimized to run in workers for maximum performance.
+The new **TapTapp AR** engine handles compilation automatically in the browser (Just-In-Time). You likely **don't need** to use the offline compiler manually anymore.
 
-```javascript
-import { OfflineCompiler } from '@srsergio/taptapp-ar';
+Simply pass your image URL to the tracker, and it will compile it on the fly:
 
-const compiler = new OfflineCompiler();
+```typescript
+// No compilation step needed!
+const tracker = await startTracking({
+  targetSrc: './my-image.jpg' // Using a JPG/PNG directly
+});
+```
 
-// Compile target image (provide grayscale pixel data)
-// Input: { width, height, data: Uint8Array }
-await compiler.compileImageTargets(
-  [{ width, height, data: grayscaleUint8Array }], 
-  (progress) => console.log(`Compiling: ${progress}%`)
-);
+However, if you still want to pre-compile for faster startup on low-end devices:
 
-// Export to high-efficiency binary format (Protocol V7)
-const binaryBuffer = compiler.exportData(); 
+```javascript
+import { OfflineCompiler } from '@srsergio/taptapp-ar';
+// ... same compiler code as before ...
 ```
 
 ---
 
 ## 🎥 Runtime Usage (AR Tracking)
 
-### 1. Simple A-Frame Integration
-The easiest way to use TapTapp AR in a web app:
+### 1. The Easy Way: React Component ⚛️
 
-```html
-<script src="https://aframe.io/releases/1.5.0/aframe.min.js"></script>
-<script src="path/to/@srsergio/taptapp-ar/dist/index.js"></script>
+The simplest, zero-config way to add AR to your app:
 
-<a-scene taar-image="imageTargetSrc: ./targets.taar;">
-  <a-camera position="0 0 0" look-controls="enabled: false"></a-camera>
-  <a-entity taar-image-target="targetIndex: 0">
-    <a-plane position="0 0 0" height="0.552" width="1"></a-plane>
-  </a-entity>
-</a-scene>
-```
+```tsx
+import { TaptappAR } from '@srsergio/taptapp-ar/react';
 
-### 2. High-Performance Three.js Wrapper
-For custom Three.js applications:
-
-```javascript
-import { TaarThree } from '@srsergio/taptapp-ar';
-
-const taarThree = new TaarThree({
-  container: document.querySelector("#container"),
-  imageTargetSrc: './targets.taar',
-});
-
-const {renderer, scene, camera} = taarThree;
-
-const anchor = taarThree.addAnchor(0);
-// Add your 3D models to anchor.group
-
-await taarThree.start();
-renderer.setAnimationLoop(() => {
-  renderer.render(scene, camera);
-});
+export const MyARScene = () => (
+  <TaptappAR 
+    config={{
+      targetImageSrc: "https://example.com/target.jpg", // Direct Image URL
+      videoSrc: "https://example.com/overlay.mp4",     // Content to show
+      scale: 1.2
+    }} 
+  />
+);
 ```
 
-### 3. Raw Controller (Advanced & Custom Engines)
-The `Controller` is the core engine of TapTapp AR. You can use it to build your own AR components or integrate tracking into custom 3D engines.
+### 2. The Powerful Way: `startTracking` API
 
-#### ⚙️ Controller Configuration
-| Property | Default | Description |
-| :--- | :--- | :--- |
-| `inputWidth` | **Required** | The width of the video or image source. |
-| `inputHeight` | **Required** | The height of the video or image source. |
-| `maxTrack` | `1` | Max number of images to track simultaneously. |
-| `warmupTolerance` | `5` | Frames of consistent detection needed to "lock" a target. |
-| `missTolerance` | `5` | Frames of missed detection before considering the target "lost". |
-| `filterMinCF` | `0.001` | Min cutoff frequency for the OneEuroFilter (reduces jitter). |
-| `filterBeta` | `1000` | Filter beta parameter (higher = more responsive, lower = smoother). |
-| `onUpdate` | `null` | Callback for tracking events (Found, Lost, ProcessDone). |
-| `debugMode` | `false` | If true, returns extra debug data (cropped images, feature points). |
-| `worker` | `null` | Pass a custom worker instance if using a specialized environment. |
-
-#### 🚀 Example: Tracking a Video Stream
-Ideal for real-time AR apps in the browser:
+For vanilla JS or custom integrations, use the new high-level API:
 
-```javascript
-import { Controller } from '@srsergio/taptapp-ar';
-
-const controller = new Controller({
-  inputWidth: video.videoWidth,
-  inputHeight: video.videoHeight,
-  onUpdate: (data) => {
-    if (data.type === 'updateMatrix') {
-      const { targetIndex, worldMatrix } = data;
-      if (worldMatrix) {
-        console.log(`Target ${targetIndex} detected! Matrix:`, worldMatrix);
-        // Apply worldMatrix (Float32Array[16]) to your 3D object
-      } else {
-        console.log(`Target ${targetIndex} lost.`);
-      }
+```typescript
+import { startTracking } from '@srsergio/taptapp-ar';
+
+const tracker = await startTracking({
+    targetSrc: './assets/target.jpg', // No .taar needed!
+    container: document.getElementById('ar-container'),
+    overlay: document.getElementById('overlay-element'),
+    
+    // Optional callbacks
+    callbacks: {
+        onFound: () => console.log("Target Found! 🎯"),
+        onLost: () => console.log("Target Lost 👋"),
+        onUpdate: (data) => {
+             console.log("Stability:", data.avgStability);
+        }
     }
-  }
 });
 
-// Single target
-await controller.addImageTargets('./targets.taar');
-
-// OR multiple targets from different .taar files
-await controller.addImageTargets(['./target1.taar', './target2.taar', './target3.taar']);
-controller.processVideo(videoElement); // Starts the internal RAF loop
+// Stop later
+// tracker.stop();
 ```
 
-#### 📸 Example: One-shot Image Matching
-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.taar');
-
-// 1. Detect features in a static image
-const { featurePoints } = await controller.detect(canvasElement);
-
-// 2. Attempt to match against a specific target index
-const { targetIndex, modelViewTransform } = await controller.match(featurePoints, 0);
-
-if (targetIndex !== -1) {
-  // Found a match! Use modelViewTransform for initial pose estimation
-}
-```
+### 3. Advanced Integration (Three.js / A-Frame)
 
-### 4. Vanilla JS (No Framework) 🍦
-The **simplest way** to use AR—no Three.js, no A-Frame. Just overlay an image on the tracked target.
+We still provide wrappers for 3D engines if you need to render complex 3D models instead of DOM overlays.
 
+#### Three.js Adapter
 ```javascript
-import { SimpleAR } from '@srsergio/taptapp-ar';
-
-const ar = new SimpleAR({
-  container: document.getElementById('ar-container'),
-  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 👋`)
-});
-
-await ar.start();
-
-// When done:
-ar.stop();
-```
-
-#### 📁 Minimal HTML
-```html
-<div id="ar-container" style="width: 100vw; height: 100vh;">
-  <img id="my-overlay" src="./overlay.png" 
-       style="opacity: 0; z-index: 1; width: 200px; transition: opacity 0.3s;" />
-</div>
-
-<script type="module">
-  import { SimpleAR } from '@srsergio/taptapp-ar';
-  
-  const ar = new SimpleAR({
-    container: document.getElementById('ar-container'),
-    targetSrc: './targets.taar',
-    overlay: document.getElementById('my-overlay'),
-  });
-  
-  ar.start();
-</script>
+import { TaarThree } from '@srsergio/taptapp-ar';
+// ... (standard Three.js integration)
 ```
 
-#### ⚙️ SimpleAR Options
-| Option | Required | Description |
-| :--- | :--- | :--- |
-| `container` | ✅ | DOM element where video + overlay render |
-| `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 |
-| `onUpdate` | ❌ | Called each frame with `{ targetIndex, worldMatrix }` |
-| `cameraConfig` | ❌ | Camera constraints (default: `{ facingMode: 'environment', width: 1280, height: 720 }`) |
-
 ---
 
 ## 🏗️ Protocol V11 (Nanite Virtualized Format)

package/dist/index.d.ts

@@ -3,5 +3,5 @@ export * from "./react/TaptappAR.js";
 export * from "./react/use-ar.js";
 export * from "./compiler/offline-compiler.js";
 export { Controller } from "./runtime/controller.js";
-export { SimpleAR } from "./runtime/simple-ar.js";
+export { createTracker, startTracking } from "./runtime/track.js";
 export * as protocol from "./core/protocol.js";

package/dist/index.js

@@ -3,5 +3,5 @@ export * from "./react/TaptappAR.js";
 export * from "./react/use-ar.js";
 export * from "./compiler/offline-compiler.js";
 export { Controller } from "./runtime/controller.js";
-export { SimpleAR } from "./runtime/simple-ar.js";
+export { createTracker, startTracking } from "./runtime/track.js";
 export * as protocol from "./core/protocol.js";

package/dist/react/TaptappAR.js

@@ -2,7 +2,7 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useMemo } from "react";
 import { useAR } from "./use-ar.js";
 export const TaptappAR = ({ config, className = "", showScanningOverlay = true, showErrorOverlay = true }) => {
-    const { containerRef, overlayRef, status, toggleVideo, trackedPoints } = useAR(config);
+    const { containerRef, overlayRef, status, toggleVideo, trackedPoints, error } = useAR(config);
     // Simple heuristic to determine if it's a video or image
     // based on the presence of videoSrc and common extensions
     const isVideo = useMemo(() => {
@@ -12,7 +12,7 @@ export const TaptappAR = ({ config, className = "", showScanningOverlay = true,
         const url = config.videoSrc.toLowerCase().split('?')[0];
         return videoExtensions.some(ext => url.endsWith(ext)) || config.videoSrc.includes('video');
     }, [config.videoSrc]);
-    return (_jsxs("div", { className: `taptapp-ar-wrapper ${className} ${status}`, style: { position: 'relative', width: '100%', height: '100%', overflow: 'hidden' }, children: [showScanningOverlay && status === "scanning" && (_jsx("div", { className: "taptapp-ar-overlay taptapp-ar-scanning", children: _jsxs("div", { className: "scanning-content", children: [_jsxs("div", { className: "scanning-frame", children: [_jsx("img", { className: "target-preview", src: config.targetImageSrc, alt: "Target", crossOrigin: "anonymous" }), _jsx("div", { className: "scanning-line" })] }), _jsx("p", { className: "scanning-text", children: "Apunta a la imagen para comenzar" })] }) })), showErrorOverlay && status === "error" && (_jsx("div", { className: "taptapp-ar-overlay taptapp-ar-error", children: _jsxs("div", { className: "error-content", children: [_jsx("span", { className: "error-icon", children: "\u26A0\uFE0F" }), _jsx("p", { className: "error-title", children: "No se pudo iniciar AR" }), _jsx("p", { className: "error-text", children: "Verifica los permisos de c\u00E1mara" }), _jsx("button", { className: "retry-btn", onClick: () => window.location.reload(), children: "Reintentar" })] }) })), _jsx("div", { ref: containerRef, className: "taptapp-ar-container", onClick: toggleVideo, style: { width: '100%', height: '100%' }, children: isVideo ? (_jsx("video", { ref: overlayRef, className: "taptapp-ar-overlay-element", src: config.videoSrc, preload: "auto", loop: true, playsInline: true, muted: true, crossOrigin: "anonymous" })) : (_jsx("img", { ref: overlayRef, className: "taptapp-ar-overlay-element", src: config.videoSrc || config.targetImageSrc, crossOrigin: "anonymous", alt: "AR Overlay" })) }), trackedPoints.length > 0 && (_jsx("div", { className: "taptapp-ar-points-overlay", style: { opacity: status === "tracking" ? 1 : 0.6 }, children: trackedPoints
+    return (_jsxs("div", { className: `taptapp-ar-wrapper ${className} ${status}`, style: { position: 'relative', width: '100%', height: '100%', overflow: 'hidden' }, children: [showScanningOverlay && status === "scanning" && (_jsx("div", { className: "taptapp-ar-overlay taptapp-ar-scanning", children: _jsxs("div", { className: "scanning-content", children: [_jsxs("div", { className: "scanning-frame", children: [_jsx("img", { className: "target-preview", src: config.targetImageSrc, alt: "Target", crossOrigin: "anonymous" }), _jsx("div", { className: "scanning-line" })] }), _jsx("p", { className: "scanning-text", children: "Apunta a la imagen para comenzar" })] }) })), status === "compiling" && (_jsx("div", { className: "taptapp-ar-overlay taptapp-ar-compiling", style: { background: 'rgba(0,0,0,0.9)' }, children: _jsxs("div", { className: "scanning-content", children: [_jsx("div", { className: "loading-spinner" }), _jsx("p", { className: "scanning-text", style: { marginTop: '20px' }, children: "Preparando motor AR..." }), _jsx("p", { style: { fontSize: '0.8rem', opacity: 0.6 }, children: "Compilando imagen de referencia" })] }) })), showErrorOverlay && status === "error" && (_jsx("div", { className: "taptapp-ar-overlay taptapp-ar-error", children: _jsxs("div", { className: "error-content", children: [_jsx("span", { className: "error-icon", children: "\u26A0\uFE0F" }), _jsx("p", { className: "error-title", children: "No se pudo iniciar AR" }), _jsx("p", { className: "error-text", children: error || "Verifica los permisos de cámara" }), _jsx("button", { className: "retry-btn", onClick: () => window.location.reload(), children: "Reintentar" })] }) })), _jsx("div", { ref: containerRef, className: "taptapp-ar-container", onClick: toggleVideo, style: { width: '100%', height: '100%' }, children: isVideo ? (_jsx("video", { ref: overlayRef, className: "taptapp-ar-overlay-element", src: config.videoSrc, preload: "auto", loop: true, playsInline: true, muted: true, crossOrigin: "anonymous" })) : (_jsx("img", { ref: overlayRef, className: "taptapp-ar-overlay-element", src: config.videoSrc || config.targetImageSrc, crossOrigin: "anonymous", alt: "AR Overlay" })) }), trackedPoints.length > 0 && (_jsx("div", { className: "taptapp-ar-points-overlay", style: { opacity: status === "tracking" ? 1 : 0.6 }, children: trackedPoints
                     .map((point, i) => {
                     // 🚀 Reflex visualization of the engine's new sensitivity
                     const isStable = point.stability > 0.3 && point.reliability > 0.2;
@@ -89,6 +89,17 @@ export const TaptappAR = ({ config, className = "", showScanningOverlay = true,
                     font-weight: 500;
                     letter-spacing: 0.5px;
                 }
+                .loading-spinner {
+                    width: 40px;
+                    height: 40px;
+                    border: 3px solid rgba(255,255,255,0.1);
+                    border-radius: 50%;
+                    border-top-color: #00e5ff;
+                    animation: spin 1s ease-in-out infinite;
+                }
+                @keyframes spin {
+                    to { transform: rotate(360deg); }
+                }
                 .error-icon { font-size: 3rem; margin-bottom: 10px; }
                 .error-title { font-size: 1.2rem; font-weight: bold; margin: 0; }
                 .error-text { opacity: 0.8; margin: 5px 0 20px; }
@@ -104,12 +115,15 @@ export const TaptappAR = ({ config, className = "", showScanningOverlay = true,
                 }
                 .retry-btn:active { transform: scale(0.95); }
                 .taptapp-ar-overlay-element {
-                    display: block;
-                    width: 100%;
+                    display: none; /* Controlled by tracker */
+                    position: absolute;
+                    top: 0;
+                    left: 0;
+                    width: auto;
                     height: auto;
-                    opacity: 0;
                     pointer-events: none;
-                    transition: opacity 0.3s ease;
+                    z-index: 10;
+                    /* Will be positioned via matrix3d by track.ts */
                 }
                 .taptapp-ar-points-overlay {
                     position: absolute;

package/dist/react/types.d.ts

@@ -1,7 +1,7 @@
 export interface ARConfig {
     cardId: string;
     targetImageSrc: string;
-    targetTaarSrc: string;
+    targetTaarSrc?: string;
     videoSrc: string;
     videoWidth: number;
     videoHeight: number;

package/dist/react/use-ar.d.ts

@@ -1,5 +1,5 @@
 import type { ARConfig } from "./types.js";
-export type ARStatus = "scanning" | "tracking" | "error";
+export type ARStatus = "compiling" | "scanning" | "tracking" | "error";
 export interface TrackedPoint {
     x: number;
     y: number;
@@ -13,5 +13,6 @@ export interface UseARReturn {
     isPlaying: boolean;
     toggleVideo: () => Promise<void>;
     trackedPoints: TrackedPoint[];
+    error: string | null;
 }
 export declare const useAR: (config: ARConfig) => UseARReturn;

package/dist/react/use-ar.js

@@ -5,6 +5,7 @@ export const useAR = (config) => {
     const [status, setStatus] = useState("scanning");
     const [isPlaying, setIsPlaying] = useState(false);
     const [trackedPoints, setTrackedPoints] = useState([]);
+    const [error, setError] = useState(null);
     const arInstanceRef = useRef(null);
     const toggleVideo = useCallback(async () => {
         const overlay = overlayRef.current;
@@ -31,65 +32,70 @@ export const useAR = (config) => {
         const initAR = async () => {
             try {
                 // Safe hybrid import for SSR + Speed
-                const { SimpleAR } = await import("../runtime/simple-ar.js");
+                const { createTracker } = await import("../runtime/track.js");
                 if (!isMounted)
                     return;
-                const instance = new SimpleAR({
+                setStatus("compiling");
+                const instance = await createTracker({
                     container: containerRef.current,
-                    targetSrc: config.targetTaarSrc,
+                    targetSrc: config.targetTaarSrc || config.targetImageSrc,
                     overlay: overlayRef.current,
                     scale: config.scale,
-                    debug: false,
-                    onUpdate: (data) => {
-                        const { screenCoords, reliabilities, stabilities } = data;
-                        if (screenCoords && reliabilities && stabilities) {
-                            const points = screenCoords.map((p, i) => ({
-                                x: p.x,
-                                y: p.y,
-                                reliability: reliabilities[i],
-                                stability: stabilities[i]
-                            }));
-                            setTrackedPoints(points);
-                        }
-                    },
-                    onFound: async ({ targetIndex }) => {
-                        console.log(`🎯 Target ${targetIndex} detected!`);
-                        if (!isMounted)
-                            return;
-                        setStatus("tracking");
-                        const overlay = overlayRef.current;
-                        if (overlay instanceof HTMLVideoElement) {
-                            try {
-                                await overlay.play();
-                                setIsPlaying(true);
+                    debugMode: false,
+                    callbacks: {
+                        onUpdate: (data) => {
+                            const { screenCoords, reliabilities, stabilities } = data;
+                            if (screenCoords && reliabilities && stabilities) {
+                                const points = screenCoords.map((p, i) => ({
+                                    x: p.x,
+                                    y: p.y,
+                                    reliability: reliabilities[i],
+                                    stability: stabilities[i]
+                                }));
+                                setTrackedPoints(points);
                             }
-                            catch (err) {
-                                console.warn("Auto-play blocked:", err);
+                        },
+                        onFound: async ({ targetIndex }) => {
+                            console.log(`🎯 Target ${targetIndex} detected!`);
+                            if (!isMounted)
+                                return;
+                            setStatus("tracking");
+                            const overlay = overlayRef.current;
+                            if (overlay instanceof HTMLVideoElement) {
+                                try {
+                                    await overlay.play();
+                                    setIsPlaying(true);
+                                }
+                                catch (err) {
+                                    console.warn("Auto-play blocked:", err);
+                                }
+                            }
+                        },
+                        onLost: ({ targetIndex }) => {
+                            console.log(`👋 Target ${targetIndex} lost`);
+                            if (!isMounted)
+                                return;
+                            setStatus("scanning");
+                            setTrackedPoints([]);
+                            const overlay = overlayRef.current;
+                            if (overlay instanceof HTMLVideoElement) {
+                                overlay.pause();
+                                setIsPlaying(false);
                             }
-                        }
-                    },
-                    onLost: ({ targetIndex }) => {
-                        console.log(`👋 Target ${targetIndex} lost`);
-                        if (!isMounted)
-                            return;
-                        setStatus("scanning");
-                        setTrackedPoints([]);
-                        const overlay = overlayRef.current;
-                        if (overlay instanceof HTMLVideoElement) {
-                            overlay.pause();
-                            setIsPlaying(false);
                         }
                     }
                 });
                 arInstanceRef.current = instance;
-                await instance.start();
+                await instance.startCamera();
                 if (isMounted)
                     setStatus("scanning");
             }
             catch (err) {
-                console.error("Failed to initialize AR:", err);
-                if (isMounted)
+                console.error("❌ [TapTapp AR] Error durante la inicialización:", err);
+                if (isMounted) {
+                    setError(err.message || String(err));
                     setStatus("error");
+                }
             }
         };
         initAR();
@@ -98,13 +104,14 @@ export const useAR = (config) => {
             arInstanceRef.current?.stop();
             arInstanceRef.current = null;
         };
-    }, [config.targetTaarSrc, config.scale]);
+    }, [config.targetTaarSrc, config.targetImageSrc, config.scale]);
     return {
         containerRef,
         overlayRef,
         status,
         isPlaying,
         toggleVideo,
-        trackedPoints
+        trackedPoints,
+        error
     };
 };

package/dist/runtime/index.d.ts

@@ -1,4 +1,5 @@
 export * from "./controller.js";
-export * from "./simple-ar.js";
+export * from "./bio-inspired-controller.js";
+export * from "./track.js";
 export * from "./three.js";
 export * from "./aframe.js";

package/dist/runtime/index.js

@@ -1,4 +1,5 @@
 export * from "./controller.js";
-export * from "./simple-ar.js";
+export * from "./bio-inspired-controller.js";
+export * from "./track.js";
 export * from "./three.js";
 export * from "./aframe.js";