Introduction to Model Targets in Unity

This guide walks you through 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, also available in the Unity Asset Store. The samples include two scenes, one for Model Targets and one for Advanced Model Targets. Create your Model Targets with the Model Target Generator (MTG) and import its database into Unity as a Unity Asset Package.

 

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 this article explains.
  3. Replace the default Main Camera with an ARCamera from GameObject -> Vuforia Engine -> AR Camera.
  4. Obtain a License Key for your project. Refer to the Vuforia License Manager guide on obtaining a Vuforia Engine license key.

    NOTE: Device tracking is enabled by default, which is recommended when using 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. If no Model Target database is in the scene, a pop-up will appear, offering to import a default database comprised of the NASA Viking Lander with two Guide Views (front and back).

  2. If you have an already generated Model Target, you can import the database by selecting Assets -> Import Package -> Custom Package… and select the Unity Asset Package 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 will not appear at runtime. The preview in the scene can be hidden by disabling the enable Visualization in the Model Target Preview component.

  1. In the Inspector window of the Model Target, verify that the Physical Length, Physical 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 are known to affect tracking quality.

  2. Add a cube or other content as a child to the Model Target GameObject.
    TIP: You can import 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 or deploy the app to your device.

Tracking configuration of the Model Target 

A Model Target will have an Optimize Tracking For mode set from when it was created in the MTG. However, you can change this mode to any 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.

Enhanced Runtime Detection for Standard Model Targets

Improve a Standard Model Target’s detection performance by caching local appearance information at runtime. The cached data is updated every time you track the Model Target and saved after the session or when deactivating the Model Target.

This feature mainly enhances detection performance for Standard Model Targets, though it is also available for Advanced Model Targets. However, the enhanced detection performance effects might not be as prominent for Advanced Model Targets as for Model Targets. Also, consider that enabling the feature incurs some additional memory overhead and runtime processing.

NOTE: This feature has no effect on Model Targets that use LOW_FEATURE_OBJECTS.

  1. Select Enhance Runtime Detection in the Model Target Behaviour component to turn on enhanced detection for the Model Targets in the database.
    1. See Create and Load Targets in Unity to activate this feature when creating a Model Target at runtime.

Cleaning cached data

Clear the locally stored detection data by calling ClearModelTargetDetectionCache(). This method removes all the cached data by the Model Target Behaviours. If there are any active Model Targets, the method will fail. Clearing the cache can take significant time, and we recommend calling this on other than the main/UI thread.

1
Copy
VuforiaBehaviour.Instance.ClearModelTargetDetectionCache();

Resetting Tracking

When using Runtime Enhanced Detection, it is recommended to include a way for application users to reset tracking in cases where e.g., a strong misalignment is seen and is not corrected automatically. Calling modelTargetBehaviour.Reset(), which resets the tracking of a Model Target Observer, also removes any existing cached data for a Model Target. If the target is detected again, the caching will automatically restart.

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 Runtime Occlusion Mesh parameter to add a runtime mesh that occludes 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 a child of the Model Target. It includes the Runtime Mesh Rendering Behaviour component, which instantiates the Model Target’s mesh at runtime and keeps the geometry accessible for updates and changes.

The mesh requires a Display Material to render the mesh of the tracked Model Target. The component can be used on other GameObjects, but 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, also created at runtime.

Add Target Representation

The Button Add Target Representation adds a static mesh as a new GameObject as a child to the Model Target. It’s useful for setting up shaders and highlighting 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 applying 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 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 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 menu. With the GuideView2D mode enabled, an outlined representation of the object is rendered on the screen at runtime- 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 DetectionPositionControlwith 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.
    • The Custom 2D GuideView Image lets you replace the Guide View with a custom image in Texture 2D format, while the Custom 3D GuideView Model uses a custom 3D model as the Guide View.< br />

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 to add your custom application logic to present target detection.
  • GuideView2D renders the pre-configured Guide View.
  • GuideView3D is for HoloLens or Magic Leap applications to render 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():

12345678
Copy
// The index to activate must be 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 the articles Model Target Generator User Guide and Advanced Model Target Databases.

The setup of Advanced Model Targets is similar to standard Model Targets.

  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. You may choose between the Model Targets stored in the database in the Model Target If you have multiple Models in one database. Switch between the models as you add content to them. Remember that all content must be child objects of the ModelTarget GameObject.

Unlike standard Model Targets, Advanced Model Targets are automatically detected without first displaying a Guide View on the screen. To help users identify the objects that can be detected, you can add a viewfinder UX or a Guide View selected at runtime by the Vuforia Engine.

  1. Select GuideView2D in the Guide View Mode to have the Vuforia Engine render a Guide View for your Advanced Model Target.

For custom UI, display the content during the Model Target’s initializing status.

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

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