Skip to content

VuMark API Overview

The VuMark API is exposed in the native Vuforia Engine C API. 

A VuMark target is a template for a defined set of instances that each has a unique ID.

With VuMarks, you can encode different data for every instances while maintaining a consistent visual image or logo. Create a VuMark Template following the VuMark Design Guide and use the Vuforia Target Manager to generate and download a VuMark database.

Create a VuMark Observer

The VuMark Observer is the template from which VuMark instances are recognized. The VuMark Template is loaded from a generated VuMark database. Instances can be of id type: byte, string, or numeric.

1
2
3
4
5
6
7
8
// Create an Observer config
VuVuMarkConfig vuMarkConfig = vuVuMarkConfigDefault();
vuMarkConfig.databasePath = "VuMark.xml";
vuMarkConfig.templateName = "VumarkTemplate";

// Create a VuMark Observer
VuObserver* vuMarkObserver = { NULL };
vuEngineCreateVuMarkObserver(engine, &vuMarkObserver, vuMarkConfig, NULL);

The above code snippet creates a VuMark Observer loaded from the VuMark database. The databasePath and templateName must match the content of the database. When the Vumark 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 VuMark Observer produces Observations that are 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

1
2
3
4
5
6
// create observation list
VuObservationList* obsList = { NULL };
vuObservationListCreate(&obsList);

// Get and parse VuMark observations list
vuStateGetVuMarkObservations(state,obsList);

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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
int32_t listSize = 0;
vuObservationListGetSize(obsList, &listSize);

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

    VuPoseInfo poseInfo;
    vuObservationGetPoseInfo(obs, &poseInfo);

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

Destroy Observer and Observation

Stop and 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 

1
2
// destroy observation list
vuObservationListDestroy(obsList);

Destroy the Obsever

1
2
// Destroy the observer
vuObserverDestroy(vuMarkObserver);

Accessing VuMark specific Observation Information

A VuMark's Template Info contains the VuMark's unique Id that is persistent across all its VuMark instances. Also, the template user data is retrieved from the VuMark Template Observation.

1
2
3
// Get VuMark template info
VuVuMarkObservationTemplateInfo vuMarkTemplateInfo;
vuVuMarkObservationGetTemplateInfo(observation, &vuMarkTemplateInfo);

VuMark Observation Instance Info

In addition to the template info, the instance specific information can be queried from the VuMark Observation as well. Every instance carries a unique id that can be identified with calling dataType and retrieved with below call.

1
2
3
4
// Get VuMark instance info
VuObservation vuMarkObservation;
VuVuMarkObservationInstanceInfo vuMarkInstanceInfo;
vuVuMarkObservationGetInstanceInfo(vuMarkObservation, &vuMarkInstanceInfo);

VuMark Configuration

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

Size

Get the size (height and length) of a VuMark template in meters.

1
vuVuMarkObserverGetTemplateSize(const VuObserver* observer, VuVector2F* size);

Scale

Re-scale the VuMark template with a scale factor retrieved from the GetTemplateSize(). All detected instances will inherit the scale changes.

1
vuVuMarkObserverSetTemplateScale(VuObserver* observer, float scale);

UserData

Get the user data for the VuMark template from the Observer's database.

1
vuVuMarkObserverGetUserData(const VuObserver* observer, const char** userData);

Background Image

For VuMarks in particular, you can decide whether to also use the background image to track with. This is for example useful if the logo contains a lot of features and details or if it contains very few features. See VuMark Design Guide for more detail on background images. Use the get/set to switch it on or off.

1
vuVuMarkObserverGetTrackingFromRuntimeAppearance(const VuObserver* observer, VuBool* isEnabled);

Bounding Box

Use this function to get an axis-aligned bounding box of a VuMark Template from its respective Observer, and relative to its frame of reference.

1
vuVuMarkObserverGetTemplateAABB(const VuObserver* observer, VuAABB* bbox);

Learn More

VuMark

How to Work with VuMark Databases

Using the VuMark Generation API