Wikitude SDK API Reference

API Docs for: 9.10.0
Show:

InstantTracker Class

Extends ARchitectObject
Module: AR

An InstantTracker represents the instant tracking algorithm. It does not require any pre-existing target information, but can immediately start tracking. Minimally it can be instantiated without any parameters.

Trackers can be enabled and disabled. Only one Tracker can be active at a time. The current enabled/disabled state of a Tracker is reflected in the enabled property. Should there be multiple Trackers used in the ARchitect file, the following logic applies to specify the currently active Tracker:

  • When a new Tracker is created, it is automatically set to the active one, unless it was created with enabled set to false.
  • When a specific Tracker is enabled, it is automatically set to the active one. The previously active Tracker is disabled by the system.
In case a Tracker is disabled by the system, the developer will be notified via the onDisabled trigger.

Instant tracking minimal example:

this.tracker = new AR.InstantTracker();

Instant tracking example:

this.tracker = new AR.InstantTracker({
    onChangedState:  function onChangedStateFn(state) {
        // react to a change in tracking state here
    },
    // device height needs to be as accurate as possible to have an accurate scale
    // returned by the Wikitude SDK
    deviceHeight: 1.0,

 // The initial orientation at which the instant tracking plane should be displayed in degrees.
 // Default value is AR.CONST.INITIAL_INSTANT_TRACKING_PLANE_ORIENTATION.HORIZONTAL (0°).
    trackingPlaneOrientation: 45.0
});

Constructor

InstantTracker

(
  • options
)

Parameters:

  • options Object optional

    Setup-Parameters to customize additional object properties.

    Accepted options-properties are

    • enabled (defaults to true) Boolean optional
    • onError (defaults to undefined) Function optional
    • onDisabled (defaults to undefined) Function optional
    • onChangedState (defaults to undefined) Function optional
    • deviceHeight (defaults to 1.0) Number optional

      The device height above ground in meters used in the scale estimation of the instant tracking algorithm

    • trackingPlaneOrientation (defaults to AR.CONST.INITIAL_INSTANT_TRACKING_PLANE_ORIENTATION.HORIZONTAL) Number optional

      Is not supported with smartEnabled being true.

    • smartEnabled (defaults to true) Boolean optional

      Defines if SMART should be used.

    • trackerEfficiencyMode (defaults to AR.CONST.TRACKER_EFFICIENCY_MODE.HIGH_ACCURACY) Number optional

      The efficiency mode in which the image tracker should run. Please refer to the AR.CONST.TRACKER_EFFICIENCY_MODE documentation for more information.

Methods

destroy

()

Inherited from ARchitectObject

Destroys the object.

loadExistingInstantTarget

(
  • targetCollectionResource
  • completionHandler
  • errorHandler
  • options
)

Loads the provided instant target and starts tracking it.

This feature is not available with platform assisted tracking enabled.

e.g.:

instantTracker.saveCurrentInstantTarget(url, function () {}, function (error) {});

...

var mapResource = new AR.TargetCollectionResource(url);

instantTracker.loadExistingInstantTarget(mapResource, function () {}, function (error) {});

Parameters:

  • targetCollectionResource AR.TargetCollectionResource

    The resource representing the instant target that should be loaded.

  • completionHandler Function

    The callback that is invoked when the map was successfully loaded.

  • errorHandler Function

    The callback that is invoked when loading the map was not possible. It will provide an AR.Error describing the issue.

  • options Object optional

    Configuration for the behaviour of loaded instant targets.

    Accepted options-properties are

    • expansionPolicy (defaults to DISALLOW_EXPANSION) AR.CONST.INSTANT_TARGET_EXPANSION_POLICY optional

      When expansion is allowed the tracker will expand the instant target if areas that were not in the camera frame when saving are detected.

saveCurrentInstantTarget

(
  • uri
  • completionHandler
  • errorHandler
)

Saves the current scene created by the InstantTracker. The saved file can then be loaded as TargetCollectionResource using loadExistingInstantTarget.

This enables that AR experiences can be persistently accessed by multiple users across devices and operating systems.

This feature is not available with platform assisted tracking enabled.

e.g.:

instantTracker.saveCurrentInstantTarget(url, function () {}, function (error) {});

...

var mapResource = new AR.TargetCollectionResource(url);

instantTracker.loadExistingInstantTarget(mapResource, function () {}, function (error) {});

Parameters:

  • uri String

    The uri where the map should be saved to.

  • completionHandler Function

    The callback that is invoked when the map was successfully saved.

  • errorHandler Function

    The callback that is invoked when saving the map was not possible. It will provide an AR.Error describing the issue.

Properties

canStartTracking

Boolean

Check whether the state can be switched from AR.InstantTrackerState.INITIALIZING to AR.InstantTrackerState.TRACKING. Currently, this property always returns true if Wikitude's instant tracking is used. When using platform assisted tracking, however, the initialization thereof may take a while, now allowing tracking to be started immediately.

destroyed

Boolean

Inherited from ARchitectObject

Indicates if the object has already been destroyed.

deviceHeight

Number

The device height used in the scale estimation of the instant tracking algorithm in meters.

enabled

Boolean

The current activity state of the Tracker. This property might by changed automatically by the system, in case another Tracker is enabled, causing this Tracker to be disabled. The onDisabled trigger will be called in this case.

state

Number

The current internal state of the Tracker. Can either be AR.InstantTrackerState.INITIALIZING or AR.InstantTrackerState.TRACKING.

trackingPlaneOrientation

Number

The initial orientation at which the instant tracking plane should be displayed in degrees.

Default values is AR.CONST.INITIAL_INSTANT_TRACKING_PLANE_ORIENTATION.HORIZONTAL (0°)

This setting is not used when running InstantTracking with platform assisted tracking.

Events

onChangedState

The trigger fires when the Tracker changes its internal state.

The trigger is null by default, and will thus result in no action executed when the trigger fires. A developer can add custom functionality by assigning a custom function to onChangedState.

onDisabled

The trigger fires when the Tracker has been disabled by the system. It does not fire when enabled is set to false manually.

The trigger is null by default, and will thus result in no action executed when the trigger fires. A developer can add custom functionality by assigning a custom function to onDisabled.

onError

The trigger fires for any Tracker errors.

The trigger is null by default, and will thus result in no action executed when the trigger fires. A developer can add custom functionality by assigning a custom function to onError.

Event Payload:

  • AR.Error Object

    object containing details of the error.