Wikitude SDK API Reference

API Docs for: 5.1.3
Show:

Trackable2DObject Class

Extends ARObject
Module: AR

A Trackable2DObject represents a virtual object bound to a specific target in a target collection. The target will be tracked in the camera scene, and Drawables will be projected onto the target as soon as it becomes visible and is detected in the scene. Any Trackable2DObject is linked to one target in a specific target collection.

A Trackable2DObject

  • is associated with one Tracker and target(s) inside the Tracker.
  • can have Drawables associated with it. These Drawables will represent the Trackable2DObject in the camera view.
  • can have triggers associated with it. Triggers fire on certain events and execute functions to react on these actions.

On creation, a reference to the Tracker, as well as the name of the target in the Tracker must be passed. The target name can either be the exact name or a regular expression. For example "*" will match all targets that are included in the given tracker. In that case the onEnterFieldOfVision event will pass the recognized target name as parameter.

A Trackable2DObject can either be enabled or disabled (see ARObject.enabled). Enabled means that the Trackable2DObject will be considered in the tracking of objects in the camera, and its triggers will fire on the appropriate events. In case the Trackable2DObject is disabled, it will not be considered in the tracking process, and it will not fire any triggers. Note that the associated Tracker must also be enabled for the Trackable2DObject to be considered for tracking.

On creation, setup parameters can be passed to customize the properties of the Trackable2DObject.

Example:
// a circle used for representation
var circle = new AR.Circle(5);
// the referenced tracker
var tracker = new AR.ClientTracker("http://myserver.com/targetCollection1.wtc");
// a Trackable2DObject using the "car" target in the tracker, using the circle as the digital representation.
var trackable2DObject = new AR.Trackable2DObject(tracker, "car", {
    drawables : {
        cam : circle
    }
});

For the render size of attached Drawables, see the chapter on SDUs.

Constructor

Trackable2DObject

(
  • tracker
  • targetName
  • options
)

Parameters:

  • tracker Tracker

    The Tracker the target is stored in

  • targetName String

    The name of the target in the Tracker

  • 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
    • onEnterFieldOfVision Function optional
    • onExitFieldOfVision Function optional
    • onClick Function optional
    • drawables.cam Drawable[] optional
    • distanceToTarget.changedThreshold Number optional
    • distanceToTarget.onDistanceChanged Function optional
    • enableExtendedTracking Boolean optional
    • extendedTrackingQualityChanged Function optional

Methods

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.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.

getDistance

() deprecated

Deprecated: The functionality is not available anymore. When the function is called, it will always return 0.

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).

stopExtendedTracking

()

Immediately stops the extended tracking mode. If the target image is already outside the field of vision, this will stop tracking the scene.

Properties

aspectRatio

Number

The aspect ratio of the target, defined as width/height. This property is read-only and will be generated after the target was loaded. The property will be undefined if the referenced Tracker was not yet loaded.

destroyed

Boolean

Inherited from ARchitectObject

Indicates if the object has already been destroyed.

distanceToTarget.changedThreshold

Number

Distance threshold (in millimeter) needed to trigger the change event.

Default: 0

distanceToTarget.onDistanceChanged

Function

Function which is called when the distance between user and target changes. The updated distance is passed as a parameter to this function.

Default: null

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(...);.

enabled

Boolean

Inherited from ARObject

A boolean flag to enable or disable the ARObject.

Default: true

enableExtendedTracking

Boolean

If this property is set to true, this trackable object will trigger the extended tracking mode. In extended tracking mode, the tracker will keep track of the 3D scene and stay active even when the target is no longer visible. This property is read-only and can only be set on creation.

height

Number deprecated

Deprecated: Use aspectRatio instead. The immutable property is undefined when the Trackable2DObject was not yet loaded, and set to 1 otherwise.

onExtendedTrackingQualityChanged

Function

If this function is defined, it will be called everytime the extended tracking quality changes. The extended tracking quality is given in three values:

    * -1 The extended tracking quality is bad and extended tracking will most likely not work
    * 0 The extended tracking quality is not very good but extended tracking might work
    * 1 The extended tracking quality is good and extended tracking will most likely work
    Please note that this callback function has three parameters. The first one is the extended target name that was tracked, the second one is the previously extended tracking quality and the last one is the new extended tracking quality.

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

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

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

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

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

targetName

String

The name of the referenced target inside the target collection. This defines on which target image the Trackable2DObject will react. The value can be either the actual name of the image or a wildcard to match several. The following wildcards are supported: * and ? to be used in the same manner as in a regular expression. This property is read-only and can only be set on creation.

tracker

Tracker

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

width

Number deprecated

Deprecated: Use aspectRatio instead. Width behaves the same way as the property aspectRatio.

Events

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.

onEnterFieldOfVision

Inherited from ARObject

The trigger will fire when the ARObject's visibility has changed from invisible to visible.

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 onEnterFieldOfVision.

Event Payload:

  • targetName String

    In case of a Trackable2DObject holds the name of the recognized target. Used in combination with wildcards for targetName.

onExitFieldOfVision

Inherited from ARObject

Will be executed when the ARObject's visibility has changed from visible to invisible.

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 onExitFieldOfVision.

Event Payload:

  • targetName String

    In case of a Trackable2dObject this will hold the name of the target that exited the field of vision.

snapToScreen.onDelayedSnapInterruption

Function

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

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.

triggers.onEnterFieldOfVision

deprecated

Inherited from ARObject

Deprecated: Use onEnterFieldOfVision instead.

triggers.onExitFieldOfVision

deprecated

Inherited from ARObject

Deprecated: Use onExitFieldOfVision instead.