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 

12345678
Copy
// 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. 

1
Copy
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.

1
Copy
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 

12345678910
Copy
// 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). 

1234567891011121314151617181920
Copy
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 

12
Copy
// Destroy observation list vuObservationListDestroy(obsList);

Destroy the Observer 

12
Copy
// 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.

1
Copy
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().

1
Copy
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.

1
Copy
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.

Can this page be better?
Share your feedback via our issue tracker