Introduction to Model Targets in Unity

Animated gif using Unity and Model Targets

This guide walks you through the process of placing AR content onto physical objects using Model Targets. For an optimal tracking experience, we recommend using Model Targets in conjunction with the Positional Device Tracker. Additionally, this guide also shows how you can migrate your existing Model Target project to the new Vuforia Engine SDK 8.3.

Creating your first Model Target Experience

  1. Open Unity 2017.3 or newer.
  2. Create a new Unity project.
  3. In the Edit menu, select Project Settings > Player
  4. In the XR Settings section, ensure that Vuforia Augmented Reality Supported is selected.
    Note: Selecting this checkbox may require installing additional resources in your project.
Vuforia Image
  1. Remove the default Main Camera from the scene. Replace the default Main Camera with an ARCamera by going to the GameObject menu -> Vuforia Engine -> AR Camera.
  2. Obtain a License Key for your project. Please refer to the Vuforia License Manager guide on how to obtain a Vuforia Engine 7 license key. Licenses generated with a previous version of Vuforia Engine will not work with Model Targets.

NOTE: A license key is not necessary when using the Vuforia Sample package with the NASA Viking Lander model. See this Article on how to obtain the NASA Viking Lander model and its 3D printing instructions.

  1. Open the Vuforia Configuration window (Window menu -> Vuforia Configuration and expand the Global section if it is not already expanded. Paste your license key in the App License Key text field.

NOTE: the Device Tracker tracking mode -> positional is started automatically by default when using Model Targets or Ground Planes.

Adding-a-license
  1. If you haven't already done so, generate a Model Target database using the Model Target Generator. You will be using the *.unitypackage file generated from this app.
  2. Import the Model Target database: go to the Assets menu -> Import Package -> Custom Package… and select the *.unitypackage file created in the previous step. Alternatively, a default Model Target database can be imported by creating a ModelTarget GameObject before importing a database. This is attained by selecting GameObject -> Vuforia Engine -> Model Target. The default Model Target database is comprised of the NASA Viking Lander with two Guide Views (front and back).

NOTE: An overview of the different imported databases can be found in the Vuforia Configuration which is accessible through the ARCamera GameObject.

Vuforia Image

Configuration for a Model Target with one or more Guide Views

With the Vuforia SDK Engine 8.3, the GameObjects ModelRecognition and ModelTarget are now collected into a single ModelTarget GameObject.

  1. Go to the GameObject menu -> Vuforia Engine -> Model Targets -> Model Target to create a ModelTarget GameObject in your scene. Select the newly created GameObject in the scene hierarchy window. If a Model Target database has not yet been imported beforehand, you are given the option to import a default database provided by Vuforia.
Screenshot of Unity showing GameObject menu, Vuforia Engine menu, Model Targets menu, Model Target entry selected
import-of-vuforia-default-model-target-database
  1. In the Inspector window, select the appropriate Database in the Model Reco Behaviour component (it should match the *.unitypackage you imported earlier):
Vuforia Image
  1. Make sure that the Physical LengthPhysical Width and Physical Height fields match the dimensions of your real-world object, in meters. If you are using a miniature version of a large-scale real-world object for development, you will need to change the dimensions to match the real-world object when shipping your production app. To make this easier, you might want to consider having separate ModelTarget GameObjects for development and production versions of your app. For more information on scaling Model Targets, see Best Practices for Scaling Model Targets.
  2. Also, in the Model Target Behaviour component, set the Guide View Mode to Guide View 2D. From the Guide View dropdown menu, select the view you want the user to align with the Model Target. If you are using Advanced Model Target databases, then a Guide View Mode is not required to be chosen. See Configuration for Advanced Model Target Databases for more information.
Vuforia Image
  1. You will notice that in your scene there is a preview model representing the Model Target. The purpose of this model is to aid you in placing an augmentation relative to specific parts of the physical object itself - it is only visible in the Scene view of the Unity Editor. If you start Play mode or build your app, it will not appear. 
  2. Attach a standard webcam to your computer and press the Play button in Unity. (Or, deploy the app to your device.)

You will notice an outlined representation of the object to be tracked - this is the Guide View.

Vuforia Image
  1. Align the Guide View with your real-world object. You will notice the Guide View disappear, which indicates that tracking has started, but there will be no visible augmentation for now.
  2. Stop Play mode if necessary and return the Scene Hierarchy.
  3. To customize your AR experience, place custom content as child objects of the ModelTarget Game Object. Align your content relative to the preview model.

NOTE: If you are using the NASA Viking Lander model you can import content for the model through the Vuforia Sample package.

Vuforia Image

Align your content relative to the preview model.

Vuforia Image
  1. Again, with a standard webcam attached to your computer, press the Play button in Unity. (Or, deploy to your device). Once you align your camera/device so that the Guide View matches the real object, you will see the augmentation.
Vuforia Image

Manually switching between Guide Views

If your Model Target defines multiple Guide Views, you can switch between them in a C# script with the following code:

var modelTarget = FindObjectOfType<ModelTargetBehaviour>().ModelTarget;
// the index to activate must between 0 and modelTarget.GetNumGuideViews()-1
int guideViewIndexToActivate = ...;
modelTarget.SetActiveGuideViewIndex(guideViewIndexToActivate);

Setting the Motion Hint in Unity

Vuforia provides a motion hint option that is ideal for tracking stationary objects. We recommend setting the Model Target’s motion hint in the Model Attributes menu of the Model Target Generator. However, the value can be manually overridden. In Unity, within the Inspector window, use the Model Target Behavior component to override the Model Target’s motion hint. In the Motion Hint field, select STATIC if the object is stationary or select ADAPTIVE If the object is likely to be moved.

Vuforia Image

Configuration for Advanced Model Target Databases

Configuring for Advanced Model Target databases use the same GameObject ModelTarget. A Advanced Model Target database is trained by using the MTG. For more information refer to this article Model Target Generator User Guide. If you have such a database representing multiple objects/Guide Views or your model is using the 360˚ feature, do the following:

  1. Go to the GameObject menu -> Vuforia Engine -> Model Targets -> Model Target to create a ModelTarget GameObject in your scene. Select the newly created GameObject in the scene hierarchy window. 

 

Screenshot of Unity showing GameObject menu, Vuforia Engine menu, Model Targets menu, Model Recognition entry selected
  1. In the Inspector window, select the appropriate Database in the Model Target Behaviour component (it should match the *.unitypackage of your Advanced Model Target database):
Screenshot of Unity demonstrating selection of the correct Model Target database in the Advanced Reco component
  1. If you are using multiple Models in one database, then you may choose between the Model Targets stored in the database in the Model Target. Switch between the models as you add content to the models. Keep in mind that all content must be child objects of the ModelTarget GameObject.

If you are using the Advanced Model Target 360 feature, there will be only one selectable Model in Model Target.

NOTE: Unlike standard Model Targets, Advanced Model Targets  databases will automatically detect the best fitting Guide View to the user’s viewing position and display the selected Guide View on the screen during runtime. Similarly, Model Targets with the Advanced 360 feature do not require a Guide View as it can recognize the object from any angle and starting position.

Screenshot of Unity showing the guide view mode

NOTE: The Guide View might change if another object comes into view, or if you move the camera around to look at the same object from a different angle, depending on how the Guide View recognition range was configured in the Model Target Generator.

NOTE: For the Advanced Model Targets, it's good practice to display some general guidance to the User until a target has been detected. The following code shows how this could be done (see more best practice recommendation on the Model Target Guide View page):

    if (modelTargetBehaviours.All(mt => mt.CurrentStatusInfo == TrackableBehaviour.StatusInfo.INITIALIZING))
    {
        //all model targets in the scene are initializing, display custom UI here
    }
    
  1. Configure the ModelTarget GameObjects and add content to them as you would with other Model Targets.

NOTE: When using a Advanced Model Targets database, multiple ModelTarget GameObjects can be active at the same time. At runtime, Vuforia will recognize which target to activate and display Guide View for it. If you have multiple ModelTarget GameObjects in the Hierarchy using different standard Model Target databases, it is advised to only activate the GameObject of the Model Target you want to track first to guarantee it will be activated over another target in the scene.

Migrate your project

With Vuforia SDK 8.3 Engine, it is possible to update your current project from the now deprecated ModelRecognition and ModelTarget GameObjects. This is done through the migration of the GameObjects.

  1. Select your ARCamera and navigate to Vuforia Configuration to ensure that you have updated to the Vuforia Engine Version 8.3.
migrating GameObjects from Model Recognition to ModelTarget 8.3
  1. Locate the Game Objects of type ModelTargets and Model Recognition in the Hierarchy. In the Inspector, you will now see that the Model Reco Behaviour is deprecated and a button to migrate the settings related to the Model Target is present. Press the Migrate Settings.

The Migrate function will deactivate the ModelRecognition GameObject and transfer the settings of the DefaultModelRecoEventHandler to the VuforiaConfiguration. Additionally, by migrating to the updated Vuforia SDK 8.3, it is now possible to have multiple ModelRecognition GameObjects (now named advanced database) active at the same time.

Advanced Occlusion

To add advanced occlusion functionality to your applications, refer to the Unity Asset Store.

Learn More

Model Targets Overview

Model Targets API Overview

Model Target Generator User Guide

Model Target Test App User Guide