Image Targets API Overview

This article presents the basic functionality for using Image Targets in a native development environment.

An Image Target represents a planar 2D image that you can detect and track in the real world. An Image Target could for example be a magazine, cards, or a wall poster. Image Targets are generated with the Target Manager and stored in a device database from which you can download and create Observers from. Image Target Observers can also be created at runtime from a locally stored file or from the camera buffer.

For a general introduction to the key concepts of the Vuforia Engine API, please see Vuforia Engine 10 API. We also encourage you to try the samples that you are free to use as a foundation for your own AR application. See Native Samples for more information

General Setup

Please see the Vuforia Engine Lifecycle for a general introduction to the Vuforia Engine lifecycle. The Engine is required for creating and using Observers.

Create an Image Target Observer 

Detect and track images in the real world with an Image Target Observer created from a device database.

Image Target Observer from a device database 

// Create an Observer config 
VuImageTargetConfig imageTargetConfig = vuImageTargetConfigDefault(); 
imageTargetConfig.databasePath = "StonesAndChips.xml"; 
imageTargetConfig.targetName = "stones"; 

// Create an Image Target Observer 
VuObserver* imageTargetObserver = { NULL }; 
vuEngineCreateImageTargetObserver(engine, &imageTargetObserver, imageTargetConfig, NULL); 

The above code snippet creates an image Target Observer with default values. The databasePath and targetName must match a target and database. When an Image Target Observer is created, it is activated by default and will start tracking the image target upon detection.  

Configuring and creating an Observer with non-default additional optional arguments should be done while other Observers from the same database is deactivated to avoid performance overhead. 

Image Target Observer from a file 

Alternatively, an Image Target Observer can be created directly from a file, without needing to create a device database first. Use imageTargetConfig.path for loading the image and a valid targetName. See Instant Image Targets for more details. 

vuEngineCreateImageTargetObserverFromFileConfig(engine, &imageTargetObserver, imageTargetConfig, errorCode); 

Image Target Observer from an image buffer 

You can also choose to create an Image Target Observer from an image pixel buffer. To do this, the VuImageTargetBufferConfig needs to be configured with a pixelBuffer, bufferFormat, bufferSize, and targetName.

vuEngineCreateImageTargetObserverFromBufferConfig(engine, &imageTargetObserver, imageTargetConfig, errorCode); 

Observations 

The Image Target Observer produces Observations that is collected in the State. Get the State from the Engine and parse them to the ObservationTargetInfo. See the Observer and Observations article for more information on target and status info. 

Creation of Observation list 

// Get update from Engine via pull mechanism: get latest state 
VuState* state = NULL; 
vuEngineAcquireLatestState(engine, &state); 

// Create observation list 
VuObservationList* obsList = { NULL }; 
vuObservationListCreate(&obsList); 

// Get and parse image target observations list 
vuStateGetImageTargetObservations(state,obsList); 

Then, parse the observation list to get info on the target(s). 

int32_t listSize = 0; 
vuObservationListGetSize(obsList, &listSize); 

// Parse the Image Target list 
for (int i = 0; i < listSize; i++) 
{ 
    VuObservation* obs = { NULL }; 
    vuObservationListGetElement(obsList, i, &obs); 

    VuPoseInfo poseInfo; 
    vuObservationGetPoseInfo(obs, &poseInfo); 

    VuImageTargetObservationTargetInfo targetInfo; 
    vuImageTargetObservationGetTargetInfo(obs, &targetInfo); 

    if (poseInfo.poseStatus != OBSERVATION_POSE_STATUS_NO_POSE) 
    { 
        // Do something with poseInfo and targetInfo 
    } 
} 

Destroy Observer and Observation 

Destroy objects and processes after usage to free up memory. 

For Image Targets, you call the following to destroy the Image Target Observation and the Image Target Observer: 

Destroy ObservationList 

// Destroy observation list 
vuObservationListDestroy(obsList); 

Destroy the Observer 

// Destroy the observer 
vuObserverDestroy(imageTargetObserver); 

 

Configuring Image Targets

In this section, additional common configuration options for Image Target Observers are presented.

Size

Get the size (height and length) of an Image Target in meters.

vuImageTargetObserverGetTargetSize(const VuObserver* observer, VuVector2F* size);

Scale

Set the scale of an Image Target with a scale factor to one of the size values retrieved from GetTargetSize().

vuImageTargetObserverSetTargetScale(VuObserver* observer, float scale);

Bounding box

Use this function to get an axis-aligned bounding box of an Image Target from its respective Observer, and relative to the target’s frame of reference.

vuImageTargetObserverGetAABB(const VuObserver* observer, VuAABB* bbox);

To configure how many targets you wish to track simultaneously, please refer to Detect and Track Multiple Targets Simultaneously.