Class WebXRImageTrackingModel

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

See

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

Constructors

constructor

Properties

createObjectInstance hideWhenTrackingIsLost image? imageDoesNotMove object? widthInMeters

Methods

getNameFromUrl

Constructors

constructor

  • new WebXRImageTrackingModel(
        params: {
            createObjectInstance?: boolean;
            hideWhenTrackingIsLost?: boolean;
            imageDoesNotMove?: boolean;
            object: Object3D<Object3DEventMap> | AssetReference;
            url: string;
            widthInMeters: number;
        },
    ): WebXRImageTrackingModel

    Creates a new image tracking configuration.

    Parameters

    • params: {
          createObjectInstance?: boolean;
          hideWhenTrackingIsLost?: boolean;
          imageDoesNotMove?: boolean;
          object: Object3D<Object3DEventMap> | AssetReference;
          url: string;
          widthInMeters: number;
      }

      Configuration parameters

      • OptionalcreateObjectInstance?: boolean

        If true, creates a new instance for each detection (useful for tracking multiple instances of the same marker)

      • OptionalhideWhenTrackingIsLost?: boolean

        If true, hides the object when tracking is lost; if false, leaves it at the last known position

      • OptionalimageDoesNotMove?: boolean

        Enable for static markers (floor/wall mounted) to improve tracking stability

      • object: Object3D<Object3DEventMap> | AssetReference

        The 3D object or AssetReference to display when this image is detected

      • url: string

        URL to the marker image to track

      • widthInMeters: number

        Physical width of the printed marker in meters (must match real size!)

    Returns WebXRImageTrackingModel

Properties

createObjectInstance

createObjectInstance: boolean = false

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

hideWhenTrackingIsLost

hideWhenTrackingIsLost: boolean = true

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

Optionalimage

image?: string

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.

imageDoesNotMove

imageDoesNotMove: boolean = false

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

Optionalobject

object?: AssetReference

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.

widthInMeters

widthInMeters: number = .25

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

// For a business card sized marker (9cm wide)
widthInMeters = 0.09;

// For an A4 page width (21cm)
widthInMeters = 0.21;

Methods

getNameFromUrl

  • getNameFromUrl(): null | string

    Extracts the filename from the marker image URL.

    Returns null | string

    The filename (last part of the URL path), or null if no image URL is set

    Example

    // URL: "https://example.com/markers/business-card.png"
    // Returns: "business-card.png"

Settings

Member Visibility

On This Page

Constructors
Properties
Methods