Area Target Feature

Classes
struct	VuAreaTargetConfig
	Configuration for creating an Area Target observer. More...
struct	VuAreaTargetCloudConfig
	Configuration for creating an Area Target observer working with Cloud Area Target. More...
struct	VuAreaTargetObservationTargetInfo
	Target info for Area Target from its respective observation. More...

Enumerations
enum	VuAreaTargetCreationError : int32_t {   VU_AREA_TARGET_CREATION_ERROR_NONE = 0x0 ,   VU_AREA_TARGET_CREATION_ERROR_INTERNAL = 0x1 ,   VU_AREA_TARGET_CREATION_ERROR_AUTOACTIVATION_FAILED ,   VU_AREA_TARGET_CREATION_ERROR_FEATURE_NOT_SUPPORTED = 0x3 ,   VU_AREA_TARGET_CREATION_ERROR_INVALID_DEVICE_POSE_OBSERVER = 0x4 ,   VU_AREA_TARGET_CREATION_ERROR_DATABASE_LOAD_ERROR = 0x5 ,   VU_AREA_TARGET_CREATION_ERROR_INVALID_TARGET_NAME = 0x6 ,   VU_AREA_TARGET_CREATION_ERROR_TARGET_NOT_FOUND ,   VU_AREA_TARGET_CREATION_ERROR_REQUIRES_EXTERNAL_POSITIONS = 0x8 }
	Configuration error for Area Target creation from VuAreaTargetConfig. More...
enum	VuAreaTargetCloudCreationError : int32_t {   VU_AREA_TARGET_CLOUD_CREATION_ERROR_NONE = 0x0 ,   VU_AREA_TARGET_CLOUD_CREATION_ERROR_INTERNAL = 0x1 ,   VU_AREA_TARGET_CLOUD_CREATION_ERROR_AUTOACTIVATION_FAILED ,   VU_AREA_TARGET_CLOUD_CREATION_ERROR_FEATURE_NOT_SUPPORTED = 0x3 ,   VU_AREA_TARGET_CLOUD_CREATION_ERROR_TARGET_NOT_FOUND = 0x4 ,   VU_AREA_TARGET_CLOUD_CREATION_ERROR_REQUIRES_EXTERNAL_POSITIONS ,   VU_AREA_TARGET_CLOUD_CREATION_ERROR_AUTHENTICATION_FAILED ,   VU_AREA_TARGET_CLOUD_CREATION_ERROR_NETWORK_TIMEOUT = 0x7 ,   VU_AREA_TARGET_CLOUD_CREATION_ERROR_NETWORK_CERTIFICATE_ERROR ,   VU_AREA_TARGET_CLOUD_CREATION_ERROR_NETWORK_DOMAIN_NAME_RESOLUTION_FAILED ,   VU_AREA_TARGET_CLOUD_CREATION_ERROR_NO_NETWORK_CONNECTION = 0xA ,   VU_AREA_TARGET_CLOUD_CREATION_ERROR_NETWORK_ERROR = 0xB ,   VU_AREA_TARGET_CLOUD_CREATION_ERROR_TARGET_NOT_READY ,   VU_AREA_TARGET_CLOUD_CREATION_ERROR_SERVICE_NOT_AVAILABLE ,   VU_AREA_TARGET_CLOUD_CREATION_ERROR_SAME_SOURCE_NOT_SUPPORTED ,   VU_AREA_TARGET_CLOUD_CREATION_ERROR_INVALID_DEVICE_POSE_OBSERVER = 0xF }
	Configuration error for Area Target creation from VuAreaTargetCloudConfig. More...
enum	VuAreaTargetObservationStatusInfo : int32_t {   VU_AREA_TARGET_OBSERVATION_STATUS_INFO_NORMAL ,   VU_AREA_TARGET_OBSERVATION_STATUS_INFO_NOT_OBSERVED ,   VU_AREA_TARGET_OBSERVATION_STATUS_INFO_RELOCALIZING ,   VU_AREA_TARGET_OBSERVATION_STATUS_INFO_MISSING_DATA }
	Status info for the pose of Area Target observations. More...
enum	{ VU_OBSERVER_AREA_TARGET_TYPE = 0x7 }
enum	{ VU_OBSERVATION_AREA_TARGET_TYPE = 0x7 }

Functions
VuAreaTargetConfig	vuAreaTargetConfigDefault ()
	Default Area Target configuration.
VuAreaTargetCloudConfig	vuAreaTargetCloudConfigDefault ()
	Default Area Target Cloud configuration.
VuResult	vuEngineCreateAreaTargetObserver (VuEngine *engine, VuObserver **observer, const VuAreaTargetConfig *config, VuAreaTargetCreationError *errorCode)
	Create an Area Target observer from database.
VuResult	vuEngineCreateAreaTargetObserverFromCloudConfig (VuEngine *engine, VuObserver **observer, const VuAreaTargetCloudConfig *config, VuAreaTargetCloudCreationError *errorCode)
	Create an Area Target observer for a Cloud Area Target.
VuResult	vuEngineGetAreaTargetObservers (const VuEngine *engine, VuObserverList *observerList)
	Get all Area Target observers.
VuResult	vuAreaTargetObserverGetTargetUniqueId (const VuObserver *observer, const char **targetId)
	Get the unique ID associated to the target from an Area Target observer.
VuResult	vuAreaTargetObserverGetTargetName (const VuObserver *observer, const char **targetName)
	Get the name associated to the target from an Area Target observer.
VuResult	vuAreaTargetObserverGetTargetSize (const VuObserver *observer, VuVector3F *size)
	Get the size in meters associated to the target from an Area Target observer.
VuResult	vuAreaTargetObserverGetTargetPoseOffset (const VuObserver *observer, VuMatrix44F *offset)
	Get the pose transformation offset associated to the target from an Area Target observer.
VuResult	vuAreaTargetObserverSetTargetPoseOffset (VuObserver *observer, const VuMatrix44F *poseOffset)
	Set the pose transformation offset associated to the target from an Area Target observer.
VuResult	vuAreaTargetObserverGetAABB (const VuObserver *observer, VuAABB *bbox)
	Get the axis-aligned bounding box associated to the target from an Area Target observer, relative to the target's frame of reference.
VuResult	vuAreaTargetObserverSetExternalPosition (VuObserver *observer, VuVector2F position, float horizontalAccuracy)
	Set approximate 2D position within an Area Target from an external localization source (DEPRECATED)
VuResult	vuAreaTargetObserverSetExternalPositionFrom2D (VuObserver *observer, VuVector2F position, float horizontalAccuracy)
	Set approximate 2D position within an Area Target from an external localization source.
VuResult	vuAreaTargetObserverSetExternalPositionFrom3D (VuObserver *observer, VuVector3F position, float horizontalAccuracy, float verticalAccuracy)
	Set approximate 3D position within an Area Target from an external localization source.
VuResult	vuAreaTargetObserverRequiresExternalPositions (const VuObserver *observer, VuBool *requiresExternalPositions)
	Check whether the target requires external positions for initial detection.
VuResult	vuStateGetAreaTargetObservations (const VuState *state, VuObservationList *observationList)
	Get all Area Target observations.
VuResult	vuAreaTargetObservationGetStatusInfo (const VuObservation *observation, VuAreaTargetObservationStatusInfo *statusInfo)
	Get status info associated to the pose status of an Area Target observation.
VuResult	vuAreaTargetObservationGetTargetInfo (const VuObservation *observation, VuAreaTargetObservationTargetInfo *targetInfo)
	Get target info associated with an Area Target observation.
VuResult	vuEngineClearAreaTargetObserverCloudCache (VuEngine *engine)
	Remove all data cached by Area Target observers.

Detailed Description

Enumeration Type Documentation

VuAreaTargetCreationError

enum VuAreaTargetCreationError : int32_t

Configuration error for Area Target creation from VuAreaTargetConfig.

Enumerator
VU_AREA_TARGET_CREATION_ERROR_NONE	No error.
VU_AREA_TARGET_CREATION_ERROR_INTERNAL	An internal error occurred while creating the observer.
VU_AREA_TARGET_CREATION_ERROR_AUTOACTIVATION_FAILED	Observer auto-activation failed (probably due to the total target size limit)
VU_AREA_TARGET_CREATION_ERROR_FEATURE_NOT_SUPPORTED	Feature not supported (e.g. if Vuforia is not running on a platform-based Fusion Provider such as ARKit, ARCore)
VU_AREA_TARGET_CREATION_ERROR_INVALID_DEVICE_POSE_OBSERVER	Device pose observer is null or invalid.
VU_AREA_TARGET_CREATION_ERROR_DATABASE_LOAD_ERROR	Database file not found or an error occurred when reading data from it (potentially unknown or corrupted file)
VU_AREA_TARGET_CREATION_ERROR_INVALID_TARGET_NAME	Invalid target name.
VU_AREA_TARGET_CREATION_ERROR_TARGET_NOT_FOUND	Target with the specified name AND matching target type for this observer not found in database.
VU_AREA_TARGET_CREATION_ERROR_REQUIRES_EXTERNAL_POSITIONS	This target does not support the default loading and detection behavior. The requireExternalPositions option in VuAreaTargetConfig must be set to VU_TRUE to use this target.

VuAreaTargetCloudCreationError

enum VuAreaTargetCloudCreationError : int32_t

Configuration error for Area Target creation from VuAreaTargetCloudConfig.

Enumerator
VU_AREA_TARGET_CLOUD_CREATION_ERROR_NONE	No error.
VU_AREA_TARGET_CLOUD_CREATION_ERROR_INTERNAL	An internal error occurred while creating the observer.
VU_AREA_TARGET_CLOUD_CREATION_ERROR_AUTOACTIVATION_FAILED	Observer auto-activation failed (probably due to the total target size limit)
VU_AREA_TARGET_CLOUD_CREATION_ERROR_FEATURE_NOT_SUPPORTED	Feature not supported (e.g. if Vuforia is not running on a platform-based Fusion Provider such as ARKit, ARCore)
VU_AREA_TARGET_CLOUD_CREATION_ERROR_TARGET_NOT_FOUND	Cloud Area Target under the given targetId was not found.
VU_AREA_TARGET_CLOUD_CREATION_ERROR_REQUIRES_EXTERNAL_POSITIONS	This target does not support the default loading and detection behavior. The requireExternalPositions option in VuAreaTargetCloudConfig must be set to VU_TRUE to use this target.
VU_AREA_TARGET_CLOUD_CREATION_ERROR_AUTHENTICATION_FAILED	Failed to authenticate with the Cloud Area Target service. Verify the provided credentials.
VU_AREA_TARGET_CLOUD_CREATION_ERROR_NETWORK_TIMEOUT	A request time out occured while we tried to contact the server.
VU_AREA_TARGET_CLOUD_CREATION_ERROR_NETWORK_CERTIFICATE_ERROR	A certificate error occured while establishing a secure connection.
VU_AREA_TARGET_CLOUD_CREATION_ERROR_NETWORK_DOMAIN_NAME_RESOLUTION_FAILED	A domain name resolution via the DNS service failed.
VU_AREA_TARGET_CLOUD_CREATION_ERROR_NO_NETWORK_CONNECTION	Device has no connection to the internet.
VU_AREA_TARGET_CLOUD_CREATION_ERROR_NETWORK_ERROR	Communication with the server failed for other reason (not listed here). Consult the device network status or device logs for further details.
VU_AREA_TARGET_CLOUD_CREATION_ERROR_TARGET_NOT_READY	The target is not in "ready" status. The target is likely still generating. Try again later.
VU_AREA_TARGET_CLOUD_CREATION_ERROR_SERVICE_NOT_AVAILABLE	Vuforia Engine Cloud services are not available at this moment. Please try again later.
VU_AREA_TARGET_CLOUD_CREATION_ERROR_SAME_SOURCE_NOT_SUPPORTED	Area target observer for this Cloud Area Target ID already exists.
VU_AREA_TARGET_CLOUD_CREATION_ERROR_INVALID_DEVICE_POSE_OBSERVER	Device pose observer is null or invalid.

VuAreaTargetObservationStatusInfo

enum VuAreaTargetObservationStatusInfo : int32_t

Status info for the pose of Area Target observations.

Provides further information on the pose status reported as part of VuPoseInfo. The status info is retrieved with vuAreaTargetObservationGetStatusInfo.

Note

All enum values defined by VuObservationPoseStatus may be reported as part of an Area Target observation, except VU_OBSERVATION_POSE_STATUS_TRACKED.

See also

VuPoseInfo

VuObservationPoseStatus

vuObservationHasPoseInfo

vuObservationGetPoseInfo

vuStateGetObservationsWithPoseInfo

vuAreaTargetObservationGetStatusInfo

Enumerator
VU_AREA_TARGET_OBSERVATION_STATUS_INFO_NORMAL	Tracking is working normally. Reported for VU_OBSERVATION_POSE_STATUS_EXTENDED_TRACKED.
VU_AREA_TARGET_OBSERVATION_STATUS_INFO_NOT_OBSERVED	Target is not observed. Reported for VU_OBSERVATION_POSE_STATUS_NO_POSE.
VU_AREA_TARGET_OBSERVATION_STATUS_INFO_RELOCALIZING	The tracking system is currently relocalizing. Reported for VU_OBSERVATION_POSE_STATUS_LIMITED.
VU_AREA_TARGET_OBSERVATION_STATUS_INFO_MISSING_DATA	Asynchronous loading of the tracking data failed. Tracking quality might decrease or the tracking might be lost. Reported for VU_OBSERVATION_POSE_STATUS_LIMITED.

anonymous enum

anonymous enum

Enumerator
VU_OBSERVER_AREA_TARGET_TYPE	Type identifier for Area Target observers.

anonymous enum

anonymous enum

Enumerator
VU_OBSERVATION_AREA_TARGET_TYPE	Type identifier for Area Target observations.

Function Documentation

vuAreaTargetConfigDefault()

VuAreaTargetConfig vuAreaTargetConfigDefault

(

)

Default Area Target configuration.

Note

Use this function to initialize the VuAreaTargetConfig data structure with default values.

vuAreaTargetCloudConfigDefault()

VuAreaTargetCloudConfig vuAreaTargetCloudConfigDefault

(

)

Default Area Target Cloud configuration.

Note

Use this function to initialize the VuAreaTargetCloudConfig data structure with default values.

vuEngineCreateAreaTargetObserver()

VuResult vuEngineCreateAreaTargetObserver	(	VuEngine *	engine,
		VuObserver **	observer,
		const VuAreaTargetConfig *	config,
		VuAreaTargetCreationError *	errorCode )

Create an Area Target observer from database.

Note

Note that loading the database may take a significant amount of time, it is therefore recommended that this method is not called on the main/UI thread.

vuEngineCreateAreaTargetObserverFromCloudConfig()

VuResult vuEngineCreateAreaTargetObserverFromCloudConfig	(	VuEngine *	engine,
		VuObserver **	observer,
		const VuAreaTargetCloudConfig *	config,
		VuAreaTargetCloudCreationError *	errorCode )

Create an Area Target observer for a Cloud Area Target.

The Area Target observer will store certain data of Cloud Area Targets locally to improve the experience and optimize the number of network transfers. The target data will be stored in a platform-specific cache directory that may persist across Vuforia Engine sessions. The system may delete the cache directory to free up disk space, but outside these relatively rare events the data will be persistent.

Use vuEngineClearAreaTargetObserverCloudCache to delete this cache directory manually when the stored Cloud Area Target data is no longer needed.

Note

Note that loading the database may take a significant amount of time, it is therefore recommended that this method is not called on the main/UI thread.

vuAreaTargetObserverGetTargetPoseOffset()

VuResult vuAreaTargetObserverGetTargetPoseOffset	(	const VuObserver *	observer,
		VuMatrix44F *	offset )

Get the pose transformation offset associated to the target from an Area Target observer.

Note

The offset is represented as a pose matrix using the OpenGL convention.

vuAreaTargetObserverSetTargetPoseOffset()

VuResult vuAreaTargetObserverSetTargetPoseOffset	(	VuObserver *	observer,
		const VuMatrix44F *	poseOffset )

Set the pose transformation offset associated to the target from an Area Target observer.

Note

The offset is represented as a pose matrix using the OpenGL convention.

vuAreaTargetObserverSetExternalPosition()

VuResult vuAreaTargetObserverSetExternalPosition	(	VuObserver *	observer,
		VuVector2F	position,
		float	horizontalAccuracy )

Set approximate 2D position within an Area Target from an external localization source (DEPRECATED)

Deprecated

This function has been deprecated. It will be removed in an upcoming Vuforia release. Please use vuAreaTargetObserverSetExternalPositionFrom2D() instead.

Setting up the external position only succeeds when the target is activated.

Note

The provided external position is valid until a successful localization, target deactivation, or updating the external position by a repeated call to this function or any of the other vuAreaTargetObserverSetExternalPosition functions (whichever happens first).

Parameters

observer	Observer handle
position	Position (x, z) in target coordinate system (which is y-up).
horizontalAccuracy	Horizontal accuracy (radial) of the position in meters. Must be positive.

Returns

VU_SUCCESS on success, VU_FAILED on failure.

vuAreaTargetObserverSetExternalPositionFrom2D()

VuResult vuAreaTargetObserverSetExternalPositionFrom2D	(	VuObserver *	observer,
		VuVector2F	position,
		float	horizontalAccuracy )

Set approximate 2D position within an Area Target from an external localization source.

Setting up the external position only succeeds when the target is activated.

Note

The provided external position is valid until a successful localization, target deactivation, or updating the external position by a repeated call to this function or any of the other vuAreaTargetObserverSetExternalPosition functions (whichever happens first).

Parameters

observer	Observer handle
position	Position (x, z) in target coordinate system (which is y-up).
horizontalAccuracy	Horizontal accuracy (radial) of the position in meters. Must be positive.

Returns

VU_SUCCESS on success, VU_FAILED on failure.

vuAreaTargetObserverSetExternalPositionFrom3D()

VuResult vuAreaTargetObserverSetExternalPositionFrom3D	(	VuObserver *	observer,
		VuVector3F	position,
		float	horizontalAccuracy,
		float	verticalAccuracy )

Set approximate 3D position within an Area Target from an external localization source.

Setting up the external position only succeeds when the target is activated.

Note

The provided external position is valid until a successful localization, target deactivation, or updating the external position by a repeated call to this function or any of the other vuAreaTargetObserverSetExternalPosition functions (whichever happens first).

Parameters

observer	Observer handle
position	Position (x, y, z) in target coordinate system (which is y-up).
horizontalAccuracy	Horizontal accuracy (radial) of the position in meters. Must be positive.
verticalAccuracy	Vertical accuracy of the position in meters. Must be positive.

Returns

VU_SUCCESS on success, VU_FAILED on failure.

vuAreaTargetObserverRequiresExternalPositions()

VuResult vuAreaTargetObserverRequiresExternalPositions	(	const VuObserver *	observer,
		VuBool *	requiresExternalPositions )

Check whether the target requires external positions for initial detection.

Checks the value of the requireExternalPositions option in VuAreaTargetConfig. If a target requires external positions, then it will not be detected until an external position is provided. This is also the case after an extended loss of tracking, e.g. after pausing the app and moving to a new location.

Note

The external position should be set using either vuAreaTargetObserverSetExternalPositionFrom2D() or vuAreaTargetObserverSetExternalPositionFrom3D().

Parameters

observer	Observer handle
requiresExternalPositions	Gives VU_TRUE if the target needs external positions for initial detection or after extended loss of tracking, VU_FALSE otherwise.

Returns

VU_SUCCESS on success, VU_FAILED on failure.

vuAreaTargetObservationGetStatusInfo()

VuResult vuAreaTargetObservationGetStatusInfo	(	const VuObservation *	observation,
		VuAreaTargetObservationStatusInfo *	statusInfo )

Get status info associated to the pose status of an Area Target observation.

The status info is intended to be used in combination with VuObservationPoseStatus retrieved via vuObservationGetPoseInfo.

vuEngineClearAreaTargetObserverCloudCache()

VuResult vuEngineClearAreaTargetObserverCloudCache

(

VuEngine *

engine

)

Remove all data cached by Area Target observers.

Use this function to decrease the disk space usage by removing all Cloud Area Target data cached by Area Target observer.

Note

If there is any Area Target observer in the given Vuforia Engine instance this function will fail.

Note that clearing the cache may take a significant amount of time, it is therefore recommended that this method is not called on the main/UI thread.