Cylinder Targets API Overview

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

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

A Cylinder Target represents images that are wrapped into cylindrical or conical shapes consisting of 2 to 3 images. To work with Cylinder Targets, you will first need to calculate and design the setup of the images and then import them into the Target Manager. The resulting device database can then be downloaded, and a Cylinder Target Observer can be loaded and created from it. We present below the general setup for using Cylinder 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 Cylinder Target Observer

To track a Cylinder Target, you can use a Cylinder Target Observer that is created from a device database. Before starting the Engine, you should configure and create your Observer.

Create a Cylinder Target Observer

// Create an Observer config
VuCylinderTargetConfig cylinderTargetConfig = vuCylinderTargetConfigDefault();
cylinderTargetConfig.databasePath = "aluminium_can.xml";
cylinderTargetConfig.targetName = "soda";

// Create a Cylinder Target Observer
VuObserver* cylinderTargetObserver = NULL;
vuEngineCreateCylinderTargetObserver(engine, &cylinderTargetObserver, cylinderTargetConfig, NULL);

The above example creates a Cylinder Target Observer with default values as configured when creating the dataset. The databasePath and targetName must match a target and database. When a Cylinder 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 Cylinder Target Observer produces Observations that are collected in the State. Get the state from the Engine and parse them to the CylinderTargetObservationTargetInfo. 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 cylinder target observations list
vuStateGetCylinderTargetObservations(state,obsList);

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

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

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

    VuPoseInfo poseInfo;
    vuObservationGetPoseInfo(obs, &poseInfo);

    VuCylinderTargetObservationTargetInfo targetInfo;
    vuCylinderTargetObservationGetTargetInfo(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 Cylinder Targets, you call the following to destroy the Cylinder Target Observation and the Cylinder Target Observer.

Destroy ObservationList

// destroy observation list
vuObservationListDestroy(obsList);

Destroy the Observer

// Destroy the observer
vuObserverDestroy(cylinderTargetObserver);

Configuring Cylinder Targets

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

Size

Get the size values of a Cylinder Target in meters. Cylinder Targets have a side length, bottom diameter, and a top diameter. These values can be retrieved with three calls:

vuCylinderTargetObserverGetTargetSideLength(const VuObserver* observer, float* sideLength);
vuCylinderTargetObserverGetTargetTopDiameter(const VuObserver* observer, float* topDiameter);
vuCylinderTargetObserverGetTargetBottomDiameter(const VuObserver* observer, float* bottomDiameter);

Scale

To set the size of a Cylinder Target, we recommend using a common scale factor and apply to each of the Cylinder Target Observer’s dimensions:

vuCylinderTargetObserverSetTargetSideLength(VuObserver* observer, float sideLength);
vuCylinderTargetObserverSetTargetTopDiameter(VuObserver* observer, float topDiameter);
vuCylinderTargetObserverSetTargetBottomDiameter(VuObserver* observer, float bottomDiameter);

Bounding Box

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

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

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

Learn More

Image Targets

Multi Targets

VuMark

Detect and Track Multiple Targets Simultaneously

Vuforia Engine Lifecycle