Observer and Observation Management

Classes
struct	VuPoseInfo
	Information about pose-specific data in an observation with a pose. More...

Typedefs
typedef struct VuObserver_	VuObserver
	Vuforia Observer handle.
typedef int32_t	VuObserverType
	Observer type.
typedef struct VuObserverList_	VuObserverList
	Vuforia ObserverList handle.
typedef struct VuObservation_	VuObservation
	Vuforia Observation handle.
typedef int32_t	VuObservationType
	Observation type.
typedef struct VuObservationList_	VuObservationList
	Vuforia ObservationList handle.

Enumerations
enum	VuTrackingOptimization : int32_t {   VU_TRACKING_OPTIMIZATION_DEFAULT = 0x1,   VU_TRACKING_OPTIMIZATION_LOW_FEATURE_OBJECTS = 0x2,   VU_TRACKING_OPTIMIZATION_AR_CONTROLLER = 0x3 }
	Tracking optimization types. More...
enum	VuObservationPoseStatus : int32_t {   VU_OBSERVATION_POSE_STATUS_NO_POSE = 0x1,   VU_OBSERVATION_POSE_STATUS_LIMITED = 0x2,   VU_OBSERVATION_POSE_STATUS_TRACKED = 0x3,   VU_OBSERVATION_POSE_STATUS_EXTENDED_TRACKED = 0x4 }
	Observation pose status. More...

Functions
int32_t	vuObserverGetId (const VuObserver *observer)
	Get a unique ID associated with an observer. More...
VuResult	vuObserverGetType (const VuObserver *observer, VuObserverType *observerType)
	Get the type of an observer.
VuBool	vuObserverIsType (const VuObserver *observer, VuObserverType observerType)
	Check the type of an observer.
VuResult	vuObserverListCreate (VuObserverList **list)
	Create an observer list.
VuResult	vuObserverListGetSize (const VuObserverList *list, int32_t *listSize)
	Get number of elements in an observer list.
VuResult	vuObserverListGetElement (const VuObserverList *list, int32_t element, VuObserver **observer)
	Get an element in an observer list.
VuResult	vuObserverListDestroy (VuObserverList *list)
	Destroy an observer list.
VuResult	vuEngineGetObserver (const VuEngine *engine, int32_t observerId, VuObserver **observer)
	Get an observer from Vuforia Engine using its unique ID.
VuResult	vuEngineGetObservers (const VuEngine *engine, VuObserverList *observerList)
	Get all observers from Vuforia Engine.
VuResult	vuObserverDestroy (VuObserver *observer)
	Destroy an observer.
VuResult	vuObserversDestroy (VuObserverList *observerList)
	Destroy multiple observers.
VuResult	vuEngineDestroyObservers (VuEngine *engine)
	Destroy all observers in Vuforia Engine.
VuResult	vuObserverActivate (VuObserver *observer)
	Activate an observer.
VuResult	vuObserverDeactivate (VuObserver *observer)
	Deactivate an observer.
VuBool	vuObserverIsActivated (const VuObserver *observer)
	Check whether an observer is activated. More...
VuResult	vuObservationGetType (const VuObservation *observation, VuObservationType *observationType)
	Get the type of an observation.
VuBool	vuObservationIsType (const VuObservation *observation, VuObservationType observationType)
	Check the type of an observation.
int32_t	vuObservationGetObserverId (const VuObservation *observation)
	Get ID of the observer which has created given observation.
VuBool	vuObservationHasPoseInfo (const VuObservation *observation)
	Check whether an observation contains pose information.
VuResult	vuObservationGetPoseInfo (const VuObservation *observation, VuPoseInfo *poseInfo)
	Get pose info associated to an observation (for observation having pose, see availability for each observer) More...
VuResult	vuObservationListCreate (VuObservationList **list)
	Create an observation list.
VuResult	vuObservationListGetSize (const VuObservationList *list, int32_t *listSize)
	Get number of elements in an observation list.
VuResult	vuObservationListGetElement (const VuObservationList *list, int32_t element, VuObservation **observation)
	Get an element in an observation list.
VuResult	vuObservationListDestroy (VuObservationList *list)
	Destroy an observation list.

Detailed Description

Observers are created by observer-specific creation functions consuming an observer-specific configuration data stucture Vu<ObserverType>Config, typically with the following signature:

VuResult vuEngineCreate<ObserverType>Observer(VuEngine* engine, VuObserver** observer, const Vu<ObserverType>Config* config, Vu<ObserverType>CreationError* errorCode);

The configuration data structure can be initialized with default parameters with a dedicated function vu<ObserverType>ConfigDefault(), and can be customized with desired settings. When creation fails, the creation function outputs an observer-specific error code of type Vu<ObserverType>CreationError.

The observer-specific configurations have a field of type VuBool called activate, which determines whether observer-internal resources should be activated automatically upon creation, or they require explicit activation by calling vuObserverActivate(). All observers are automatically deactivated when stopping the Vuforia Engine via vuEngineStop(), or they can be deactivated individually by calling vuObserverDeactivate().

If an observer is configured to be automatically activated on creation and the activation fails, then the errorCode parameter supplied to the observer creation function (e.g. vuEngineCreate<ObserverType>Observer()) is set to VU_<OBSERVER_TYPE>_CREATION_ERROR_AUTOACTIVATION_FAILED for all observer types where applicable.

Individual observers can be destroyed with the general vuObserverDestroy() function. A list of observers can be destroyed by calling vuObserversDestroy() with a VuObserverList. Neither of the destruction functions are observer-specific, unlike the observer creation functions.

Note that for modification of observers (vu<ObserverType>ObserverSet<Property>()) or for creation of observers with non-default optional arguments (for example "scale") it is recommended that all observers from the same database are deactivated as these operations can be expensive otherwise - especially when the database contains a large amount of targets.

Enumeration Type Documentation

VuTrackingOptimization

enum VuTrackingOptimization : int32_t

Tracking optimization types.

Enumerator
VU_TRACKING_OPTIMIZATION_DEFAULT	Best tracking performance for the majority of use cases and targets.
VU_TRACKING_OPTIMIZATION_LOW_FEATURE_OBJECTS	Optimize tracking for objects with smooth, untextured surfaces, that lack features and detailed structures, including cars, sheet metal parts and many industrial objects. Note Do not use for objects that move while being tracked.
VU_TRACKING_OPTIMIZATION_AR_CONTROLLER	Optimize tracking for use cases where small, handheld fast moving targets are used like an AR/VR controller. Tracking will be less stable if the object is stationary.

VuObservationPoseStatus

enum VuObservationPoseStatus : int32_t

Observation pose status.

Enumerator
VU_OBSERVATION_POSE_STATUS_NO_POSE	No valid pose available. For details refer to the status info. The NOT_OBSERVED status info is returned if an observed object is currently not being tracked. Some observers may provide additional information for NO_POSE in their status info.
VU_OBSERVATION_POSE_STATUS_LIMITED	Observed object is being tracked in a limited form, and so the pose may be unreliable or degraded. For details refer to the status info
VU_OBSERVATION_POSE_STATUS_TRACKED	Observed object is being tracked with a valid pose.
VU_OBSERVATION_POSE_STATUS_EXTENDED_TRACKED	Observed object is being tracked using extended tracking.

Function Documentation

vuObserverGetId()

int32_t vuObserverGetId

(

const VuObserver *

observer

)

Get a unique ID associated with an observer.

The ID is a positive number and is unique within a Vuforia session. It is generated at runtime and is not persistent across Vuforia sessions

vuObserverIsActivated()

VuBool vuObserverIsActivated

(

const VuObserver *

observer

)

Check whether an observer is activated.

Returns

VU_TRUE if the observer is activated, VU_FALSE if the observer is not activated

vuObservationGetPoseInfo()

VuResult vuObservationGetPoseInfo	(	const VuObservation *	observation,
		VuPoseInfo *	poseInfo
	)

Get pose info associated to an observation (for observation having pose, see availability for each observer)

Note

This call fails if the observation does not contain pose information. You can verify this by calling vuObservationHasPoseInfo() and checking its return value: VU_TRUE for an observation with pose information, VU_FALSE without.