@srsergio/taptapp-ar 1.0.52 → 1.0.53

package/README.md

@@ -136,8 +136,73 @@ ar.stop();
 
 ---
 
-### 📚 Advanced Usage
-For **A-Frame**, **Three.js**, or **Raw Controller** usage, please refer to the [Advanced Usage Documentation](./docs/advanced-usage.md).
+### 2. 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.
+
+#### ⚙️ 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:
+
+```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.`);
+      }
+    }
+  }
+});
+
+// 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
+```
+
+#### 📸 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
+}
+```
+
+### 📚 Legacy Usage
+For **A-Frame** or **Three.js** wrappers, please refer to the [Advanced Usage Documentation](./docs/advanced-usage.md).
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@srsergio/taptapp-ar",
-    "version": "1.0.52",
+    "version": "1.0.53",
     "description": "Ultra-fast, lightweight Augmented Reality Image Tracking SDK for the web. Features an optimized offline compiler, React components, and compatibility with Three.js/A-Frame. No heavy ML frameworks required.",
     "keywords": [
         "web-ar",