How To Use Object Recognition in Unity

This page concerns the Vuforia Engine API version 9.8 and earlier. It has been deprecated and will no longer be actively updated.

Object Recognition (Object Targets) enables you to create apps that can recognize, and track objects based on their visual features, such as toys. This article will show you how to add Object Recognition and Object Targets to a Unity project, and how to customize the behaviors exposed through the Object Recognition API and implement custom event handling.

If you are unfamiliar with the Unity Workflow, it may be helpful to read Getting Started with the Unity Workflow

You will also need to get a license key from the License Manager and add it to your project if you are looking to track your own objects. The following articles may be helpful: How To Create an App License and How To add a License Key to your Vuforia App

Adding Object Targets to Your Project

The workflow for adding Object Targets to a Vuforia Engine Unity project is very similar to that of the Image Targets. Firstly, set your Unity with the latest Vuforia Engine SDK with the Vuforia Engine Package Hosting for Unity.

Add a Device Database containing an Object Target and the AR Camera.

Add an ARCamera GameObject instance to your scene. Remove the default Main Camera from your scene.
Add a Device Database containing an Object Target
1. Create your own Device Database in the Target Manager that includes the Object Target. See Vuforia Object Scanner for a guide on creating Object Targets.
  1. Download that database as a *.unitypackage.
  2. Import the unitypackage from Assets -> Import Package -> Custom Package, or by double clicking the package file on your file system.
2. As an alternative, the Vuforia Core Samples for Unity include an Object Target database with a Mars Habitat model. Retrieve it from the sample project or simply continue with the following steps.

Adding and Configuring the Object Target GameObject

Create an ObjectTarget (3D Scanned) GameObject from the menu GameObject -> Vuforia Engine. If no Object Target database was imported, a window will appear asking if you wish to import a default database for your Object Target. Press Import to use the default Object Target database.
Select the ObjectTarget and in its inspector select the Database name and Object Target name that you want to associate with the Object Target instance. If there are no Object Target Databases in your project, there will be a button to import a default Object Target.

There is a 1:1 relationship between the ObjectTarget GameObject instances and the Object Target in a Device Database.

Add your augmentable content as a child to the Object Target GameObject.

In the Advanced expandable menu, you can enable the bounding box to position and scale your content in relation to the target.

Test your scene in Play Mode by pressing the Play button in the top panel of the Editor.

Recommended Augmentation Workflow

The Object Target bounding box corresponds to the grid region of the Object Target. You can use the Object Scanning target as a physical reference while in Play Mode to help position your content as illustrated in the following image setup:

Important: Making changes while in Play Mode will not be saved! Exit Play Mode every time you wish to make changes.

Obtaining the Object Recognition Tracker Instance

The ObjectTracker tracks the Object Targets and you can control the tracker by the following methods. For a full overview of the ObjectTracker capabilities, please see ObjectTracker API Overview

ObjectTracker mTracker = TrackerManager.Instance.GetTracker<ObjectTracker>();

Starting and stopping the Object Recognition Tracker

Start() starts the Object Recognition Tracker

Stop() stops the Object Recognition Tracker

Reset() resets the Object Recognition Tracker

Customizing Event Handling

Object Targets can have multiple detection and tracking states as defined by the Status of their TrackableResult. This result enables you to develop apps that unlock content when the Object Target is detected and is being tracked.

You can use this information to determine when an Object Target has been recognized, when it is being actively tracked, and when tracking and detection have been lost on an object that was previously being tracked. Use the events to disable Renderers and Colliders and assign your own event handling here. More information can be found at Using the Device Tracker in Unity

Activating Loaded Datasets at Runtime

It is also possible to load and disable your Object Target databases at runtime if you for example wish to switch between sets of trackable objects. See How to Create and Load Targets in Unity for a guide on implementing runtime behaviour in your Unity project.

/// <summary>
/// Sample implementation of how to activate the datasets through code
/// </summary>
/// <param name="datasetPath"></param>
private void ActivateDatasets(string datasetPath)
{
    ObjectTracker objectTracker = TrackerManager.Instance.GetTracker<objecttracker>();
    IEnumerable<dataset> datasets = objectTracker.GetDataSets();

    IEnumerable<dataset> activeDataSets = objectTracker.GetActiveDataSets();

    List<dataset> activeDataSetsToBeRemoved = activeDataSets.ToList();

    //1. Loop through all the active datasets and deactivate them.
    foreach (DataSet ads in activeDataSetsToBeRemoved)
    {
        objectTracker.DeactivateDataSet(ads);
    }

    //Swapping of the datasets should not be done while the ObjectTracker is working at the same time.
    //2. So, Stop the tracker first.
    objectTracker.Stop();

    //3. Then, look up the new dataset and if one exists, activate it.
    foreach (DataSet ds in datasets)
    {
        if (ds.Path.Contains(datasetPath))
        {
            objectTracker.ActivateDataSet(ds);
        }
    }

    //4. Finally, start the object tracker.
    objectTracker.Start();
}

How To Support Moving Objects

Object Recognition can track moving objects, provided the motion is slow and smooth. You will need to configure your Object Targets to support motion using the following steps. To support movement, you will need to disable the Device Tracker in VuforiaConfiguration.

Device tracking can also be started and stopped during runtime by accessing the DeviceTracker class directly.
Please see the following article for more information about device tracking: Device Tracking