Wikitude SDK API Reference

API Docs for: 7.0.0
Show:

InstantTrackable Class

Extends ARObject
Module: AR

An InstantTrackable represents a virtual object bound to an Instant Tracker. Drawable augmentations can be attached thereto, causing them to receive the appropriate transformations to be rendered while initializing and tracking. An InstantTrackable also represents a tracking plane and a means of interacting with it.

An InstantTrackable

  • can have Drawables associated with it. These Drawables will represent the InstantTrackable in the camera view.
  • can have triggers associated with it. Triggers fire on certain events and execute functions to react on these actions.
  • can receive touch and click user input

When creating an InstantTrackable, the only parameter strictly required to be passed is an InstantTracker. Practically, however, drawable augmentations for the initialization phase as well as the tracking phase are also required for a majority of practical use cases. Additionally, callbacks can be registered that will be invoked under specific circumstances.

Example:
this.instantTrackable = new AR.InstantTrackable(this.tracker, {
    drawables: {
        cam: aDrawable,
        initialization: anotherDrawable
    },
    onTrackingStarted: function onTrackingStartedFn() {
        // do something when tracking is started (recognized)
    },
    onTrackingStopped: function onTrackingStoppedFn() {
        // do something when tracking is stopped (lost)
    }
});

Constructor

InstantTrackable

(
  • tracker
  • options
)

Parameters:

  • tracker InstantTracker

    The instant tracker providing transformations

  • options Object optional

    Setup-Parameters to customize additional object properties.

    Accepted options-properties are

    • enabled (defaults to true) Boolean optional
    • renderingOrder (defaults to 0) Number optional
    • drawables.cam Drawable[] optional
    • onClick Function optional
    • onDragBegan Function optional
    • onDragChanged Function optional
    • onDragEnded Function optional
    • onPanBegan Function optional
    • onPanChanged Function optional
    • onPanEnded Function optional
    • onRotationBegan Function optional
    • onRotationChanged Function optional
    • onRotationEnded Function optional
    • onScaleBegan Function optional
    • onScaleChanged Function optional
    • onScaleEnded Function optional
    • drawables.initialization Drawable[] optional
    • onTrackingStarted Function optional
    • onTrackingStopped Function optional
    • onTrackingPlaneClick Function optional
    • onTrackingPlaneDragBegan Function optional
    • onTrackingPlaneDragChanged Function optional
    • onTrackingPlaneDragEnded Function optional
    • snapToScreen.enabled Boolean optional
    • snapToScreen.enableDelayed Number optional
    • snapToScreen.enabledOnExitFieldOfVision Boolean optional
    • snapToScreen.snapContainer DOM Element optional
    • snapToScreen.onSnappedToScreen Function optional
    • snapToScreen.onDelayedSnapInterruption Function optional

Methods

convertScreenCoordinateToPointCloudCoordinate

(
  • screenX
  • screenY
  • completionHandler
  • errorHandler
)

Converts a given screen coordinate into a point cloud coordinate.

Parameters:

  • screenX Number

    the x screen coordinate

  • screenY Number

    the y screen coordinate

  • completionHandler Function

    the callback that is invoced in case the screen coordinate could be successfully converted into a point cloud coordinate

  • errorHandler Function

    the callback that is invoced in case the screen coordinate could not be successfully converted into a point cloud coordinate

destroy

()

Inherited from ARchitectObject

Destroys the object.

drawables.addCamDrawable

(
  • drawable
  • position
)

Inherited from ARObject

Adds Drawables to the ARObject in the camera.

Parameters:

  • drawable Drawable | Drawable[]

    The drawable(s) that should be added to the camera. Can either be a single Drawable, or an Array of Drawables.

  • position Number optional

    The position where the Drawable should be added in the array. If not specified, the Drawable will be added at the end of the array. Must be a whole number.

drawables.addInitializationDrawable

(
  • drawable
  • position
)

Adds Drawable2Ds as visualisation of the starting position of the instant tracking.

Parameters:

  • drawable Drawable2D | Drawable2D[]

    The drawable(s) that should be added. Can either be a single Drawable2D, or an Array of Drawable2Ds.

  • position Number optional

    The position where the Drawable2D should be added in the array. If not specified, the Drawable2D will be added at the end of the array. Must be a whole number.

drawables.removeCamDrawable

(
  • drawable|position
)

Inherited from ARObject

Removes Drawables from the ARObject in the cam.

Parameters:

  • drawable|position Drawable | [Drawable] | Number

    When a single Drawable or an Array of Drawables is given, these Drawables will be removed from the array. When an integer is given, the Drawable at the specified position will be removed.

drawables.removeInitializationDrawable

(
  • drawable|position
)

Removes Drawable2Ds as visualisation of the starting position of the instant tracking.

Parameters:

  • drawable|position Drawable2D | Drawable2D[] | Int

    When a single Drawable2D or an Array of Drawable2Ds is given, these Drawable2Ds will be removed from the array. When an integer is given, the Drawable2D at the specified position will be removed.

isVisible

() Boolean

Inherited from ARObject

Returns the current visibility state of the ARObject. An ARObject is defined visible when at least one of the ARObject's locations (geolocations or visual tracker) is projected onto a screen coordinate which is currently visible on the screen.

Returns:

Boolean:

Whether the ARObject is currently visible on the screen (true) or invisble (false).

Properties

destroyed

Boolean

Inherited from ARchitectObject

Indicates if the object has already been destroyed.

drawables.cam

Drawable[]

Inherited from ARObject

The Drawables which will be used to represent the ARObject in the camera view.

Drawables in the array will be printed starting with the Drawable at position 0, causing Drawables at later indices to overlap the previously drawn Drawables.

Remark:

The array content should not be manipulated via the [] operator, as it cannot be guaranteed that the changes will be propagated through to the native application. The property should only be manipulated with arobject.drawables.addCamDrawable() and arobject.drawables.removeCamDrawable(), or directly set with arobject.drawables.cam = new Array(...);.

drawables.initialization

Drawable2D[]

The Drawable2Ds which will be used to indicate where the instant tracking will start.

Drawables in the array will be printed starting with the Drawable at position 0, causing Drawables at later indices to overlap the previously drawn Drawables.

Remark:

The array content should not be manipulated via the [] operator, as it cannot be guaranteed that the changes will be propagated through to the native application. The property should only be manipulated with instantTrackable.drawables.addInitializationDrawable() and instantTrackable.drawables.removeInitializationDrawable(), or directly set with instantTrackable.drawables.initialization = new Array(...);.

enabled

Boolean

Inherited from ARObject

A boolean flag to enable or disable the ARObject.

Default: true

renderingOrder

Number

Inherited from ARObject

Drawables of different ARObjects might overlap. In this case, renderingOrder defines the rendering order of the Drawables of the ARObject. ARObjects with higher renderingOrder values cause their Drawables to be drawn on top of the Drawables of ARObjects with lower renderingOrder values. In case two ARObjects have set the same renderingOrder, the Drawables are rendered based on the distance, causing objects closer to the user to overlap objects further away.
For example, If you want to bring Drawables of a certain ARObject to the very front, set the renderingOrder value of the corresponding ARObject to a very high value.

For the printing order of Drawables within the same ARObject, refer to Drawable2D.zOrder.

Must be a whole number.

Default: 0

snapToScreen.enabled

Boolean

Inherited from ScreenSnapper

If set to true, all cam drawables will be rendered in a div, specified by the snapToScreen.snapContainer element. The Trackable2DObject has to be in the onEnterFieldOfVision state at this point in time. If not, enabled = true has no effect. Setting enabled to false while not in the onEnterFieldOfVision state instead will work. So a Trackable2DObject can only be set to screen when the target is recognized, but can be set back to normal at any time if it's currently snapped.

Default: false

snapToScreen.enableDelayed

Number

Inherited from ScreenSnapper

The time that should pass by from when the onEnterFieldOfVision function was called and the attached drawables should snap to screen. Setting a negati ve value will disable the functionality. When the target is lost during the delay, the onDelayedSnapInterruption function will be called if set.

Default: -1

snapToScreen.enableOnExitFieldOfVision

Boolean

Inherited from ScreenSnapper

If set to true, the associated cam drawables will snap to the screen when the onExitFieldOfVision trigger fires. Using this property the drawables can snap to the screen when the target is lost which would not be possible with the enabled property. To disable snap to screen set the enabled property to false at any time (e.g. in the onEnterFieldOfVision trigger).

Default: false

snapToScreen.snapContainer

DOM Element

Inherited from ScreenSnapper

the DOM element that contains all cam drawables, associated with this Trackable2DObject if snap to screen is enabled. Note that all drawables might need to be adapted by there scale so that they fit into the element. Also Make sure that the aspect ratio of the DOM element.

Default: null

tracker

InstantTracker

The Tracker which contains the target referenced by this InstantTrackable. This property is read-only and can only be set on creation.

Events

conversionCompletionHandler

Executed when a screen to point cloud coordinate conversion was successfull

conversionErrorHandler

Executed when a screen to point cloud coordinate conversion could not be performed

onClick

Inherited from ARObject

Will be executed when any of the ARObject's Drawables have been clicked, and none of the clicked Drawables's onClick() triggers (might also be referenced by another ARObject) have been set to quit the click chain. ARObject.onClick() will be executed after any Drawable.onClick() triggers have been executed.

In case multiple ARObjects are hit by the click, the order of the execution is defined by the distance of the ARObject to the user, with the closest ARObject's click trigger executed first.

The return value of the function determines if, after the onClick()-function was executed for this ARObject, the queue shall continue to execute onClick() for the next ARObject in the queue. In case the last ARObject in the queue still requests to continue the click-queue, context.onScreenClick() will be executed.

The return value of the function decides what to do next. If false, the click-queue should not stop with this ARObject. Thus, the next ARObject's onClick() function will be executed. This is the default value in case no return value is set or the function is not defined for this ARObject. If true, the queue-execution will stop at the current ARObject, underlying ARObjects will not receive onClick() calls.

onDragBegan

Inherited from ARObject

Executed when the user starts dragging on at least one Drawable with a single finger and none of these Drawables quits the event propagation by returning true. This callback behaves identically to the onClick callback in terms of event propagation.

Event Payload:

  • xNormalized Number

    the distance on the X-axis between the initiating touch position and the updated touch position [-1, 1]; always 0 in onDragBegan as no change to the drag gesture has occurred yet

  • yNormalized Number

    the distance on the Y-axis between the initiating touch position and the updated touch position [-1, 1]; always 0 in onDragBegan as no change to the drag gesture has occurred yet

onDragChanged

Inherited from ARObject

Executed when the user drags on at least one Drawable with a single finger and none of these Drawables quits the event propagation by returning true. This callback behaves identically to the onClick callback in terms of event propagation.

Event Payload:

  • xNormalized Number

    the distance on the X-axis between the initiating touch position and the updated touch position [-1, 1]

  • yNormalized Number

    the distance on the Y-axis between the initiating touch position and the updated touch position [-1, 1]

onDragEnded

Inherited from ARObject

Executed when the user stops dragging on at least one Drawable with a single finger and none of these Drawables quits the event propagation by returning true. This callback behaves identically to the onClick callback in terms of event propagation.

Event Payload:

  • xNormalized Number

    the distance on the X-axis between the initiating touch position and the updated touch position [-1, 1]; always identical to the most recent distance received in onDragChanged

  • yNormalized Number

    the distance on the Y-axis between the initiating touch position and the updated touch position [-1, 1]; always identical to the most recent distance received in onDragChanged

onPanBegan

Inherited from ARObject

Executed when the user starts dragging on at least one Drawable with two fingers and none of these Drawables quits the event propagation by returning true. This callback behaves identically to the onClick callback in terms of event propagation.

Event Payload:

  • xNormalized Number

    the distance on the X-axis between the initiating touch positions and the updated touch positions [-1, 1]; always 0 in onPanBegan as no change to the pan gesture has occurred yet; the mid-points between the first and second touches are used to calculate the distances to allow co-operative behaviour with the scale and rotate gesture

  • yNormalized Number

    the distance on the Y-axis between the initiating touch position and the updated touch position [-1, 1]; always 0 in onPanBegan as no change to the pan gesture has occurred yet; the mid-points between the first and second touches are used to calculate the distances to allow co-operative behaviour with the scale and rotate gesture

onPanChanged

Inherited from ARObject

Executed when the user drags on at least one Drawable with two fingers and none of these Drawables quits the event propagation by returning true. This callback behaves identically to the onClick callback in terms of event propagation.

Event Payload:

  • xNormalized Number

    the distance on the X-axis between the initiating touch positions and the updated touch positions [-1, 1]; the mid-points between the first and second touches are used to calculate the distances to allow co-operative behaviour with the scale and rotate gesture

  • yNormalized Number

    the distance on the Y-axis between the initiating touch position and the updated touch position [-1, 1]; the mid-points between the first and second touches are used to calculate the distances to allow co-operative behaviour with the scale and rotate gesture

onPanEnded

Inherited from ARObject

Executed when the user stops dragging on at least one Drawable with two fingers and none of these Drawables quits the event propagation by returning true. This callback behaves identically to the onClick callback in terms of event propagation.

Event Payload:

  • xNormalized Number

    the distance on the X-axis between the initiating touch positions and the updated touch positions [-1, 1]; always identical to the most recent distance received in onPanChanged; the mid-points between the first and second touches are used to calculate the distances to allow co-operative behaviour with the scale and rotate gesture

  • yNormalized Number

    the distance on the Y-axis between the initiating touch position and the updated touch position [-1, 1]; always identical to the most recent distance received in onPanChanged; the mid-points between the first and second touches are used to calculate the distances to allow co-operative behaviour with the scale and rotate gesture

onRotationBegan

Inherited from ARObject

Executed when the user starts rotating on at least one Drawable with two fingers and none of these Drawables quits the event propagation by returning true. This callback behaves identically to the onClick callback in terms of event propagation.

Event Payload:

  • angle Number

    the CCW angle in degree between the line defined by the initiating touch positions and the line defined by the updated touch positions [0, 360); always 0 in onRotationBegan as no change to the rotation gesture has occurred yet

onRotationChanged

Inherited from ARObject

Executed when the user rotates on at least one Drawable with two fingers and none of these Drawables quits the event propagation by returning true. This callback behaves identically to the onClick callback in terms of event propagation.

Event Payload:

  • angle Number

    the CCW angle in degree between the line defined by the initiating touch positions and the line defined by the updated touch positions [0, 360)

onRotationEnded

Inherited from ARObject

Executed when the user stops rotating on at least one Drawable with two fingers and none of these Drawables quits the event propagation by returning true. This callback behaves identically to the onClick callback in terms of event propagation.

Event Payload:

  • angle Number

    the CCW angle in degree between the line defined by the initiating touch positions and the line defined by the updated touch positions [0, 360); always identical to the most recent angle received in onRotationChanged

onScaleBegan

Inherited from ARObject

Executed when the user starts scaling on at least one Drawable with two fingers and none of these Drawables quits the event propagation by returning true. This callback behaves identically to the onClick callback in terms of event propagation.

Event Payload:

  • scale Number

    the scale value defined the ratio of the distance between the updated touches over the distance between the initiating touches [0, inf]; always 1 in onScaleBegan as no change to the scale gesture has occurred yet

onScaleChanged

Inherited from ARObject

Executed when the user scales on at least one Drawable with two fingers and none of these Drawables quits the event propagation by returning true. This callback behaves identically to the onClick callback in terms of event propagation.

Event Payload:

  • scale Number

    the scale value defined the ratio of the distance between the updated touches over the distance between the initiating touches [0, inf]

onScaleEnded

Inherited from ARObject

Executed when the user stops scaling on at least one Drawable with two fingers and none of these Drawables quits the event propagation by returning true. This callback behaves identically to the onClick callback in terms of event propagation.

Event Payload:

  • scale Number

    the scale value defined the ratio of the distance between the updated touches over the distance between the initiating touches [0, inf]; always identical to the most recent scale received in onScaleChanged

onTrackingPlaneClick

Executed when the user clicks on the plane of an instant trackable. This callback does not propagate to the context as the regular onClick callback would; it is dedicated to the instant trackable only.

Event Payload:

  • xIntersection Number

    the world space X-coordinate of the intersection position of the initiating touch ray of the instant tracking plane [-infinity, infinity]

  • yIntersection Number

    the world space Y-coordinate of the intersection position of the initiating touch ray of the instant tracking plane [-infinity, infinity]

onTrackingPlaneDragBegan

Executed when the user starts dragging on the plane of an instant trackable. This callback does not propagate to the context as the regular onDragBegan callback would; it is dedicated to the instant trackable only.

Event Payload:

  • xIntersection Number

    the world space X-coordinate of the intersection position of the initiating touch ray and the instant tracking plane [-infinity, infinity]

  • yIntersection Number

    the world space Y-coordinate of the intersection position of the initiating touch ray and the instant tracking plane [-infinity, infinity]

onTrackingPlaneDragChanged

Executed when the user drags on the plane of an instant trackable. This callback does not propagate to the context as the regular onDragChanged callback would; it is dedicated to the instant trackable only.

Event Payload:

  • xIntersection Number

    the world space X-coordinate of the intersection position of the initiating touch ray and the instant tracking plane [-infinity, infinity]

  • yIntersection Number

    the world space Y-coordinate of the intersection position of the initiating touch ray and the instant tracking plane [-infinity, infinity]

onTrackingPlaneDragEnded

Executed when the user drags on the plane of an instant trackable. This callback does not propagate to the context as the regular onDragEnded callback would; it is dedicated to the instant trackable only.

Event Payload:

  • xIntersection Number

    the world space X-coordinate of the intersection position of the initiating touch ray and the instant tracking plane [-infinity, infinity]

  • yIntersection Number

    the world space Y-coordinate of the intersection position of the initiating touch ray and the instant tracking plane [-infinity, infinity]

onTrackingStarted

Executed when a transition from the tracking state to the initialization state is performed. Also, when tracking is lost.

onTrackingStarted

Executed when a transition from the initialization state to the tracking state is performed. Also, when tracking has previously been lost, but is found again.

snapToScreen.onDelayedSnapInterruption

Function

Inherited from ScreenSnapper

A function that should be called when a delayed snap to screen was interrupted because of the onExitFieldOfVision event.

Event Payload:

  • interruptionTimestamp Number

    the milliseconds that passed by between the activation through the enabledDelayed property and the interruption through the onExitFieldOfVision event.

snapToScreen.onSnappedToScreen

Function

Inherited from ScreenSnapper

A function that should be called when the underlaying ARObject snapped to the screen.

Event Payload:

  • element DOM Element

    The DOM Element to which the cam drawables snapped.