Multi Targets API Overview¶

This article presents the basic configuration and lifecycle concepts for using Multi Targets.

For a general introduction to the key concepts of the Vuforia Engine API, please see Vuforia Engine API.

A Multi Target represents a geometric composition of images. You will need to design and set up the images with the Target Manager and save it in a device database from which you can load and create a Multi Target Observer from. We present below the general setup for using Multi Targets from a device database.

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 a Multi Target Observer¶

To track a Multi Target, you can create a Multi Target Observer from a device database. Before starting the Engine, you should configure and create your Observer.

Create a Multi Target Observer

// Create a Multi Target Observer config
VuMultiTargetConfig multiTargetConfig = vuMultiTargetConfigDefault();
multiTargetConfig.databasePath = "box.xml";
multiTargetConfig.targetName = "flakes";

// Create a Multi Target Observer
VuObserver* multiTargetObserver = { NULL };
vuEngineCreateMultiTargetObserver(engine, &multiTargetObserver, multiTargetConfig, NULL);

The above example creates a Multi Target Observer with default values. The databasePath and targetName must match a target and database. When a Multi Target Observer is created, it is activated by default.

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 constraints.

Observations¶

Each Multi Target Observer produces Observations that are collected in the State. Get the state from the Engine and parse them to the MultiTargetObservationTargetInfo. See the Observer and Observations article for more information on target info and status info.

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

// Get and parse multi target observations list
vuStateGetMultiTargetObservations(state,obsList);

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

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

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

    VuPoseInfo poseInfo;
    vuObservationGetPoseInfo(obs, &poseInfo);

    VuMultiTargetObservationTargetInfo targetInfo;
    vuMultiTargetObservationGetTargetInfo(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.

Please see Engine Lifecycle for more information on ending Vuforia processes in a timely fashion. For Multi Targets, you call the following to destroy the Multi Target Observation and the Multi Target Observer:

Destroy ObservationList

// Destroy observation list
vuObservationListDestroy(obsList);

Destroy the Observer

// Destroy the observer
vuObserverDestroy(multiTargetObserver);

Create Multi Targets from Parts¶

Alternative to creating Multi Target Observers for Multi Targets created with the target manager, you can create a Multi Target from a list of parts using the native API. A part is a standalone Image Target that can be positioned in a geometric shape with each other. Creating a Multi Target from parts can be done at runtime with vuEngineCreateMultiTargetObserverFromPartsConfig() from a list of parts by using and providing a VuMultiTargetPartsConfigVuMultiTargetPartConfigList. Parts can also be added or removed from an existing Multi Target with vuMultiTargetObserverAddPart() and vuMultiTargetObserverRemovePart().

Multi Target Observer parts require an Image Target as input for creating the Multi Target from parts. Adding to or removing from an existing Multi Target requires that the Image Targets are loaded from the same database as the one used for creating the Multi Target Observer.

NOTE: Multi Targets from parts is only available in the native C API and not in Unity. To create more complex Multi Targets that what is supported with the Target Manager, Configure a Multi Target in the Dataset XML.

Create Multi Target Observer

// Create a Multi Target Observer from parts config
VuMultiTargetPartConfigList parts = nullptr;
vuMultiTargetPartConfigListCreate(&parts);

VuMultiTargetPartsConfig multiTargetPartsConfig = vuMultiTargetPartsConfigDefault();
multiTargetPartsConfig.databasePath = "box.xml";
multiTargetPartsConfig.targetName = "newMultiTargetName";
multiTargetPartsConfig.parts = “Image_Target_from_same_database”; 

// Create a Multi Target Observer from parts
VuObserver* multiTargetFromPartsObserver = NULL;
vuEngineCreateMultiTargetObserverFromPartsConfig(engine, &multiTargetFromPartsObserver, multiTargetPartsConfig, NULL);

Similarly, a part can be added to an existing Multi Target. The part must be specified to one of the sides of the target. Adding a new part to a side of a Multi Target overrides the existing image.

// Create a Multi Target part config
VuMultiTargetPartConfig partConfig = vuMultiTargetPartConfigDefault();
partConfig.targetName = "Image_Target_from_same_database";

// Add a part to a Multi Target Observer
vuMultiTargetObserverAddPart(multiTargetFromPartsObserver, partConfig);

Remove a part of the Multi Target Observer with a pointer to the targetNameof the part.

vuMultiTargetObserverRemovePart(multiTargetFromPartsObserver, targetName);

Observations¶

Getting Observations from Multi Targets created from parts are performed in same way as demonstrated in the Multi Targets created with MultiTargetConfig section. However, if you so wish, the Observations can be specified to Multi Target from parts with API calls GetParts(), PartListGetSize(), and PartListGetElement().

Destroy PartsList and Part¶

Remember to destroy the list and ConfigList after usage.

Destroy ObservationList

// Destroy observation list
vuMultiTargetPartListDestroy(obsPartsList);

Destroy the ConfigList

// Destroy the part list
 vuMultiTargetPartConfigListDestroy(parts);

Configuring Multi Targets¶

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

Size¶

Get the sizes, height, length, and width of a Multi Target in meters.

vuMultiTargetObserverGetTargetSize(const VuObserver* observer, VuVector3F* size);

Scale¶

Setting the scale on Multi Targets is not supported.

Bounding box¶

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

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

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

Learn More¶

Image Targets

Cylinder Targets

VuMark

Detect and Track Multiple Targets Simultaneously

Vuforia Engine Lifecycle