ARImageTrackable Class Reference

#import <ARImageTrackable.h>

Inherits NSObject.

Instance Methods
(instancetype)	- initWithPath:
(instancetype)	- initWithBundledFile:
(instancetype)	- initWithImage:name:
(instancetype)	- initWithImage:name:autoCrop:
(instancetype)	- initWithImage:name:width:height:
(instancetype)	- initWithImage:name:width:height:autoCrop:
(void)	- addTrackingEventTarget:action:forEvent:
(void)	- removeTrackingEventTarget:action:forEvent:
(NSSet *)	- allTrackingEventTargets
(void)	- allowRecoveryMode
(void)	- forceRecoveryMode
(void)	- prohibitRecoveryMode
(void)	- setExtensible:
(BOOL)	- isExtensible
(BOOL)	- isExtended
(void)	- clearExtensions

Protected Types
enum	ARImageTrackableEvents { ARImageTrackableEventDetected, ARImageTrackableEventLost, ARImageTrackableEventTracked }

Properties
NSString *	name
int	width
int	height
BOOL	isDetected
ARNode *	world
ARNode *	worldYUp
ARNode *	touchableNode

Detailed Description

The ARImageTrackable class represents an image that can be tracked. Add ARImageTrackables to the ARImageTrackerManager in order to display content on those trackables. The ARImageTrackerManager will automatically update properties of any trackables added to it. Add ARNodes as children of the ARImageTrackable's world to render content on the trackable.

Member Enumeration Documentation

ARImageTrackableEvents

- (enum) ARImageTrackableEvents

protected

Tracking events:

Enumerator
ARImageTrackableEventDetected	ARImageTrackableEventDetected** - The first frame that a marker has been detected.
ARImageTrackableEventLost	ARImageTrackableEventLost** - The first frame since it started being tracker that it is no longer being tracked.
ARImageTrackableEventTracked	ARImageTrackableEventTracked** - Marker was tracked. This can be sent in the same frame as ARImageTrackableEventDetected.

Method Documentation

addTrackingEventTarget:action:forEvent:

- (void) addTrackingEventTarget:		(id)	target
action:		(SEL)	action
forEvent:		(ARImageTrackableEvents)	event

Add an action for a given tracking event.

NOTE: Any added tracking event targets must be removed before exiting an ARView.

Example of use:

[imageTrackable addTrackingEventTarget:self action:@selector(detected:) forEvent:ARImageTrackableEventDetected];

Parameters

target	The target object to add the event to.
action	The action to get called on the target. It will get called with a single argument - the ARImageTrackable that triggered the event.
forEvent	The event type, Detected, Tracked or Lost.

allowRecoveryMode

- (void) allowRecoveryMode

Set this marker to use flow recovery, if the global setting is switched on (default to global setting). Recovery mode is a feature that allows for quicker re-detection of a marker if it is lost. It is also easier to re-detect the marker from shallower angles and greater distances. It is recommended that this feature be enabled for as many markers as possible, though doing so will use a fraction more CPU power.

Example of use:

[imageTrackable allowRecoveryMode];

allTrackingEventTargets

- (NSSet *) allTrackingEventTargets

The set of all tracking targets. Contains NSDictionary objects of target, action and forEvent keys.

clearExtensions

- (void) clearExtensions

For extended markers: clear all current extensions (they can be re-created after this, if extended tracking has not been disabled).

Example of use:

[imageTrackable clearExtensions];

forceRecoveryMode

- (void) forceRecoveryMode

Make this marker use flow recovery irrespective of the global setting.

Example of use:

[imageTrackable forceRecoveryMode];

initWithBundledFile:

- (instancetype) initWithBundledFile:

(NSString *)

bundledFile

Initialises an ARImageTrackable using a .KARMarker data set in the main bundle.

Example of use:

ARImageTrackable *imageTrackable = [[ARImageTrackable alloc] initWithBundledFile:@"example.KARMarker"];

Parameters

bundledFile

The file path to the trackable file relative to the main project bundle, including the file extension. This file should have been generated by the Kudan AR Toolkit and be in the .KARMarker format.

Returns

the initialised object.

initWithImage:name:

- (instancetype) initWithImage:		(UIImage *)	image
name:		(NSString *)	name

Initialises this object with a UIImage and assigns it the given name.

Example of use:

ARImageTrackable *imageTrackable = [[ARImageTrackable alloc] initWithImage:[UIImage imageNamed:@"example.jpg"] name:@"Example Marker"];

Parameters

image	A UIImage representing the image to create this trackable from.
name	The name to give to this trackable so the tracker can find it by name.

Returns

The initialised object.

initWithImage:name:autoCrop:

- (instancetype) initWithImage:		(UIImage *)	image
name:		(NSString *)	name
autoCrop:		(BOOL)	autoCrop

Initialises this object with a UIImage, assigns it the given name and sets whether autocropping should be used. Autocropping is a feature that automatically finds the most useful sub-region of a trackable image, and uses that for tracking and detection. This allows images containing large borders to be used without sacrificing tracking resolution. Cropping is automatic and makes no difference to how the trackable objects are used the tracked region will never look cropped. This must be enabled for individual markers when they are created from images.

Example of use:

ARImageTrackable *imageTrackable = [[ARImageTrackable alloc] initWithImage:[UIImage imageNamed:@"example.jpg"] name:@"Example Marker" autoCrop:YES];

Parameters

image	A UIImage representing the image to create this trackable from.
name	The name to give to this trackable so the tracker can find it by name.
autoCrop	Set whether this image will be optimally cropped internally for tracking.

Returns

The initialised object.

initWithImage:name:width:height:

- (instancetype) initWithImage:		(UIImage *)	image
name:		(NSString *)	name
width:		(int)	width
height:		(int)	height

Initialises this object with a UIImage, assigns it the given name and sets its width and height.

Example of use:

ARImageTrackable *imageTrackable = [[ARImageTrackable alloc] initWithImage:[UIImage imageNamed:@"example.jpg"] name:@"Example Marker" width:100 height:100];

Parameters

image	A UIImage representing the image to create this trackable from.
name	The name to give to this trackable so the tracker can find it by name.
width,height	Set the size of the marker in world units

Returns

The initialised object.

initWithImage:name:width:height:autoCrop:

- (instancetype) initWithImage:		(UIImage *)	image
name:		(NSString *)	name
width:		(int)	width
height:		(int)	height
autoCrop:		(BOOL)	autoCrop

Initialises this object with a UIImage, assigns it the given name, sets its width and height and sets whether autocropping should be used.

Example of use:

ARImageTrackable *imageTrackable = [[ARImageTrackable alloc] initWithImage:[UIImage imageNamed:@"example.jpg"] name:@"Example Marker" width:100 height:100 autoCrop:YES];

Parameters

image	A UIImage representing the image to create this trackable from.
name	The name to give to this trackable so the tracker can find it by name.
autoCrop	Set whether this image will be optimally cropped internally for tracking.
width,height	Set the size of the marker in world units

Returns

The initialised object.

initWithPath:

- (instancetype) initWithPath:

(NSString *)

path

Initialises an ARImageTrackable using a .KARMarker data set. A .KARMarker is a custom format that is more lightweight than that of a usual .jpg file. This means that, by converting marker images into .KARMarker files, a good deal of space can be saved.

Example of use:

NSString *filePath = [[[NSBundle mainBundle] resourcePath] stringByAppendingString:@"example.KARMarker"];
ARImageTrackable *imageTrackable = [[ARImageTrackable alloc] initWithPath:filePath];

Parameters

path	The full file path to the trackable file, including all folders and file extension. This file should have been generated by the Kudan AR Toolkit and be in the .KARMarker format.

Returns

the initialised object.

isExtended

- (BOOL) isExtended

Get whether any extensions have been made of this marker, or if this marker is itself an extension of a marker.

Example of use:

BOOL extendedStatus = [imageTrackable isExtended];

Returns

Whether this one trackable has extensions (YES) or not (NO).

isExtensible

- (BOOL) isExtensible

Get whether this marker is using Extended Tracking and Detection.

Example of use:

BOOL extensibilityStatus = [imageTrackable isExtensible];

Returns

Whether extensibility is enabled (YES) or not (NO) on this trackable.

prohibitRecoveryMode

- (void) prohibitRecoveryMode

Prevent this marker from using flow recovery, irrespective of the global setting.

Example of use:

[imageTrackable prohibitRecoveryMode];

removeTrackingEventTarget:action:forEvent:

- (void) removeTrackingEventTarget:		(id)	target
action:		(SEL)	action
forEvent:		(ARImageTrackableEvents)	event

Remove an existing tracking target.

Example of use:

[imageTrackable removeTrackingEventTarget:self action:@selector(detected:) forEvent:ARImageTrackableEventDetected];

Parameters

target	The target object to remove the event from.
action	The action to get called on the target. It will get called with a single argument - the ARImageTrackable that triggered the event.
forEvent	The event type, Detected, Tracked or Lost.

setExtensible:

- (void) setExtensible:

(BOOL)

isExtensible

Set whether this marker should use Extended Tracking and Detection. Extended Tracking and Detection is a feature where trackables can be extended by automatically creating new markers from the surrounding scene. This means that after being expanded, trackables can be detected and tracked from much further away. This can be activated on a per-trackable basis and should ideally only be used for stationary markers, such as posters. Extended Tracking is good for tracking small objects at large distances when moving away from the marker. Extended Tracking is not designed for use with markers that are not stationary. Enabling this feature will require slightly more memory space.

Example of use:

[imageTrackable setExtensible:YES];

Parameters

isExtensible

Set if the marker is extensible or not. Setting this to NO will prevent any more extensions being made (but not clear existing ones).

Property Documentation

height

- (int) height

readwritenonatomicassign

The scene height of this trackable. This can be arbitrary but is used to determine the scale of the coordinate system that is attached to this node.

isDetected

- (BOOL) isDetected

readnonatomicassign

Whether this trackable is currently detected or not. Automatically controlled by the tracker.

name

- (NSString *) name

readwritenonatomicassign

The name of this trackable. This needs to be unique, otherwise the tracker will not be able to find it. If initialised from a trackable file then it is read in automatically.

width

- (int) width

readwritenonatomicassign

The scene width of this trackable. This can be arbitrary but is used to determine the scale of the coordinate system that is attached to this node.

world

- (ARNode*) world

readwritenonatomicassign

The node whose transformation is automatically updated by the tracker to represent the trackable's pose in the camera image. Content attached here will be tracked whilst the trackable is being detected.

---

The documentation for this class was generated from the following files:

• ARImageTrackable.h
• ARImageTrackable.mm