@needle-tools/engine 4.13.0 → 4.13.1-beta

package/src/engine-components/webxr/WebXRImageTracking.ts

@@ -20,29 +20,70 @@ const debug = getParam("debugimagetracking");
 
 // #region WebXRTrackedImage
 
+/**
+ * Represents a tracked image detected during a WebXR session.
+ * Contains position, rotation, and tracking state information for a detected marker image.
+ *
+ * **Properties:**
+ * - Access image URL and physical dimensions
+ * - Get current position and rotation in world space
+ * - Check tracking state (tracked vs emulated)
+ * - Apply transform to 3D objects
+ *
+ * @summary Runtime data for a detected marker image in WebXR
+ * @category XR
+ */
 export class WebXRTrackedImage {
 
+    /** URL of the tracked marker image */
     get url(): string { return this._trackedImage.image ?? ""; }
+    /** Physical width of the marker in meters */
     get widthInMeters() { return this._trackedImage.widthInMeters ?? undefined; }
+    /** The ImageBitmap used for tracking */
     get bitmap(): ImageBitmap { return this._bitmap; }
+    /** The {@link WebXRImageTrackingModel} configuration for this tracked image */
     get model(): WebXRImageTrackingModel { return this._trackedImage; }
+    /**
+     * The measured size of the detected image in the real world.
+     * May differ from `widthInMeters` if the physical marker doesn't match the configured size.
+     */
     readonly measuredSize: number;
+    /**
+     * Current tracking state of the image:
+     * - `tracked` - Image is currently being tracked by the system
+     * - `emulated` - Tracking is being emulated (less accurate)
+     */
     readonly state: "tracked" | "emulated";
 
-    /** Copy the image position to a vector */
+    /**
+     * Copy the current world position of the tracked image to a Vector3.
+     * @param vec The vector to store the position in
+     * @returns The input vector with the position copied to it
+     */
     getPosition(vec: Vector3) {
         this.ensureTransformData();
         vec.copy(this._position);
         return vec;
     }
 
-    /** Copy the image rotation to a quaternion */
+    /**
+     * Copy the current world rotation of the tracked image to a Quaternion.
+     * @param quat The quaternion to store the rotation in
+     * @returns The input quaternion with the rotation copied to it
+     */
     getQuaternion(quat: Quaternion) {
         this.ensureTransformData();
         quat.copy(this._rotation);
         return quat;
     }
 
+    /**
+     * Apply the tracked image's position and rotation to a 3D object.
+     * Optionally applies smoothing to reduce jitter.
+     *
+     * @param object The 3D object to update
+     * @param t01 Interpolation factor (0-1) for smoothing. If undefined or >= 1, no smoothing is applied. When smoothing is enabled, larger position/rotation changes will automatically reduce the smoothing to prevent lag.
+     */
     applyToObject(object: Object3D, t01: number | undefined = undefined) {
         this.ensureTransformData();
         // check if position/_position or rotation/_rotation changed more than just a little bit and adjust smoothing accordingly
@@ -92,14 +133,22 @@ export class WebXRTrackedImage {
 
 }
 
+/**
+ * Event callback type for image tracking updates.
+ * @param images Array of currently tracked images
+ */
 declare type WebXRImageTrackingEvent = (images: WebXRImageTrackingEvent[]) => void;
 
-/** Initial state of assigned tracked image objects that are already present in the scene
- * This is used to restore the state of the object when the webxr session has ended to return to the original state
+/**
+ * Initial state of tracked image objects before entering an XR session.
+ * Used to restore objects to their original state when the WebXR session ends.
  */
 declare type InitialTrackedObjectState = {
+    /** Original visibility state */
     visible: boolean;
+    /** Original parent object in the scene hierarchy */
     parent: Object3D | undefined | null;
+    /** Original transformation matrix */
     matrix: Matrix4;
 }
 
@@ -107,13 +156,37 @@ declare type InitialTrackedObjectState = {
 // #region Model
 
 /**
- * WebXRImageTracking allows you to track images in the real world and place objects on top of them.  
- * This component is only available in WebXR sessions.  
- * The WebXRImageTrackingModel contains the image to track, the object to place on top of the image, and the size of the image as well as settings for the tracking.  
- * Used by the {@link WebXRImageTracking} component
+ * Configuration model for a tracked image marker.
+ * Defines which image to track, its physical size, and which 3D content to display when detected.
+ *
+ * **Important:** The physical size (`widthInMeters`) must match your printed marker size for accurate tracking.
+ * Mismatched sizes cause the tracked object to appear to "float" above or below the marker.
+ *
+ * **Best practices for marker images:**
+ * - Use high-contrast images with distinct features
+ * - Avoid repetitive patterns or solid colors
+ * - Test images at intended viewing distances
+ * - Ensure good lighting conditions
+ *
+ * @summary Configuration for a single trackable image marker
+ * @category XR
+ * @see {@link WebXRImageTracking} for the component that uses these models
+ * @link https://engine.needle.tools/docs/xr.html#image-tracking
+ * @link https://engine.needle.tools/samples/image-tracking
  */
 export class WebXRImageTrackingModel {
 
+    /**
+     * Creates a new image tracking configuration.
+     *
+     * @param params Configuration parameters
+     * @param params.url URL to the marker image to track
+     * @param params.widthInMeters Physical width of the printed marker in meters (must match real size!)
+     * @param params.object The 3D object or AssetReference to display when this image is detected
+     * @param params.createObjectInstance If true, creates a new instance for each detection (useful for tracking multiple instances of the same marker)
+     * @param params.imageDoesNotMove Enable for static markers (floor/wall mounted) to improve tracking stability
+     * @param params.hideWhenTrackingIsLost If true, hides the object when tracking is lost; if false, leaves it at the last known position
+     */
     constructor(params: { url: string, widthInMeters: number, /** Object to track */ object: AssetReference | Object3D, createObjectInstance?: boolean, imageDoesNotMove?: boolean, hideWhenTrackingIsLost?: boolean }) {
         this.image = params.url;
         this.widthInMeters = params.widthInMeters;
@@ -121,44 +194,81 @@ export class WebXRImageTrackingModel {
             this.object = new AssetReference({ asset: params.object });
         }
         else this.object = params.object;
-        
+
         if (params.createObjectInstance !== undefined) this.createObjectInstance = params.createObjectInstance;
         if (params.imageDoesNotMove !== undefined) this.imageDoesNotMove = params.imageDoesNotMove;
         if (params.hideWhenTrackingIsLost !== undefined) this.hideWhenTrackingIsLost = params.hideWhenTrackingIsLost;
     }
 
     /**
-     * Tracked image marker url. Make sure the image has good contrast and unique features to improve the tracking quality.
+     * URL to the marker image to track.
+     * **Important:** Use images with high contrast and unique features to improve tracking quality.
+     * Avoid repetitive patterns, solid colors, or low-contrast images.
      */
     @serializable(URL)
     image?: string;
 
-    /** Make sure this matches your physical marker size! Otherwise the tracked object will \"swim\" above or below the marker. 
-     * @default 0.25 which is equivalent to 25cm
+    /**
+     * Physical width of the printed marker in meters.
+     * **Critical:** This must match your actual printed marker size!
+     * If mismatched, the tracked object will appear to "float" above or below the marker.
+     *
+     * @default 0.25 (25cm)
+     * @example
+     * ```ts
+     * // For a business card sized marker (9cm wide)
+     * widthInMeters = 0.09;
+     *
+     * // For an A4 page width (21cm)
+     * widthInMeters = 0.21;
+     * ```
     */
     @serializable()
     widthInMeters: number = .25;
 
     /**
-     * The object moved around by the image. Make sure the size matches WidthInMeters.
+     * The 3D object or prefab to display when this marker is detected.
+     * The object will be positioned and rotated to match the tracked image in the real world.
+     *
+     * **Note:** Scale your 3D content appropriately relative to `widthInMeters`.
      */
     @serializable(AssetReference)
     object?: AssetReference;
 
     /**
-     * If true, a new instance of the referenced object will be created for each tracked image. Enable this if you're re-using objects for multiple markers.
+     * When enabled, creates a new instance of the referenced object each time this image is detected.
+     * Enable this if you want to track multiple instances of the same marker simultaneously,
+     * or if the same object is used for multiple different markers.
+     *
+     * @default false
      */
     @serializable()
     createObjectInstance: boolean = false;
 
-    /** Use this for static images (e.g. markers on the floor). Only the first few frames of new poses will be applied to the model. This will result in more stable tracking. 
+    /**
+     * Enable for static markers that don't move (e.g., posters on walls or markers on the floor).
+     * When enabled, only the first few tracking frames are used to position the object,
+     * resulting in more stable tracking by ignoring subsequent minor position changes.
+     *
+     * **Use cases:**
+     * - Wall-mounted posters or artwork
+     * - Floor markers for persistent AR content
+     * - Product packaging on shelves
+     *
+     * **Don't use for:**
+     * - Handheld cards or objects
+     * - Moving markers
+     *
      * @default false
     */
     @serializable()
     imageDoesNotMove: boolean = false;
 
     /**
-     * Enable to hide the tracked object when the image is not tracked anymore. When disabled the tracked object will stay at the position it was last tracked at.
+     * Controls visibility behavior when tracking is lost.
+     * - When `true`: Object is hidden when the marker is no longer visible
+     * - When `false`: Object remains visible at its last tracked position
+     *
      * @default true
      */
     @serializable()
@@ -166,7 +276,13 @@ export class WebXRImageTrackingModel {
 
 
     /**
-     * Get the name of the image file from the url
+     * Extracts the filename from the marker image URL.
+     * @returns The filename (last part of the URL path), or null if no image URL is set
+     * @example
+     * ```ts
+     * // URL: "https://example.com/markers/business-card.png"
+     * // Returns: "business-card.png"
+     * ```
      */
     getNameFromUrl() {
         if (this.image) {
@@ -299,24 +415,121 @@ class ImageTrackingExtension implements IUSDExporterExtension {
 
 // #region Tracking Component
 /**
- * Add this component to a object to enable image tracking in WebXR sessions.    
- * 
- * You need to add at least one {@link WebXRImageTrackingModel} to the `trackedImages` array to define which images to track and which objects to place on top of them.
+ * Create powerful AR image tracking experiences with just a few lines of code!
+ * WebXRImageTracking makes it incredibly easy to detect marker images in the real world and anchor 3D content to them.
+ * Needle Engine automatically handles all the complexity across different platforms and fallback modes for you.
+ *
+ * [![Image Tracking Demo](https://cloud.needle.tools/-/media/vRUf9BmqW_bgNARATjmfCQ.gif)](https://engine.needle.tools/samples/image-tracking)
+ *
+ * **What makes Needle Engine special:**
+ * - **Write once, run everywhere**: The same code works across iOS, Android, and visionOS
+ * - **Automatic platform optimization**: Seamlessly switches between WebXR, ARKit, and QuickLook
+ * - **Flexible deployment options**: From full WebXR with unlimited markers to QuickLook fallback
+ * - **Production ready**: Battle-tested tracking with adaptive smoothing and stability features
+ *
+ * **Platform Support & Options:**
+ * - **iOS (WebXR via AppClip)**: Full WebXR support - track unlimited markers simultaneously via native ARKit!
+ * - **iOS (QuickLook mode)**: Instant AR without app installation - perfect for quick demos (tracks first marker)
+ * - **Android (WebXR)**: Native WebXR Image Tracking API - unlimited markers (requires browser flag during early access)
+ * - **visionOS (QuickLook)**: Spatial image anchoring with Apple's AR QuickLook
+ *
+ * **Simple 3-Step Setup:**
+ * 1. Add this component to any GameObject in your scene
+ * 2. Configure your markers in the `trackedImages` array:
+ *    - `image`: URL to your marker image
+ *    - `widthInMeters`: Physical size of your printed marker
+ *    - `object`: The 3D content to display
+ * 3. Export and test - Needle handles the rest!  
+ *
+ * **Pro Tips for Best Results:**
+ * - Use high-contrast markers with unique features for reliable tracking
+ * - Match `widthInMeters` to your actual physical marker size for accurate positioning
+ * - Enable `imageDoesNotMove` for wall posters or floor markers - significantly improves stability
+ * - Use `smooth` (enabled by default) for professional-looking, jitter-free tracking
+ * - Test with different marker sizes and lighting - Needle's adaptive tracking handles various conditions  
  * 
- * **NOTE:** For Android devices, image tracking currently requires the user to enable the `chrome://flags/#webxr-incubations` flag in Chrome.  
- * 
- * **NOTE:** For iOS only one image can be tracked at a time. If you have multiple images in the `trackedImages` array, only the first one will be tracked. You can use the {@link setPrimaryImage} method to change which image is tracked before entering the XR session.  
- * 
- * - Example: https://samples.needle.tools/image-tracking
+ * ![](https://cloud.needle.tools/-/media/V-2UxGVRJxvH9oDnXGnIdg.png)  
+ * *WebXRImageTracking component in Unity Editor*  
  * 
+ * ![](https://cloud.needle.tools/-/media/poDPca1bI1an4SBY7LtKNA.png)  
+ * *WebXRImageTracking panel/component in Blender*
+ *
+ * @example Getting started - it's this easy!
+ * ```ts
+ * // Just add markers and Needle handles everything else
+ * const imageTracking = myObject.addComponent(WebXRImageTracking);
+ * const marker = new WebXRImageTrackingModel({
+ *   url: "https://example.com/my-poster.png",
+ *   widthInMeters: 0.3, // 30cm poster
+ *   object: my3DContent
+ * });
+ * imageTracking.addImage(marker);
+ * // Done! Works on iOS, Android, and visionOS automatically
+ * ```
+ *
+ * @example Track multiple markers (WebXR mode)
+ * ```ts
+ * const imageTracking = myObject.addComponent(WebXRImageTracking);
+ *
+ * // In WebXR mode (iOS AppClip, Android), all markers work simultaneously!
+ * const productBox = new WebXRImageTrackingModel({ url: "product-box.png", widthInMeters: 0.15, object: productInfo });
+ * const businessCard = new WebXRImageTrackingModel({ url: "business-card.png", widthInMeters: 0.09, object: contactCard });
+ * const poster = new WebXRImageTrackingModel({ url: "poster.png", widthInMeters: 0.5, object: videoPlayer });
+ *
+ * imageTracking.addImage(productBox);
+ * imageTracking.addImage(businessCard);
+ * imageTracking.addImage(poster);
+ *
+ * // For QuickLook fallback mode, optionally set which marker is primary
+ * imageTracking.setPrimaryImage(poster); // This will be used in QuickLook
+ * ```
+ *
+ * @example Professional setup for static markers
+ * ```ts
+ * // Perfect for museums, retail displays, or permanent installations
+ * const wallArt = new WebXRImageTrackingModel({
+ *   url: "gallery-painting.png",
+ *   widthInMeters: 0.6,
+ *   object: interactiveExplanation,
+ *   imageDoesNotMove: true, // Rock-solid tracking for static markers!
+ *   hideWhenTrackingIsLost: false // Content stays visible even if temporarily occluded
+ * });
+ * ```
+ *
+ * **Why developers love Needle's image tracking:**
+ * - Zero platform-specific code required
+ * - Automatic graceful degradation across deployment modes
+ * - Built-in jitter reduction and stability features
+ * - Works with any image - posters, packaging, business cards, artwork
+ * - Export once, deploy everywhere
+ *
+ * @summary The easiest way to create cross-platform AR image tracking experiences
  * @category XR
  * @group Components
+ * @see {@link WebXRImageTrackingModel} for marker configuration options
+ * @see {@link WebXRTrackedImage} for runtime tracking data and events
+ * @see {@link WebXR} for general WebXR setup and session management
+ * @link https://engine.needle.tools/docs/xr.html#image-tracking - Full Documentation
+ * @link https://engine.needle.tools/samples/image-tracking - Try Live Demo
+ * @link https://github.com/immersive-web/marker-tracking/blob/main/explainer.md - WebXR Marker Tracking Specification
  */
 export class WebXRImageTracking extends Behaviour {
 
     /**
-     * If you have multiple images in your application to track then this method is useful for iOS AR where only the first image can be tracked.   
-     * Call this method will set the given image as the first one in the array so it will be used for tracking.
+     * Set which marker should be primary (first in the list).
+     * Useful when deploying to QuickLook mode where one marker is tracked at a time.
+     * In full WebXR mode (iOS AppClip, Android), all markers track simultaneously regardless of order.
+     *
+     * **Note:** Needle Engine automatically adapts - in WebXR all markers work, in QuickLook the primary is used.
+     *
+     * @param image The marker model to set as primary
+     *
+     * @example
+     * ```ts
+     * // Great for offering different AR experiences from one deployment
+     * imageTracking.setPrimaryImage(businessCardMarker); // Use this for QuickLook
+     * // In WebXR mode, all markers still work simultaneously!
+     * ```
      */
     setPrimaryImage(image: WebXRImageTrackingModel) {
         const index = this.trackedImages.indexOf(image);
@@ -331,14 +544,25 @@ export class WebXRImageTracking extends Behaviour {
     }
 
     /**
-     * Add an image to track. If the image is already in the trackedImages array it won't be added again.  
-     * Note: that adding images at runtime *while* in AR is not supported.  
-     * 
+     * Add a marker to track - it's that simple!
+     * Needle Engine handles all the platform differences automatically.
+     *
+     * **Tip:** Add all your markers upfront. In WebXR mode they all work simultaneously.
+     * In QuickLook mode, the first (primary) marker is used.
+     *
+     * @param image The marker configuration to add
+     * @param asPrimary Set to true to make this the primary marker (for QuickLook fallback)
+     *
      * @example
      * ```ts
-     * const imageTracking = GameObject.getComponent(myGameObject, WebXRImageTracking);
-     * const image = new WebXRImageTrackingModel({ url: "https://example.com/my-marker.png", widthInMeters: 0.2, object: myObject });
-     * imageTracking.addImage(image, true); // add and set as primary image
+     * // Super simple - works across all platforms
+     * const marker = new WebXRImageTrackingModel({
+     *   url: "https://mysite.com/poster.png",
+     *   widthInMeters: 0.42, // A3 poster width
+     *   object: cool3DModel
+     * });
+     * imageTracking.addImage(marker);
+     * // That's it! Needle does the rest.
      * ```
      */
     addImage(image: WebXRImageTrackingModel, asPrimary: boolean = false) {
@@ -351,20 +575,40 @@ export class WebXRImageTracking extends Behaviour {
 
 
     /**
-     * List of images to track in the WebXR session. Use {@link WebXRImageTrackingModel} to define each image and the object to place on top of it.  
-     * 
-     * Use the `addImage()` and `setPrimaryImage()` methods to modify this array at runtime.
+     * Your list of markers to track. Add as many as you need!
+     *
+     * **How it works across platforms:**
+     * - **WebXR mode** (iOS AppClip, Android): All markers are tracked simultaneously - amazing for multi-marker experiences!
+     * - **QuickLook mode** (iOS fallback, visionOS): First marker is used - perfect for quick demos without app installation
+     *
+     * **Needle's smart deployment:** Configure all your markers once, and Needle automatically uses the best
+     * tracking mode available on each platform. No platform-specific code needed!
+     *
+     * @see {@link WebXRImageTrackingModel} for marker configuration
+     * @see {@link addImage} and {@link setPrimaryImage} for runtime management
      */
     @serializable(WebXRImageTrackingModel)
     readonly trackedImages: WebXRImageTrackingModel[] = [];
 
-    /** Applies smoothing based on detected jitter to the tracked image. */
+    /**
+     * Enable Needle's professional-grade adaptive smoothing for rock-solid tracking.
+     * Automatically reduces jitter while staying responsive to real movement.
+     *
+     * **Pro tip:** Keep this enabled (default) for production experiences!
+     *
+     * @default true
+     */
     @serializable()
     smooth: boolean = true;
 
     private readonly trackedImageIndexMap: Map<number, WebXRImageTrackingModel> = new Map();
 
-    /** @returns true if image tracking is supported on this device. This may return false at runtime if the user's browser did not enable webxr incubations */
+    /**
+     * Check if image tracking is available on this device right now.
+     *
+     * **Note:** On Android Chrome, WebXR Image Tracking is currently behind a flag during the early access period.
+     * Needle automatically falls back to other modes when needed, so your experience keeps working!
+     */
     get supported() { return this._supported; }
 
     private _supported: boolean = true;

package/src/engine-components/webxr/WebXRPlaneTracking.ts

@@ -48,7 +48,7 @@ export declare type WebXRPlaneTrackingEvent = {
 }
 
 /**
- * Use this component to track planes and meshes in the real world when in immersive-ar (e.g. on Oculus Quest).
+ * [WebXRPlaneTracking](https://engine.needle.tools/docs/api/WebXRPlaneTracking) tracks planes and meshes in the real world when in immersive-ar (e.g. on Oculus Quest).
  * @category XR
  * @group Components
  */

package/src/engine-components/webxr/XRFlag.ts

@@ -61,12 +61,39 @@ export class XRState {
 }
 
 /**
- * Use the XRFlag component to show or hide objects based on the current XR state or session.   
- * This means you can show or hide objects based on if the user is in VR, AR, using first person view or third person view.
- * 
+ * XRFlag shows or hides GameObjects based on the current XR state or session.  
+ * Use for XR-responsive content that should only appear in specific modes.  
+ *
+ * **XR states:**  
+ * - `Browser` - Normal web browsing (no XR)  
+ * - `AR` - Augmented reality session  
+ * - `VR` - Virtual reality session  
+ * - `FirstPerson` - First-person view mode  
+ * - `ThirdPerson` - Third-person/spectator view mode
+ * - Combine with bitwise OR: `AR | VR`
+ *
+ * **Debug options:**  
+ * - `?debugxrflags` - Log flag changes
+ * - `?disablexrflags` - Disable all XR flags
+ *
+ * @example Show only in VR
+ * ```ts
+ * const flag = myObject.addComponent(XRFlag);
+ * flag.visibleIn = XRStateFlag.VR;
+ * ```
+ *
+ * @example Show in AR and VR, hide in browser
+ * ```ts
+ * flag.visibleIn = XRStateFlag.AR | XRStateFlag.VR;
+ * ```
+ *
  * @category XR
  * @category Utilities
  * @group Components
+ * @see {@link XRStateFlag} for state options
+ * @see {@link XRState} for global state management
+ * @see {@link DeviceFlag} for device-based visibility
+ * @see {@link WebXR} for XR session management
  */
 export class XRFlag extends Behaviour {