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 |
---|---|
restorationHandler |
This handler is used to provide further information on how the previously stored instant target should be restored. Please refer to the |
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