ImageTrackable Class
A ImageTrackable 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 ImageTrackable is linked to one target in a
specific target collection.
A ImageTrackable
- is associated with one Tracker and target(s) inside the Tracker.
- can have Drawables associated with it. These Drawables will represent the ImageTrackable 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
onImageRecognized event will pass the recognized target name as parameter.
A ImageTrackable can either be
enabled or disabled (see ARObject.enabled). Enabled means that the
ImageTrackable will be considered in the tracking of objects in the
camera, and its triggers will fire on the appropriate events. In case the
ImageTrackable 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 ImageTrackable to be considered for tracking.
On creation, setup parameters can be passed to customize the properties of
the ImageTrackable.
// a circle used for representation var circle = new AR.Circle(5); // the referenced tracker var targetCollectionResource = new AR.TargetCollectionResource("http://myserver.com/targetCollection1.wtc"); var tracker = new AR.ImageTracker(targetCollectionResource); // a ImageTrackable using the "car" target in the tracker, using the circle as the digital representation. var ImageTrackable = new AR.ImageTrackable(tracker, "car", { drawables : { cam : circle } });
// a circle used for representation var circle = new AR.Circle(5); // the referenced tracker var cloudRecognitionService = new AR.CloudRecognitionService("__your_client_token__", "__target_collection_id__"); var tracker = new AR.ImageTracker(cloudConnection); // a ImageTrackable using the "car" target in the tracker, using the circle as the digital representation. var ImageTrackable = new AR.ImageTrackable(tracker, "car", { drawables : { cam : circle } });
For the render size of attached Drawables, see the chapter on SDUs.
Constructor
ImageTrackable
-
tracker
-
targetName
-
options
-
@deprecated
-
@deprecated
-
@deprecated
Parameters:
-
tracker
ImageTrackerThe ImageTracker the target is stored in
-
targetName
StringThe name of the target in the Tracker
-
options
Object optionalSetup-Parameters to customize additional object properties.
Accepted options-properties are-
enabled
(defaults totrue
) Boolean optional -
renderingOrder
(defaults to0
) Number optional -
onImageRecognized
Function optional -
onImageLost
Function 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.cam
Drawable[] 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 -
distanceToTarget.changedThreshold
Number optional -
distanceToTarget.onDistanceChanged
Function optional
-
-
@deprecated
Boolean[options.enableExtendedTracking]
-
@deprecated
String[options.extendedTarget]
-
@deprecated
Function[options.onExtendedTrackingQualityChangedTriggerActive]
Item Index
Methods
Properties
- aspectRatio
- destroyed
- distanceToTarget.changedThreshold
- distanceToTarget.onDistanceChanged
- drawables.cam
- enabled
- enableExtendedTracking deprecated
- extendedTarget deprecated
- onExtendedTrackingQualityChanged deprecated
- renderingOrder
- snapToScreen.enabled
- snapToScreen.enableDelayed
- snapToScreen.enabledOnExitFieldOfVision
- snapToScreen.snapContainer
- targetName
- tracker
Events
- onClick
- onDragBegan
- onDragChanged
- onDragEnded
- onEnterFieldOfVision deprecated
- onExitFieldOfVision deprecated
- onImageLost
- onImageRecognized
- onPanBegan
- onPanChanged
- onPanEnded
- onRotationBegan
- onRotationChanged
- onRotationEnded
- onScaleBegan
- onScaleChanged
- onScaleEnded
- onTrackingPlaneClick
- onTrackingPlaneDragBegan
- onTrackingPlaneDragChanged
- onTrackingPlaneDragEnded
- snapToScreen.onDelayedSnapInterruption
- snapToScreen.onSnappedToScreen
Methods
addImageTargetCamDrawables
-
imageTarget
-
arrayOfDrawables
-
position
Adds AR.Drawables to the ImageTrackable for the ImageTarget. This enables different AR.Drawables for the same target image (Multiple targets with the same target image).
Parameters:
-
imageTarget
ImageTargetThe ImageTargets for which the AR.Drawables should be added.
-
arrayOfDrawables
Drawable | Drawable[]The drawable(s) that should be added to the camera for the imageTarget. Can either be a single AR.Drawable, or an Array of AR.Drawables.
-
position
NumberThe position where the AR.Drawable should be added in the array. If not specified, the AR.Drawable will be added at the end of the array. Must be a whole number.
destroy
()
Destroys the object.
drawables.addCamDrawable
-
drawable
-
position
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 optionalThe 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
Removes Drawables from the ARObject in the cam.
Parameters:
-
drawable|position
Drawable | [Drawable] | NumberWhen 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.
isVisible
()
Boolean
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:
Whether the ARObject is currently visible on the screen (true) or invisble (false).
removeImageTargetCamDrawables
-
imageTarget
-
drawables|position
Removes AR.Drawables to the ImageTrackable for the ImageTarget
Parameters:
-
imageTarget
ImageTargetThe ImageTargets for which the AR.Drawables should be removed.
-
drawables|position
Drawable | Drawable[] | NumberWhen a single AR.Drawable or an Array of AR.Drawables is given, these AR.Drawables will be removed from the array. When an integer is given, the AR.Drawable at the specified position will be removed.
stopExtendedTracking
()
deprecated
Immediately stops extended tracking. If the target image is already outside ot the field of vision, this will stop tracking the scene. Resuming extended tracking is only possible if one of the associated target images is recognized again.
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.
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[]
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.
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(...);.
enableExtendedTracking
Boolean
deprecated
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.
extendedTarget
String
deprecated
Use this property to define which targets of an ImageTrackable are treated as extended targets. In case a wildcard was used to define the targetName, this property also accepts the same wildcard settings ('*' and '?'). This property can be changed at any time. Changes take affect as soon as an ongoing extended tracking is lost or the stopExtendedTracking function is called.
onExtendedTrackingQualityChanged
Function
deprecated
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
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.enabledOnExitFieldOfVision
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 ImageTrackable 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
ImageTracker
The ImageTracker which contains the target referenced by this ImageTrackable. This property is read-only and can only be set on creation.
Events
onClick
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
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
Numberthe 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
Numberthe 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
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.
onDragEnded
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
Numberthe 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
Numberthe 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
onEnterFieldOfVision
deprecated
The trigger will fire when the ImageTrackable'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
StringHolds the name of the recognized target. Used in combination with wildcards for targetName.
onExitFieldOfVision
deprecated
Will be executed when the ImageTrackable'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
StringHolds the name of the target that exited the field of vision.
onImageLost
Will be executed when the ImageTrackable'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 onImageLost.
Event Payload:
-
target
ImageTargetAn ImageTarget that represents the target that has been lost.
onImageRecognized
The trigger will fire when the ImageTrackable'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 onImageRecognized.
Event Payload:
-
target
ImageTargetAn ImageTarget that represents the target that has been recognized.
onPanBegan
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
Numberthe 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
Numberthe 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
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
Numberthe 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
Numberthe 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
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
Numberthe 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
Numberthe 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
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
Numberthe 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
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
Numberthe 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
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
Numberthe 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
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
Numberthe 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
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
Numberthe scale value defined the ratio of the distance between the updated touches over the distance between the initiating touches [0, inf]
onScaleEnded
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
Numberthe 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 image trackable. This callback does not propagate to the context as the regular onClick callback would; it is dedicated to the image trackable only.
Event Payload:
-
xIntersection
Numberthe world space X-coordinate of the intersection position of the initiating touch ray of the image tracking plane [-infinity, infinity]
-
yIntersection
Numberthe world space Y-coordinate of the intersection position of the initiating touch ray of the image tracking plane [-infinity, infinity]
onTrackingPlaneDragBegan
Executed when the user starts dragging on the plane of an image trackable. This callback does not propagate to the context as the regular onDragBegan callback would; it is dedicated to the image trackable only.
Event Payload:
-
xIntersection
Numberthe world space X-coordinate of the intersection position of the initiating touch ray and the image tracking plane [-infinity, infinity]
-
yIntersection
Numberthe world space Y-coordinate of the intersection position of the initiating touch ray and the image tracking plane [-infinity, infinity]
onTrackingPlaneDragChanged
Executed when the user drags on the plane of an image trackable. This callback does not propagate to the context as the regular onDragChanged callback would; it is dedicated to the image trackable only.
Event Payload:
-
xIntersection
Numberthe world space X-coordinate of the intersection position of the initiating touch ray and the image tracking plane [-infinity, infinity]
-
yIntersection
Numberthe world space Y-coordinate of the intersection position of the initiating touch ray and the image tracking plane [-infinity, infinity]
onTrackingPlaneDragEnded
Executed when the user drags on the plane of an image trackable. This callback does not propagate to the context as the regular onDragEnded callback would; it is dedicated to the image trackable only.
Event Payload:
-
xIntersection
Numberthe world space X-coordinate of the intersection position of the initiating touch ray and the image tracking plane [-infinity, infinity]
-
yIntersection
Numberthe world space Y-coordinate of the intersection position of the initiating touch ray and the image tracking plane [-infinity, infinity]
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
Numberthe 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 ElementThe DOM Element to which the cam drawables snapped.