WTInstantTracker Class Reference

Inherits from	NSObject
Declared in	WTInstantTracker.h

Overview

Instant trackers start in initializing state, during which the origin of the tracked scene can be set by rotating the device. Displaying a gravity aligned plane or target in the center of the screen can help users through this process. After this was set, the instant tracker can instantly transition to the tracking state, during which the actual tracking of the scene takes place.

`enabled`

Whether the tracker is enabled.

@property (nonatomic, readonly) BOOL enabled

Declared In

WTInstantTracker.h

`– setActiveInstantTrackingState:`

Changes the tracking state of the instant tracker

- (void)setActiveInstantTrackingState:(WTInstantTrackingState)state

Parameters

`state`	The new state to which the instant tracker should switch to

Discussion

The tracking state is not changed immediately, and the didChangeState method can be used to get notified of exactly when that happens.

Declared In

WTInstantTracker.h

`– setDeviceHeightAboveGround:`

Allows changing the estimated height at which the device is currently above the ground.

- (void)setDeviceHeightAboveGround:(float)height

Parameters

`height`	The estimated device height above the ground in meters

Discussion

Setting this to an appropriate value will allow the augmentations to have a scale close to the one they would have in reality.

Declared In

WTInstantTracker.h

`– setTrackingPlaneOrientation:`

Allows changing the orientation of the plane with which the instant tracking initializes

- (void)setTrackingPlaneOrientation:(float)trackingPlaneOrientation

Parameters

`trackingPlaneOrientation`	The orientation of the tracking plane in degrees

Discussion

The orientation can only be changed if the active instant tracking state is WTInstantTrackerInitializing. It can be set to all values between 360 and -360. This can enable e.g. easier tracking on walls and ceilings.

Declared In

WTInstantTracker.h

`– convertScreenCoordinate:toPointCloudCoordinateOnQueue:completion:`

use this method to perform a hit test on the point cloud coming from the instant tracker.

When invoking this method, a block on the given operation queue is dispatched which performs the hit test operation. In case there is no point at the given screen coordinate, the BOOL property in the completion handler is set to NO. Otherwise the given 3d coordinate can be used to position an augmentation at this point.

- (void)convertScreenCoordinate:(CGPoint)screenCoordinate toPointCloudCoordinateOnQueue:(NSOperationQueue *)operationQueue completion:(WTInstantTrackingCoordinateConversionHandler)completionHandler

Parameters

`screenCoordinate`	The screen coordinate for that a hit test should be performed
`operationQueue`	The operation queue on which the hit test computation should be performed
`completionHandler`	The block that should be called when the hit test computation finishes

Declared In

WTInstantTracker.h

`– convertScreenCoordinatetoPointCloudCoordinate:success:error:`

Use this method to perform a hit test on the point cloud coming from the instant tracker.

This operation is performed on a separate thread and the successHandler is called from that thread. Because this operation uses screen coordinates, please make sure that surface changed is called at least once before invoking this method.

- (void)convertScreenCoordinatetoPointCloudCoordinate:(CGPoint)screenCoordinate success:(WTInstantTrackingCoordinateConversionSuccessHandler)successHandler error:(WTInstantTrackingCoordinateConversionErrorHandler)errorHandler

Parameters

`screenCoordinate`	The screen coordinate for which a hit test should be performed.
`successHandler`	The callback that should be called when the hit test computation finishes. This will be called from another thread.
`errorHandler`	The callback that should be called when an error occurs.

Declared In

WTInstantTracker.h

`– requestCurrentPointCloudOnQueue:representedThroughDataProvider:`

use this method to get all points of the current point cloud that is managed by this instant tracker

When invoking this method, a block on the given operation queue is dispatched which performs the point cloud retrieval.

- (void)requestCurrentPointCloudOnQueue:(NSOperationQueue *)operationQueue representedThroughDataProvider:(WTInstantTrackingPointCloudDataProvider *)dataProvider

Parameters

`operationQueue`	The operation queue on which the point cloud retrieval is performed
`dataProvider`	The data provider that should be used to provide the current point cloud.

Declared In

WTInstantTracker.h

`– requestCurrentPointCloudRepresentedThroughDataProvider:`

use this method to get all points of the current point cloud that is managed by this instant tracker

- (void)requestCurrentPointCloudRepresentedThroughDataProvider:(WTInstantTrackingPointCloudDataProvider *)dataProvider

Parameters

`dataProvider`	The data provider that should be used to provide the current point cloud.

Declared In

WTInstantTracker.h

`– canStartTracking`

Use this method to query whether a state change from initialization state to tracking state can be performed.

- (BOOL)canStartTracking

Return Value

A BOOL value indicating the viability of a subsequent state change. YES for viable, NO for not viable.

Discussion

For Wikitude’s instant tracking algorithm, this function currently always returns YES because the state change is always possible. For ARKit this function performs a hit test internally to check whether the state can be switched or not. Theoretically, the state change could still be unsuccessful after this function has indicated otherwise due to a hit test position that differs and a temporal delay between the two calls. Practically, this is the best we can do and it works consistently.

Declared In

WTInstantTracker.h

`– saveCurrentInstantTargetWithSceneName:success:error:`

Use this method to persist the currently tracked instant tracking session as a file.

- (void)saveCurrentInstantTargetWithSceneName:(NSURL *)instantTargetDestinationURL success:(WTSaveCurrentInstantTargetSuccessHandler)successHandler error:(WTSaveCurrentInstantTargetErrorHandler)errorHandler

Parameters

`instantTargetDestinationURL`	A iOS sandbox compliant URL including a file name to which the current session should be saved to. NSFileManager can be used to get such a URL.
`successHandler`	A completion handler that is called if the current session could be successfully stored at the given URL. This handler might be called from a background thread.
`errorHandler`	A completion handler that is called in case the current session could not be successfully stored at the given URL. The given NSError contains more information why the operation failed.

Discussion

Saving the current session as an instant target happens on a background thread. In case the given directory does not exist, the error handler is called with a description and more details. In case the directory exists and a file with the same name in it exists, it will be overridden. The file type is .wto

Declared In

WTInstantTracker.h

`– loadExistingInstantTargetWithTargetCollectionResource:restoration:success:error:`

Use this method to load a previously stored instant target.

- (void)loadExistingInstantTargetWithTargetCollectionResource:(WTTargetCollectionResource *)targetCollectionResource restoration:(WTInstantTrackingTargetRestorationConfigurationHandler)restorationHandler success:(WTLoadInstantTargetSuccessHandler)successHandler error:(WTLoadInstantTargetErrorHandler)errorHandler

Parameters

`targetCollectionResource`	The target collection resource that points to a .wto file (either on the device or a remote server). Please refer to `WTTrackerManager` `-createTargetCollectionResourceFromURL:` for more information.
`restorationHandler`	This handler is used to provide further information on how the previously stored instant target should be restored. Please refer to the `WTInstantTargetRestorationConfiguration` class reference for more information.
`successHandler`	A completion handler that is called once the instant target is fully restored and ready for recognition.
`errorHandler`	A completion handler that is called in case the instant target could not be restored. The given NSError contains more information why the operation failed.

Discussion

Loading an instant target happens on a background thread.

Declared In

WTInstantTracker.h