This page concerns the Vuforia Engine API version 9.8 and earlier.
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.
Creating your first Model Target Experience
- Create a new Unity project.
- Add the Vuforia Engine package to your Unity project as explained in this article
- 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.
- 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: 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.
- 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 is now enabled by default in new Vuforia enabled Unity projects. Using Model Targets and Ground Planes without Device Tracker will present an error.
- 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.
- Import the Model Target database: go to the Assets menu -> Import Package -> Custom Package… and select the
*.unitypackagefile 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.
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.
- 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.
- In the Inspector window, select the appropriate Database in the Model Target Behaviour component (it should match the *.unitypackage you imported earlier):
- Make sure that the Physical Length, Physical 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.
For more information on scaling Model Targets, see Best Practices for Scaling Model Targets and Virtual Scene Scale Factor in Unity. - 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 choosing a Guide View Mode is not required. See Configuration for Advanced Model Target Databases in the section below for more information.
- 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.
- Use Vuforia's Play Mode in Unity and either attach a standard webcam to your computer or the simulator mode if the object is not at hand, 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.
- 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.
- Stop Play mode and return to the Scene Hierarchy.
- 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.
Align your content relative to the preview model.
- 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.
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 Behaviour 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.
Configuration for Advanced Model Target Databases
Configuring for Advanced Model Target databases use the same GameObject ModelTarget. An Advanced Model Target database is trained by using the Model Target Generator. For more information refer to this article: Model Target Generator User Guide.
If you have trained a database with one or multiple objects with recognition ranges up to 360°, do the following:
- 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.
- 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):
- 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 will automatically be detected without first displaying a Guide View on the screen.
NOTE: The recognition range that was configured in the Model Target Generator for an Advanced Model Target can recognize an object from angles up to 360° from the configured guide view position. For Advanced Model Targets, it is 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
}
- Configure the ModelTarget GameObjects and add content to them as you would with other Model Targets.
The migration guide for Model Targets have been moved here.
Advanced Occlusion
By adding advanced occlusion functionality to your Model Targets you can further immerse your end users or partmentalize the object's features. See How to Use the Occlusion Model in Unity to learn more.