Working with VuMarks in Unity

Vuforia Image

The Vuforia VuMark Sample project for Unity provides a pre-configured VuMark scene that you can use as a reference and starting point for your own VuMark apps. This article will show you how to author content using VuMarks in this sample, how to customize event handling for the detection and tracking of VuMarks, and how to read and respond to data encoded in a VuMark.

Unity Setup for Vuforia Engine

Importing the sample

The VuMark sample is part of the Core samples available on the Unity Asset Store website or from the Assets tab in the Unity Editor. Import the content into a new and empty Unity project. This will prompt the Vuforia Engine SDK to be imported and configured.

Adding a License Key

The Core samples available on the Asset Store will work without a Vuforia license key. However, to  use a custom VuMark database created by yourself, it is necessary to add a license key to the Vuforia Configuration in Unity.The license key can be created in the License Manager on the Developer Portal and Vuforia Configuration is reachable with the key bindings cmd+shift+V for Mac and ctrl+shift+V for Windows. 

See also: How To add a License Key to your Vuforia Engine App

Scene Elements and their Configuration

Start by locating the VuMark scene in the Project Folder at Assets/SamplesResources/Scenes/3-VuMarks. Open the scene. The VuMark sample's scene Hierarchy demonstrates how to set-up a Vuforia VuMark scene in Unity.

Vuforia Image

For a general introduction to the Vuforia Engine setup and components in the Unity Editor, please see Getting Started with Unity

VuMark

The VuMark GameObject encapsulates the VuMark Behaviour and VuMark Trackable Event Handler components which ensure that your VuMark instances are trackable. These are also the primary script components that you will use to customize an app that use VuMarks.

In the VuMark Behaviour component, the ID Type and ID Length is shown for the VuMark database.  

Vuforia Image

VuMark GameObject is created by right-clicking in the Hierarchy and then select Vuforia Engine -> VuMark.

NOTE: That only one VuMark database can be used at a time in a scene with the Free Development License. If you wish to use multiple VuMarks, please refer to the other available license options.

VuMarkUI

The VuMarkUI GameObject is a parent object that is populated with the UI elements for presenting the instance ID information of a VuMark instance when it is recognized during runtime. 

VuMarkHandler

The VuMarkHandler GameObject contains the augmentation content and it is responsible for querying the InstanceId of the VuMarks. The attached script handles what to show when a certain VuMark instance is recognized. Consult the VuMarkHandler.cs script to understand how this data is retrieved and written to theUI fields in the VuMarkUI GameObject.

Vuforia Image

TIP: Add content as a child of the VuMark GameObject that you wish to have present on all VuMark instances. The instance specific content should only be placed in the VuMarkHandler GameObject and set to inactive as the content will be called for activation by the VuMarkHandler.cs script when the matching VuMark instanceID is identified. 

Build Settings

To build and test the sample, add all of the scenes in the /SamplesScenes folder to Scenes In Build in File -> Build Settings window. Depending on your device, select Android, iOS or Universal Windows Platform as the build Platform.

Vuforia Image

Then, proceed to name your app’s Bundle Identifier in Player Settings -> Publishing tab. Connect your device and click Build and Run

Using PlayMode

Alternatively, test the scene and VuMark by using Vuforia’s Play Mode. Press the Play button at the top of the Unity Editor and use an inbuilt or attached webcam to detect and track the activated VuMark databases.

See Vuforia Play Mode for Unity.

Customizing the Sample

The quickest possible way to test your own VuMark databases is to exchange the VuMark GameObject’sdatabase with your own in the VuMark Behaviour component.

  1. Follow the instructions on creating your own VuMark Template in Adobe Illustrator and download the resulting database as a .unitypackage from the Vuforia Target Manager. 
  2. Import the database into your Unity project by selecting Assets -> Package -> Custom Package. 
  3. Select the VuMark GameObject and replace the database in the dropdown menu with your own. 
  4. If applicable, adjust the data type and IDs in the VuMarkHandler GameObject to fit with your VuMark template.
  5. Make sure to add a Vuforia License key as described in How To add a License Key to your Vuforia Engine App
  6. Test your VuMark instances by generating and download them from the Target Manager and print them without scaling them. A guide on generating instances can be found in How to Work with VuMark Databases.

Further customization

Default Trackable Event Handler

The VuMark Trackable Event Handler component is responsible for handling callbacks to the VuMark Behaviourarising from changes in the state of the VuMark Trackable, such as when it has been detected and is being tracked.
This script is used to enable and disable rendering and collision detection on digital content that is a child of the VuMark GameObject. Extend the script’s OnTrackingFound() and OnTrackingLost() methods to implement custom event handling for your VuMark and app. See Interpreting Tracking API Results for details on the VuMark’s tracking states.

Enabling/Disabling Extended Tracking

Using the Device Tracker for extended tracking enables you to maintain tracking for a scene even when the VuMark is no longer in the camera view. This enables you to place content further away from the VuMark, See: Device Tracking Overview

The Device Tracker is enabled by default, but you can manage it at build time in the Vuforia Configuration or at runtime at initialization by calling the PositionalDeviceTracker. Control when to render augmentations iftracking accuracy of a target is reduced significantly; when the status is switched to LIMITED, you may choose between continuing rendering augmentations or wait until EXTENDED_TRACKING is reported once again.  

VuMark sizes

The size of a VuMark is controlled through its template and needs to correspond to the physical size of the printed VuMark. All instances of the template will use the same size.

For use cases where different VuMark instances have different sized, you can use the getSize() and setSize() methods of the VuMark class to change the size at runtime. You can also use the Virtual Scene Scale Factor in Unity to translate between real-world size and virtual scale in your Unity scene.

If two different sized VuMark instances of the same template are being tracked at the same time, at least one of them will be scaled wrongly. To avoid unexpected tracking effects, disable the device tracker in such a case.

Learn More

How to Work with the VuMark Databases

Using the VuMark Generation API

VuMark API Overview