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.