com.wikitude.tracker

Interface InstantTracker

public interface InstantTracker

Interface to control Instant Trackers

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static interface	InstantTracker.PointCloudCallback Interface to receive instant tracking point cloud data as Vector3<Float>[].
static interface	InstantTracker.PointCloudNativeCallback Interface to receive instant tracking point cloud data as pointer to a native float array.
static interface	InstantTracker.ScenePickingCallback Interface to receive picking results from the InstantTracker class

Method Summary

Modifier and Type	Method and Description
boolean	canStartTracking() Queries whether the state can be changed from initialization to tracking.
void	convertScreenCoordinateToPointCloudCoordinate(Vector2<Float> screenCoordinate, InstantTracker.ScenePickingCallback callback) Queries the point cloud for a 3D position using the provided 2D screen position. The callback will be invoked synchronously on the call thread.
void	convertScreenCoordinateToPointCloudCoordinate(Vector2<Float> screenCoordinate, InstantTracker.ScenePickingCallback callback, android.os.Handler handler) Queries the point cloud for a 3D position using the provided 2D screen position. The method returns immediately and informs about the result asynchronously using the specified callback and handler. Note: This method is not designed to be called repeatedly, calling it repeatedly(e.g.
void	loadExistingInstantTarget(TargetCollectionResource targetCollectionResource, CompletionCallback completion, ErrorCallback error, InstantTargetRestorationConfiguration configuration) Loads the provided instant target and starts tracking it. This feature is not available with platform assisted tracking enabled. e.g.:
void	loadExistingInstantTarget(TargetCollectionResource targetCollectionResource, CompletionCallback completion, ErrorCallback error, InstantTargetRestorationConfiguration configuration, android.os.Handler handler) Loads the provided instant target and starts tracking it. This feature is not available with platform assisted tracking enabled. e.g.:
void	requestCurrentPointCloud(InstantTracker.PointCloudCallback callback) Queries the current 3D point cloud as Vector3<Float>[].
void	requestCurrentPointCloud(InstantTracker.PointCloudCallback callback, android.os.Handler handler) Queries the current 3D point cloud as Vector3<Float>[].
void	requestCurrentPointCloudNativePointer(InstantTracker.PointCloudNativeCallback callback) Queries the current 3D point cloud as pointer to a native float array.
void	requestCurrentPointCloudNativePointer(InstantTracker.PointCloudNativeCallback callback, android.os.Handler handler) Queries the current 3D point cloud as pointer to a native float array.
void	saveCurrentInstantTarget(String url, CompletionCallback completion, ErrorCallback error) Saves the current scene created by the InstantTracker. The saved file can then be loaded as TargetCollectionResource using loadExistingInstantTarget(com.wikitude.tracker.TargetCollectionResource, com.wikitude.common.CompletionCallback, com.wikitude.common.ErrorCallback, com.wikitude.tracker.InstantTargetRestorationConfiguration). This enables that AR experiences can be persistently accessed by multiple users across devices and operating systems. This feature is not available with platform assisted tracking enabled.
void	saveCurrentInstantTarget(String url, CompletionCallback completion, ErrorCallback error, android.os.Handler handler) Saves the current scene created by the InstantTracker. The saved file can then be loaded as TargetCollectionResource using loadExistingInstantTarget(com.wikitude.tracker.TargetCollectionResource, com.wikitude.common.CompletionCallback, com.wikitude.common.ErrorCallback, com.wikitude.tracker.InstantTargetRestorationConfiguration). This enables that AR experiences can be persistently accessed by multiple users across devices and operating systems. This feature is not available with platform assisted tracking enabled.
void	setDeviceHeightAboveGround(float height) Sets the current height at which the device is being held above the ground or other desired tracking surface (e.g.
void	setState(InstantTrackingState state) Changes the state in which the tracker should run in
void	setTrackingPlaneOrientation(float orientation) Sets the current orientation at which the instant tracking plane should be displayed. This can be used to align the instant tracking plane with real world structures (e.g.

Method Detail

setState

void setState(InstantTrackingState state)

Changes the state in which the tracker should run in

Parameters:

state - The new state in which the tracker should run in.

setDeviceHeightAboveGround

void setDeviceHeightAboveGround(float height)

Sets the current height at which the device is being held above the ground or other desired tracking surface (e.g. table).
This is used to compute the correct scale of the augmentations.

The device height above ground may only be set while the InstantTrackingState is InstantTrackingState.Initializing

Parameters:

height - The current height at which the device is being held.

setTrackingPlaneOrientation

void setTrackingPlaneOrientation(float orientation)

Sets the current orientation at which the instant tracking plane should be displayed.
This can be used to align the instant tracking plane with real world structures (e.g. 0° for a floor, 90° for a vertical wall)

The tracking plane orientation may only be set while the InstantTrackingState is InstantTrackingState.Initializing
This setting is not used when running InstantTracking with SMART.

Parameters:

orientation - The Angle in degree.

convertScreenCoordinateToPointCloudCoordinate

void convertScreenCoordinateToPointCloudCoordinate(Vector2<Float> screenCoordinate,
                                                   InstantTracker.ScenePickingCallback callback)

Queries the point cloud for a 3D position using the provided 2D screen position.
The callback will be invoked synchronously on the call thread. Use convertScreenCoordinateToPointCloudCoordinate(Vector2, ScenePickingCallback, Handler) for asynchronous querying.

Note: This method is not designed to be called repeatedly, calling it repeatedly(e.g. in InstantTrackerListener.onTracked(com.wikitude.tracker.InstantTracker, com.wikitude.tracker.InstantTarget)) may affect the performance of the Instant Tracking.

Parameters:

screenCoordinate - The input screen coordinate in pixels. This value may not be null.

callback - The callback which is invoked once the process is finished. This value may not be null.

Throws:

IllegalArgumentException - if screenCoordinate or the callback was null.

convertScreenCoordinateToPointCloudCoordinate

void convertScreenCoordinateToPointCloudCoordinate(Vector2<Float> screenCoordinate,
                                                   InstantTracker.ScenePickingCallback callback,
                                                   android.os.Handler handler)

Queries the point cloud for a 3D position using the provided 2D screen position.
The method returns immediately and informs about the result asynchronously using the specified callback and handler.

Note: This method is not designed to be called repeatedly, calling it repeatedly(e.g. in InstantTrackerListener.onTracked(com.wikitude.tracker.InstantTracker, com.wikitude.tracker.InstantTarget)) may affect the performance of the Instant Tracking.

Parameters:

screenCoordinate - The input screen coordinate in pixels. This value may not be null.

callback - The callback which is invoked once the process is finished. This value may not be null.

handler - The handler on which the callback should be invoked, or null to use the current thread's looper.

Throws:

IllegalArgumentException - if screenCoordinate or the callback was null.

requestCurrentPointCloud

void requestCurrentPointCloud(InstantTracker.PointCloudCallback callback)

Queries the current 3D point cloud as Vector3<Float>[].
The callback will be invoked synchronously on the call thread. Use requestCurrentPointCloud(PointCloudCallback, Handler) for asynchronous querying.

Note: This method is not designed to be called repeatedly, calling it repeatedly(e.g. in InstantTrackerListener.onTracked(com.wikitude.tracker.InstantTracker, com.wikitude.tracker.InstantTarget)) may affect the performance of the Instant Tracking.

Parameters:

callback - The callback which is invoked once the process is finished. This value may not be null.

Throws:

IllegalArgumentException - if the callback was null.

requestCurrentPointCloud

void requestCurrentPointCloud(InstantTracker.PointCloudCallback callback,
                              android.os.Handler handler)

Queries the current 3D point cloud as Vector3<Float>[].
The method returns immediately and informs about the result asynchronously using the specified callback and handler.

Note: This method is not designed to be called repeatedly, calling it repeatedly(e.g. in InstantTrackerListener.onTracked(com.wikitude.tracker.InstantTracker, com.wikitude.tracker.InstantTarget)) may affect the performance of the Instant Tracking.

Parameters:

callback - The callback which is invoked once the process is finished. This value may not be null.

handler - The callback which is invoked once the process is finished. This value may not be null.

Throws:

IllegalArgumentException - if the callback was null.

requestCurrentPointCloudNativePointer

void requestCurrentPointCloudNativePointer(InstantTracker.PointCloudNativeCallback callback)

Queries the current 3D point cloud as pointer to a native float array.
The callback will be invoked synchronously on the call thread. Use requestCurrentPointCloudNativePointer(PointCloudNativeCallback, Handler) for asynchronous querying.

Note: This method is not designed to be called repeatedly, calling it repeatedly(e.g. in InstantTrackerListener.onTracked(com.wikitude.tracker.InstantTracker, com.wikitude.tracker.InstantTarget)) may affect the performance of the Instant Tracking.

Parameters:

callback - The callback which is invoked once the process is finished. This value may not be null.

requestCurrentPointCloudNativePointer

void requestCurrentPointCloudNativePointer(InstantTracker.PointCloudNativeCallback callback,
                                           android.os.Handler handler)

Queries the current 3D point cloud as pointer to a native float array.
The method returns immediately and informs about the result asynchronously using the specified callback and handler.

Note: This method is not designed to be called repeatedly, calling it repeatedly(e.g. in InstantTrackerListener.onTracked(com.wikitude.tracker.InstantTracker, com.wikitude.tracker.InstantTarget)) may affect the performance of the Instant Tracking.

Parameters:

callback - The callback which is invoked once the process is finished. This value may not be null.

handler - The callback which is invoked once the process is finished. This value may not be null.

canStartTracking

boolean canStartTracking()

Queries whether the state can be changed from initialization to tracking.
Note: For Wikitude's instant tracking algorithm, this function currently always returns true because the state change is always possible. For platform assisted tracking(ARCore), 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.

Returns:

A boolean value indicating the viability of a subsequent state change. true for viable, false for not viable.

saveCurrentInstantTarget

void saveCurrentInstantTarget(String url,
                              CompletionCallback completion,
                              ErrorCallback error)

Saves the current scene created by the InstantTracker.
The saved file can then be loaded as TargetCollectionResource using loadExistingInstantTarget(com.wikitude.tracker.TargetCollectionResource, com.wikitude.common.CompletionCallback, com.wikitude.common.ErrorCallback, com.wikitude.tracker.InstantTargetRestorationConfiguration).

This enables that AR experiences can be persistently accessed by multiple users across devices and operating systems.

This feature is not available with platform assisted tracking enabled. The callbacks will be invoked on an internal thread. To specify the Thread that should receive the callback use saveCurrentInstantTarget(String, CompletionCallback, ErrorCallback, Handler).

e.g.:

 String savedTargetPath = new File(getExternalFilesDir(null), "savedTarget.wto").getAbsolutePath();
 instantTracker.saveCurrentInstantTarget(savedTargetPath, () -> {}, (error) -> {});

 ...

 TargetCollectionResource resource = wikitudeSDK.getTrackerManager().createTargetCollectionResource(savedTargetPath);
 instantTracker.loadExistingInstantTarget(resource, () -> {}, (error) -> {}, new InstantTargetRestorationConfiguration());
 

Parameters:

url - the path where the target should be saved to. The folder has to exist and potential required permissions have to be granted.

completion - will be triggered when saving the target is done.

error - will be triggered when there was an issue when trying to save the target.

See Also:

CompletionCallback, ErrorCallback, saveCurrentInstantTarget(String, CompletionCallback, ErrorCallback, Handler), loadExistingInstantTarget(com.wikitude.tracker.TargetCollectionResource, com.wikitude.common.CompletionCallback, com.wikitude.common.ErrorCallback, com.wikitude.tracker.InstantTargetRestorationConfiguration)

saveCurrentInstantTarget

void saveCurrentInstantTarget(String url,
                              CompletionCallback completion,
                              ErrorCallback error,
                              android.os.Handler handler)

Saves the current scene created by the InstantTracker.
The saved file can then be loaded as TargetCollectionResource using loadExistingInstantTarget(com.wikitude.tracker.TargetCollectionResource, com.wikitude.common.CompletionCallback, com.wikitude.common.ErrorCallback, com.wikitude.tracker.InstantTargetRestorationConfiguration).
This enables that AR experiences can be persistently accessed by multiple users across devices and operating systems.

This feature is not available with platform assisted tracking enabled. e.g.:

 String savedTargetPath = new File(getExternalFilesDir(null), "savedTarget.wto").getAbsolutePath();
 instantTracker.saveCurrentInstantTarget(savedTargetPath, () -> {}, (error) -> {});

 ...

 TargetCollectionResource resource = wikitudeSDK.getTrackerManager().createTargetCollectionResource(savedTargetPath);
 instantTracker.loadExistingInstantTarget(resource, () -> {}, (error) -> {}, new InstantTargetRestorationConfiguration());
 

Parameters:

url - the path where the target should be saved to. The folder has to exist and potential required permissions have to be granted.

completion - will be triggered when saving the target is done.

error - will be triggered when there was an issue when trying to save the target.

handler - the handler used to deliver the callbacks to a specified thread.

See Also:

CompletionCallback, ErrorCallback, loadExistingInstantTarget(com.wikitude.tracker.TargetCollectionResource, com.wikitude.common.CompletionCallback, com.wikitude.common.ErrorCallback, com.wikitude.tracker.InstantTargetRestorationConfiguration)

loadExistingInstantTarget

void loadExistingInstantTarget(TargetCollectionResource targetCollectionResource,
                               CompletionCallback completion,
                               ErrorCallback error,
                               InstantTargetRestorationConfiguration configuration)

Loads the provided instant target and starts tracking it.
This feature is not available with platform assisted tracking enabled.
e.g.:

 String savedTargetPath = new File(getExternalFilesDir(null), "savedTarget.wto").getAbsolutePath();
 instantTracker.saveCurrentInstantTarget(savedTargetPath, () -> {}, (error) -> {});

 ...

 TargetCollectionResource resource = wikitudeSDK.getTrackerManager().createTargetCollectionResource(savedTargetPath);
 instantTracker.loadExistingInstantTarget(resource, () -> {}, (error) -> {}, new InstantTargetRestorationConfiguration());
 

Parameters:

targetCollectionResource - the file saved by saveCurrentInstantTarget(java.lang.String, com.wikitude.common.CompletionCallback, com.wikitude.common.ErrorCallback) as TargetCollectionResource.

completion - will be triggered when saving the target is done.

error - will be triggered when there was an issue when trying to save the target.

configuration - the configuration applied to the loaded instant target. The callbacks will be invoked on an internal thread. To specify the Thread that should receive the callback use loadExistingInstantTarget(TargetCollectionResource, CompletionCallback, ErrorCallback, InstantTargetRestorationConfiguration, Handler).

See Also:

CompletionCallback, ErrorCallback, InstantTargetRestorationConfiguration, saveCurrentInstantTarget(java.lang.String, com.wikitude.common.CompletionCallback, com.wikitude.common.ErrorCallback), loadExistingInstantTarget(TargetCollectionResource, CompletionCallback, ErrorCallback, InstantTargetRestorationConfiguration, Handler)

loadExistingInstantTarget

void loadExistingInstantTarget(TargetCollectionResource targetCollectionResource,
                               CompletionCallback completion,
                               ErrorCallback error,
                               InstantTargetRestorationConfiguration configuration,
                               android.os.Handler handler)

Loads the provided instant target and starts tracking it.
This feature is not available with platform assisted tracking enabled.
e.g.:

 String savedTargetPath = new File(getExternalFilesDir(null), "savedTarget.wto").getAbsolutePath();
 instantTracker.saveCurrentInstantTarget(savedTargetPath, () -> {}, (error) -> {});

 ...

 TargetCollectionResource resource = wikitudeSDK.getTrackerManager().createTargetCollectionResource(savedTargetPath);
 instantTracker.loadExistingInstantTarget(resource, () -> {}, (error) -> {}, new InstantTargetRestorationConfiguration());
 

Parameters:

targetCollectionResource - the file saved by saveCurrentInstantTarget(java.lang.String, com.wikitude.common.CompletionCallback, com.wikitude.common.ErrorCallback) as TargetCollectionResource.

completion - will be triggered when saving the target is done.

error - will be triggered when there was an issue when trying to save the target.

configuration - the configuration applied to the loaded instant target.

See Also:

CompletionCallback, ErrorCallback, InstantTargetRestorationConfiguration, saveCurrentInstantTarget(java.lang.String, com.wikitude.common.CompletionCallback, com.wikitude.common.ErrorCallback)