This page concerns the Vuforia Engine API version 9.8 and earlier. It has been deprecated and will no longer be actively updated.
Vuforia supports a variety of objects that can be initialized and activated as datasets. The ObjectTracker tracks these targets in your physical environment. Place augmentations on posters and 3D objects alike by using the same ObjectTracker for your AR experiences. This article provides an overview of the ObjectTracker API and its related components.
The type of objects supported by ObjectTracker, and represented as Trackables, are:
- Cylinder Targets
- Image Targets
- Model Targets
- Multi Targets
- VuMark Targets (+Templates)
Objects can be packaged together, in what we define as a DataSet. All these objects inherit from a base class, named ObjectTarget.
Class definitions:
The relationships of the ObjectTracker are as follows:
- ObjectTracker tracks one or multiple ObjectTargets (or subclasses).
- ObjectTracker produces an ObjectTargetResult, which can be specialized for the different target types.
- The ObjectTarget reports through TrackableResult which provide information on the state of the trackable.
ObjectTracker
The ObjectTracker allows you to create, destroy, initialize and deactivate DataSets.
Initialization of ObjectTracker in native Code:
TrackerManager &
trackerManager = TrackerManager::getInstance();
ObjectTracker *objectTracker = static_cast & lt;
ObjectTracker *>
(trackerManager.initTracker(
Vuforia::ObjectTracker::getClassType()));
Destroy the ObjectTracker
TrackerManager &
trackerManager = TrackerManager::getInstance();
trackerManager.deinitTracker(Vuforia::ObjectTracker::getClassType());
Start the ObjectTracker
objectTracker->start();
Stop the ObjectTracker
objectTracker->stop();
ObjectTarget
The ObjectTarget class represents a unified target definition for the ObjectTracker. All targets tracked by the ObjectTracker are specializations of ObjectTarget.
The ObjectTarget class provides parent properties such as the size of the target (3D Vector), therefore this property is valid for any specialized target type. It offers a simple way for developers to get the size of any ObjectTracker’s trackable (or its name), without considering their specific type, which is useful for parsing results generically.
The size property can be seen as the bounding box of any of the existing objects. Size needs to be defined in meter units.
- For ImageTarget, a 2D digital representation of an image, the last component of the size vector will be 0 (a flat object).
- For CylinderTarget, the size will be computed based on existing procedural parameters (e.g. side-length, diameter, etc).
- For MultiTarget, size is currently not supported.
- For ModelTarget, a bounding box defines its size which can be uniformly scaled by using
setSize().
A motion hint can be set through the ObjectTarget which can help improve the tracking experience. The motion hint can be used to achieve the optimal tracking performance for your user scenario. Set the motion hint to either STATIC for stationary targets or ADAPTIVE for targets that are likely to be moved.
For more information see Optimizing Model Target Tracking.
ObjectTargetResult
ObjectTargetResults contain tracking data which are published in the State object and can be accessed from the Renderer or from the Vuforia::registerCallback. Only use this callback for time-critical operations on the frame, or to perform operations which need to be synchronized to the camera thread (e.g. activating and deactivating DataSet instances on an ObjectTracker).
NOTE: If your apps iterate over the list of target results from the State object in their application logic, you won’t have to modify existing code parsing the list of results, but only add a new conditional statement for parsing ObjectTargetResult. If you need to differentiate between ObjectTracker’s target result type (or associated Trackable), you will need to iterate on the derived type before the parent type, i.e. ObjectTargetResult should be verified after ImageTargetResult, ModelTargetResult or VuMarkTargetResult. If you don’t need to differentiate on the type of ObjectTracker’s target result type (or associated Trackable), you only need to use ObjectTargetResult type to get the pose of all the trackable results from ObjectTracker.
example:
for (int r = 0; r < state.getNumTrackableResults(); ++ r)
{
const Vuforia::TrackableResult* trackableResult = state.getTrackableResult(r);
if (trackableResult->isOfType(ImageTargetResult::getClassType()))
{
renderCube(colourRed, trackableResult->getPose());
}
else if (trackableResult->isOfType(VuMark::getClassType()))
{
renderCube(colourBlue, trackableResult->getPose());
}
else if (trackableResult->isOfType(MultiTargetResult::getClassType()))
{
renderCube(colourGreen, trackableResult->getPose());
}
else if (trackableResult->isOfType(CylinderTargetResult::getClassType()))
{
renderCube(colourYellow, trackableResult->getPose());
}
else if (trackableResult->isOfType(ObjectTargetResult::getClassType()))
{
renderCube(colourWhite, trackableResult->getPose());
}
else if (trackableResult->isOfType(ModelTarget::getClassType()))
{
renderCube(colourBlack, trackableResult->getPose());
}
static const Vuforia::Vec3F rightBodyTargetScale(40.f, 40.f, 40.f);
renderCube(colourRed, trackableResult->getPose(), &rightBodyTargetScale);
}
DataSet
A DataSet stores data for one or more ObjectTarget-derived Trackables. Obtain an empty DataSet instance from ObjectTracker::createDataSet(). Populate the returned DataSet either using load() with data prepared offline (pairs of .xml and .dat files), or using createTrackable() with data provided at runtime (for example from a camera frame). Once populated, activate the DataSet using ObjectTracker::activateDataSet().
Use this example on how to load and activate datasets using the ObjectTracker.
Vuforia::TrackerManager& tManager = Vuforia::TrackerManager::getInstance();
Vuforia::ObjectTracker* objectTracker = static_cast<Vuforia::ObjectTracker*>(trackerManager.getTracker(Vuforia::ObjectTracker::getClassType()));
Vuforia::DataSet* dataSetOt1 = objectTracker->createDataSet();
dataSetOt1->load("car.xml", Vuforia::STORAGE_ABSOLUTE);
objectTracker->activateDataSet(dataSetOt1);
(init camera)
objectTracker->start();
To deactivate and destroy the DataSet, follow these three approaches:
- During deinitialization time: deactivate the dataset after stopping the ObjectTracker,
- During run time: if you have started the tracker, deactivate the dataset in the UpdateCallback,
- During run time: if you have started the tracker, stop the tracker first, deactivate the dataset, then restart the tracker.
Example of deactivation
objectTracker->deactivateDataSet(dataSet01);
Example of destroying a loaded and deactivated dataset
objectTracker->destroyDataSet(dataSet01);