Introduction to Model Targets in Unity

This guide walks you through the process of importing and working with Model Targets in Unity. Import your Model Targets from databases and start designing and developing AR experiences to augment your products.

Get Started with Model Targets by trying our Vuforia Core Samples that are also available in the Unity Asset Store. The samples include two scenes, one for Model Targets and one for Advanced Model Targets. Create your own Model Targets with the Model Target Generator (MTG) and import its database as a .unitypackage into Unity

Set up Unity with Vuforia Engine and Model Targets

See Getting Started with Vuforia Engine in Unity if you are unfamiliar with Vuforia Engine in Unity. We recommend having the physical object present to test the tracking quality and digital content with a webcam or a device.

Setup Vuforia Engine in Unity

  1. Create a new Unity project. For supported Unity Editor versions, see Supported Versions.
  2. Add the Vuforia Engine package to your Unity project as explained in this article.
  3. Replace the default Main Camera with an ARCamera from GameObject -> Vuforia Engine -> AR Camera.
  4. Obtain a License Key for your project. Please refer to the Vuforia License Manager guide on how to obtain a Vuforia Engine license key.

    NOTE: Device tracking is enabled by default. It is recommended to use Device Tracking with Model Targets.

Add a Model Target to your scene

If you haven't already done so, generate a Model Target database using the Model Target Generator. You will be importing the .unitypackage file generated from the MTG tool. Alternatively, a default Model Target database with the Viking Lander can be imported by creating a ModelTarget GameObject before importing a database. 

  1. Select GameObject -> Vuforia Engine -> Model Target. A default Model Target database comprised of the NASA Viking Lander with two Guide Views (front and back) can then be added if no Model Target database was detected.

  2. If you have your own Model Target generated, import the database by selecting Assets -> Import Package -> Custom Package… and select the .unitypackage file.

TIP: You can verify that a database was added from the overview in the Vuforia Configuration (Cmd+Shift+V/Ctrl+Shift+V).

TIP: Disable the model extraction from databases if you only need to track the targets.

Configure the Model Target

A Model Target GameObject needs a Database and Model Target assigned to it from the Inspector panel. A preview model representing the Model Target will be shown in the Scene. 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 and it will not appear at runtime. The preview in the scene can be hidden by disabling the enable Visualization in Model Target Preview component.

  1. In the Inspector window of the Model Target, verify that the Physical LengthPhysical Width, and Physical Height fields match the dimensions of your real-world object, in meters. Size differences between the physical object and the Model Target is known to affect tracking quality.

  2. Add a cube or other content as a child to the Model Target GameObject.

    TIP: You can import content for the Viking Lander or the toy vehicle through the Vuforia Core Samples package.

  3. Test your Model Target with Vuforia’s Play Mode in Unity by pressing the Play button in Unity. Or, deploy the app to your device.

Tracking configuration of the Model Target 

A Model Target will have a Optimize Tracking For mode set from when it was created in the MTG, however, you can change this mode to any of the available options in the Inspector. The mode AR_CONTROLLER can only be set here or with the API. Please see Optimizing Model Target Tracking for details on the tracking mode for Model Targets.

Mesh and Target Representation

The Model Targets Behaviour component has options to add and use its Model Target’s mesh at runtime for collision detection and occlusion. This adds the benefit of using the mesh directly from the Model Target instead of copying the mesh into the app. The following two parameters will not render or display anything over the Model Target.

  • Set the parameter Runtime Occlusion Mesh to add a runtime mesh that occlude other GameObjects.
  • Set the parameter Runtime Mesh Collider to add a runtime mesh with a mesh collider for raycasting and collision detection.

Add Runtime Mesh

The button Add Runtime Mesh creates a new GameObject as child of the Model Target. It has the Runtime Mesh Rendering Behaviour component which instantiates the Model Target’s mesh at runtime and keeps the geometry accessible for updates and changes.

It requires a Display Material for rendering the mesh of the tracked Model Target. The component can be used on other GameObjects, but then you need to supply a Source Behaviour as well.

This capability is extended to runtime where you can use the API CreateRuntimeMeshRenderingBehaviour to add a mesh representation to a ModelTargetBehaviour that also could be created at runtime.

Add Target Representation

The Button Add Target Representation adds a static mesh as a new GameObject as child to the Model Target. It’s useful for setting up shaders and highlight of parts when authoring in the Editor. At runtime, the Target Representation will then render when the Model Target is detected. It also occludes other GameObjects.

NOTE: Virtual Scene Scale will not re-scale the Runtime Mesh or Target Representation. These must be added again after you have applied the value to the Virtual Scene Scale Factor.

Configure Guide Views for a Model Target

A Model Target is generated with one or more Guide Views for initializing tracking of an object from different angles; see Guide Views for details. In Unity, you can select a Guide View to show from the Model Target Behaviour component of the Model Target if it has one or multiple Guide Views.

NOTE: Advanced Model Targets don’t require a Guide View. See Configuration for Advanced Model Target Databases in the section below for more information.

  1. Select between GuideView2D and GuideView3D in the Guide View Mode. As the names suggest, Guide Views can be 2D textures or 3D models.
  2. Choose between your Guide Views from the dropdown Guide View. At runtime, with the GuideView2D mode enabled, an outlined representation of the object is rendered on the screen – this is the Guide View. It disappears when the matching object is detected.
    • Override Detection Position creates a GameObject named DectectionPositionControl that replaces the detection position of the Guide View in world space. Reposition the DetectionPositionControl with the help of the Camera component’s preview window in the scene to update a Guide View, its tracking initiation, and its preview image rendered at runtime.
    • Custom 2D GuideView Image lets you replace the Guide View with a custom image in Texture 2D format. Similarly, Custom 3D GuideView Model lets you use a custom 3D model as the Guide View.

Guide View mode

The Guide View Mode defines how the Guide View is rendered. 

  • NoGuideView will not render the Guide View on the screen. Use this mode for adding your own application logic to present target detection.
  • GuideView2D renders the pre-configured Guide View.
  • GuideView3D is for HoloLens or Magic Leap applications for rendering a 3D model representation of the object and the detection position.

Manually switching between Guide Views

If your Model Target has multiple Guide Views, you can switch between them at runtime in a custom C# script with SetActiveGuideViewIndex():

// The index to activate must between 0 and mModelTarget.GetNumGuideViews()-1
var guideViewIndexToActivate = 0;
mModelTarget.SetActiveGuideViewIndex(guideViewIndexToActivate);
/* Or, set Guide View to activate by string name */
string guideViewNameToActivate = "Front";
mModelTarget.SetActiveGuideViewName(guideViewNameToActivate);
/* Afterwards you should set the guide view display mode */
mModelTarget.GuideViewMode = ModelTargetBehaviour.GuideViewDisplayMode.GuideView2D;

Configuration for Advanced Model Target Databases

Advanced Model Targets use the same ModelTarget GameObject. An Advanced Model Target database is trained through the Model Target Generator. For more information refer to these articles: Model Target Generator User Guide and Advanced Model Target Databases..

The setup of Advanced Model Targets is similar to standard Model Targets, with exception of the Guide views.

  1. Go to GameObject -> Vuforia Engine -> Model Targets -> Model Target to create a ModelTarget GameObject in your scene. Select the newly created GameObject in the scene hierarchy window.
  2. In the Inspector window, select the Database dropdown menu and select your imported Advanced Model Target database.

  3. 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.

NOTE: Unlike standard Model Targets, Advanced Model Targets are automatically detected without first displaying a Guide View on the screen.

It is good practice to display some general guidance to the user to identify the object that can be tracked. The following code shows how this could be done. See other best practices on the Advanced Views page.

if (mModelTargetBehaviour.TargetStatus.StatusInfo == StatusInfo.INITIALIZING)
{
   // All model targets in the scene are initializing, display custom UI here
}

Configure the ModelTarget GameObjects and add content to them as you would with other Model Targets.

Can this page be better?
Share your feedback via our issue tracker