All Classes Files Functions Variables Typedefs Enumerations Enumerator Macros Modules Pages
Loading...
Searching...
No Matches
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

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

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
observerObserver handle
positionPosition (x, z) in target coordinate system (which is y-up).
horizontalAccuracyHorizontal 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
observerObserver handle
positionPosition (x, z) in target coordinate system (which is y-up).
horizontalAccuracyHorizontal 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
observerObserver handle
positionPosition (x, y, z) in target coordinate system (which is y-up).
horizontalAccuracyHorizontal accuracy (radial) of the position in meters. Must be positive.
verticalAccuracyVertical 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
observerObserver handle
requiresExternalPositionsGives 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.