Object Targets API Overview

This article presents the basic configuration options for using Object Targets.

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

An Object Target is a digital representation of a physical object that is obtained from a scan. It is particular suitable for smaller objects that has a rich texture. An Object Target is created by using the Vuforia Object Scanner. The scan is uploaded to the Target Manager from where a device database with the Object Target can be downloaded. Object Targets are tracked with Object Target Observers.

General Setup

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

Create Object Target Observers

Detect and track objects made from the Object Scanner with the Object Target Observer. Use a device database containing an Object Target and configure and create an Observer from it. This should be done before starting the Engine.

// Create an Observer config
VuObjectTargetConfig objectTargetConfig = vuObjectTargetConfigDefault();
objectTargetConfig.databasePath = "habitat.xml";
objectTargetConfig.targetName = "habitat";

// Create an Object Target Observer
VuObserver* objectTargetObserver = { NULL };
vuEngineCreateObjectTargetObserver(engine, &objectTargetObserver, objectTargetConfig, NULL);

The above code snippet creates an Object Target Observer with default values. The databasePath and targetName must match a target and a database. When an Object 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

The Object Target Observer produces Observations that is collected in the State. Get the state from the Engine and parse it to the VuObjectTargetObservationTargetInfo. See the Observer and Observations article for more information.

Creation of Observation list

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

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

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

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

    VuPoseInfo poseInfo;
    vuObservationGetPoseInfo(obs, &poseInfo);

    VuObjectTargetObservationTargetInfo targetInfo;
    vuObjectTargetObservationGetTargetInfo(obs, &targetInfo);

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

Destroy Observer and Observations

Destroy objects and processes after usage to free up memory.

Destroy the Object Target Observer

// Destroy the observer
vuObserverDestroy(objectTargetObserver);

Destroy ObservationList

// Destroy observation list
vuObservationListDestroy(obsList);

Configuring Object Targets

In this section, we present additional common configuration options for Object Target Observers.

Size

Get the sizes, height, length, and width of an Object Target in meters.

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

Scale

Re-scale the Object Target with a scale factor applied to one of the dimensions retrieved from the GetTargetSize().

vuObjectTargetObserverSetTargetScale(VuObserver* observer, float scale);

Bounding Box

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

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

Delayed initialization

In particular cases where your Object Target database is large, we recommend setting a delay for loading the Object Targets. A delayed loading will reduce the time to load large objects but will increase the initial detection time of the Object Target. The delay should be set before loading any Object Target database. Its default value is VU_FALSE.

vuEngineGetObjectTargetsDelayedLoading(const VuEngine* engine, VuBool* delayedLoading);
vuEngineSetObjectTargetsDelayedLoading(VuEngine* engine, VuBool delayedLoading);

Set simultaneous tracking for Object Targets

VuEngineGetMaximumSimultaneousObjectTargets(const VuEngine* engine, int32_t* maxNumberOfTargets);

For more information on how many targets you can track simultaneously, please refer to Detect and Track Multiple Targets Simultaneously.