PositionalDeviceTracker Class Reference

Detailed Description

A type of DeviceTracker that tracks the world-relative position and rotation of the device.

The PositionalDeviceTracker tracks the device in the world based on the environment.

While this Tracker is running, the device's position and rotation are made available on the State class as a DeviceTrackableResult containing a 6DOF pose, specified in meters in the world coordinate system. The origin of the world coordinate system corresponds to the position and orientation of the device when tracking starts.

Extended Tracking

PositionalDeviceTracker also provides extended tracking functionality. As long as the PositionalDeviceTracker is running, previously detected Trackables will continue to report poses via the State class, even if they are no longer visible in the device's camera.

This assumes that the Trackable remains static relative to the user's environment. If the Trackable is moved while it is out of view of the camera, its pose will snap to its new location once it comes back into view of the camera and Vuforia re-detects it. For some Trackables, the detection distance may be closer than the tracking distance. You may need to move the camera closer than expected to the Trackable so that it updates its pose after it has moved.

You can use TrackableResult::getStatus() to determine whether a Trackable is being tracked directly or using extended tracking.

Initialization

The PositionalDeviceTracker may need some extra manual initialization steps on some devices, depending on the active Fusion provider (as returned by Vuforia::getActiveFusionProvider()).

• For FUSION_PROVIDER_PLATFORM_SENSOR_FUSION (which is the default for iOS devices that support ARKit, Android devices that support ARCore, and UWP devices that support Windows Holographic), the PositionalDeviceTracker will be initialized automatically.
• For FUSION_PROVIDER_VUFORIA_SENSOR_FUSION, the PositionalDeviceTracker will attempt to initialize automatically, but this requires some motion of the device. If the device is stationary, it will wait for sufficient motion before initialization is completed. You can use TrackableResult::getStatus() and TrackableResult::getStatusInfo() on the DeviceTrackableResult to determine whether the PositionalDeviceTracker is still initializing.
• For FUSION_PROVIDER_VUFORIA_VISION_ONLY, you need to initialize the PositionalDeviceTracker by detecting and tracking an ObjectTarget.

Inheritance diagram for PositionalDeviceTracker:

Public Member Functions
virtual Anchor *	createAnchor (const char *name, const Matrix34F &pose)=0
	Create a named Anchor with a particular world position and rotation. More...
virtual Anchor *	createAnchor (const char *name, const HitTestResult &hitTestResult)=0
	Create a named Anchor using the result of a hit test from a SmartTerrain. More...
virtual bool	destroyAnchor (Anchor *anchor)=0
	Destroy the given Anchor. More...
virtual List< Anchor >	getAnchors () const =0
	Get the list of anchors. More...
virtual bool	reset ()=0
	Reset the tracker. More...
Public Member Functions inherited from Tracker
virtual Type	getType () const =0
	Get the Type of this instance (may be a subclass of Tracker). More...
virtual bool	isOfType (Type type) const =0
	Get whether this Tracker instance's type equals or has been derived from the given type. More...
virtual bool	start ()=0
	Start the Tracker. More...
virtual void	stop ()=0
	Stop the Tracker. More...
virtual	~Tracker ()

Static Public Member Functions
static Type	getClassType ()
	Get the Type for class 'PositionalDeviceTracker'. More...
Static Public Member Functions inherited from DeviceTracker
static Type	getClassType ()
	Get the Type for class 'DeviceTracker'. More...
Static Public Member Functions inherited from Tracker
static Type	getClassType ()
	Get the Type for class 'Tracker'. More...

Member Function Documentation

static Type getClassType ( )

static

Get the Type for class 'PositionalDeviceTracker'.

virtual Anchor* createAnchor ( const char *  name, const Matrix34F &  pose  )

pure virtual

Create a named Anchor with a particular world position and rotation.

This method creates an Anchor at an arbitrary position and orientation in the world.

Depending on the active Fusion provider (see Vuforia::getActiveFusionProvider()), tracking of Anchors created with this method may be poor under certain conditions. For this reason, it is recommended that you only create Anchors using createAnchor(const char*, const HitTestResult&), rather than using this method. If you want to render something at an arbitrary position in the world, for example floating in the air, create a hit-test-based Anchor and then apply an offset transform in your application logic.

For platform-independent behavior, you should always create the first anchor from a HitTestResult.

To destroy an Anchor, call destroyAnchor(). Do not delete the pointer yourself. A call to reset() invalidates (destroys) all Anchors. Do not access the returned pointer after calling reset().

Note

Creating anchors is not supported if the active Fusion provider is FUSION_PROVIDER_VUFORIA_VISION_ONLY (see Vuforia::getActiveFusionProvider()).

If the active Fusion provider is FUSION_PROVIDER_VUFORIA_SENSOR_FUSION, extra steps are required to fully initialize the PositionalDeviceTracker before using this method. See the Initialization section in the class documentation above for more details.

When using FUSION_PROVIDER_VUFORIA_SENSOR_FUSION, reported Anchor poses may fluctuate at first, until Vuforia has learned enough about the environment to provide a stable pose estimate. This typically takes a few seconds after creating the first Anchor from a HitTestResult, depending on how the user moves their device.

When using FUSION_PROVIDER_VUFORIA_SENSOR_FUSION, Anchors created with this method are not guaranteed to receive any further position updates after the device tracker recovers from a limited tracking state.

Parameters

name	The name for the new anchor.
pose	The pose (position and orientation) for the anchor.

Returns

The newly created anchor, or NULL on failure (check application log for details).

virtual Anchor* createAnchor ( const char *  name, const HitTestResult &  hitTestResult  )

pure virtual

Create a named Anchor using the result of a hit test from a SmartTerrain.

This method is the preferred way to attach augmentations to arbitrary points in the user's environment. If you need the augmentation to appear somewhere other than the surface of the plane detected by the hit test, apply an offset transform in your application logic.

To destroy an Anchor, call destroyAnchor(). Do not delete the pointer yourself. A call to reset() invalidates (destroys) all Anchors. Do not access the returned pointer after calling reset().

Note

When using FUSION_PROVIDER_VUFORIA_SENSOR_FUSION, reported Anchor poses may fluctuate initially until Vuforia has learned enough about the environment to provide a stable pose estimate (typically until a few seconds after creating the first Anchor from a HitTestResult, depending on how the user moves their device).

Parameters

name	The name for the new Anchor.
hitTestResult	a HitTestResult as returned from SmartTerrain::hitTest(). The HitTestResult must not have been already used to create an Anchor.

Returns

The newly created Anchor, or NULL on failure (check application log for details).

virtual bool destroyAnchor ( Anchor *  anchor )

pure virtual

Destroy the given Anchor.

Deletes the given Anchor and cleans up all associated internal resources.

Do not access the pointer after calling this method.

Returns

true if destroyed successfully, false if the Anchor is invalid (e.g. null).

virtual List<Anchor> getAnchors ( ) const

pure virtual

Get the list of anchors.

virtual bool reset ( )

pure virtual

Reset the tracker.

Calling this function invalidates (destroys) all Anchors. Do not hold on to any existing Anchor pointers after calling this function.

Note

On some platforms a new world origin will be defined at the device's current position and orientation.

On some platforms the underlying Vuforia Fusion provider may also be reset.

Returns

true if the tracker was successfully reset, otherwise false (check application logs for failure details).