Getting Started with Vuforia for Unity Development


Developing Vuforia Apps Using a Graphical Workflow

The Vuforia Unity Extension enables you to create vision apps for Android and iOS using a simple drag-and-drop authoring workflow in Unity.

Unity is a popular development engine that provides high quality rendering and animation features, along with the ability to implement custom app logic through scripting.

Vuforia provides a variety of Unity sample projects that demonstrate how to implement all of the features of the platform. You can use these projects as templates for your own apps, and customize them by adding your own digital content and target images.

Getting Started

The Image Targets in Unity video tutorial will show you how to author a simple Vuforia project using Image Targets in Unity.

How To Setup a Unity Project will walk you through the steps necessary for setting-up, customizing and building a simple Vuforia Unity project for both iOS and Android.

The Vuforia Play Mode for Unity video tutorial will show you how to rapidly prototype your app in Unity using the Vuforia simulator in Play Mode.

Creating Targets

You will use the online Target Manager to create and manage the target images that your app can recognize and track. The Vuforia Target Manager Guide provides an introduction to working with the Target Manager to create targets and target databases.

For tips on selecting and designing target images, review the Image Targets Guide.

More Information

The Vuforia Developer Library documents all of the features, tools and services of the Vuforia Platform.


How To Install the Vuforia Unity Extension

The Vuforia Unity Extension enables the development of vision based apps using the Unity Game Engine. Developers must obtain the Unity Editor, along with the Unity Android and/or Unity iOS mobile plugins from Unity Technologies. To use Vuforia in Unity, you'll need to import the Vuforia Unity Extension into your Unity project
Note: The Vuforia Unity Extension is compatible with both Unity Standard and Unity Pro.

Visit the Unity website for further information about Unity and how to download it.
If you already have Unity and need to migrate an existing Vuforia project to a new extension version, See: How To Migrate a Unity Project
Importing the extension

  1.  Download the Vuforia Unity Extension.
  2. Open your Unity project or create a new one.
  3. Import the Vuforia Unity Extension by either double clicking the extensions *.unitypackage file on your file system, or by selecting Assets/Import Package/Custom Package in the Editor's menu and then selecting the *.unitypackage on your file system.
  4. The extension archive will self install into your project, adding the following folders, with plugins and libraries, to your project.

Vuforia extension folders


How To Setup a Simple Unity Project

It's easy to set-up a basic Vuforia project in Unity. Follow these steps to import the Vuforia Unity extension and to add and configure the prefabs and assets used to develop Vuforia apps in Unity.

Create a project

  1. Create a new project in Unity.
  2. Download the Vuforia Unity Extension
  3. Browse to the vuforia-unity-xx-yy-zz.unitypackage you just downloaded double-click on the file.
  4. Accept the import of the package into your Unity project.

Obtain a License Key

You will need create a license key for your app in the License Manager and add this key to your project.

See:
How To Create a License Key
How To add a License Key to your Vuforia App

Adding Targets

Next, you need to add a Device Database to your project. You can do this in two ways:

  • Create a target on the Target Manager

OR

  • Use existing targets from other projects
  1. To use the Target Manager method, see Vuforia Target Manager to create and download a package.
  2. Double-click the downloaded package, or right-click on Unity Project for Import Package and "Custom Package.
  3. Select the downloaded package.
  4. Click Import to import the target Device Database.

If you are copying the Device Database files from another project, be sure to copy any files located in the Editor/QCAR/ImageTargetTextures folder. These will be used to texture the target plane in the Unity editor.

You should now see the following folder structure inside Unity:

Project Folders

  • Editor - Contains the scripts required to interact dynamically with Target data in the Unity editor
  • Plugins - Contains Java and native binaries that integrate the Vuforia AR SDK with the Unity Android or Unity iOS application
  • Vuforia - Contains the prefabs and scripts required to bring augmented reality to your Unity application
  • Streaming Assets / QCAR - Contains the Device Database configuration XML and DAT files downloaded from the online Target Manager

Add AR assets and prefabs to scene

  1. Now that you have imported the Vuforia AR Extension for Unity, you can easily adapt your project to use augmented reality.
  2. Open the /Vuforia/Prefabs folder
  3. Delete the Main Camera in your current scene hierarchy, and drag an instance of the ARCamera prefab into your scene. The ARCamera is responsible for rendering the camera image in the background and manipulating scene objects to react to tracking data.
  4. With the ARCamera in place and the target assets available in the StreamingAssets/QCAR folder, run the application on a supported device, and see the live video in the background.
  5. Drag an instance of the ImageTarget prefab into your scene. This prefab represents a single instance of an Image Target object.
  6. Select the ImageTarget object in your scene, and look at the Inspector. There should be an Image Target Behaviour attached, with a property named Data Set. This property contains a drop-down list of all available Data Sets for this project. When a Data Set is selected, the Image Target property drop-down is filled with a list of the targets available in that Data Set.
  7. Select the Data Set and Image Target from your StreamingAssets/QCAR project. In this example, we choose "StonesAndChips". (It is automatically populated from the Device Database XML file that is downloaded from the online Target Manager). The Unity sample apps come with several Image Targets . To use them, copy them from the ImageTargets sample, or create your own at the Target Manager section of this site.

Inspector view of the ImageTarget


NOTE: When you added the Image Target object to your scene, a gray plane object appeared. This object is a placeholder for actual Image Targets. In the inspector view of the Image Target there is a pop-up list called Image Target. From this list, you can choose any Image Target that has been defined in one of the StreamingAssets/QCAR datasets so that the Image Target object in your scene adopts the size and shape from the Image Target it represents. The object is also textured with the same image from which the Image Target was created.

Add 3D objects to scene and attach to trackables

Now you can bind 3D content to your Image Target.

  1. As a test, create a simple Cube object (GameObject > 3D Object > Cube).
  2. Add the cube as a child of the ImageTarget object by selecting it in the Hierarchy list and dragging it onto the ImageTarget item.
  3. Move the cube in the scene until it is centered on the Image Target. You can also add a Directional Light to the scene (GameObject > Light > Directional Light).

TrackableEventHandler

The Default Trackable Event Handler (DefaultTrackableEventHandler) is a script component of the Image Target that causes the cube you just drew to appear or disappear automatically an automatic reaction to the appearance of the target in the video.

You can override this default behavior by revising the DefaultTrackableEventHandler script or writing your own by implementing the ITrackableEventHandler interface.

Adding Dataset load to camera

The Vuforia SDK has the ability to use multiple active Device Databases simultaneously. To demonstrate this capability, you can borrow the StonesAndChips and Tarmac Device Databases from the ImageTargets sample and configure both to load and activate in the Datasets field of the ARCamera s Vuforia Configuration asset, which is accessible from the ARCamera's Inspector panel via the Open Vuforia Configuration button. You can also search for VuforiaConfiguration in the Project panel.This allows you to use targets from both Device Databases at the same time in your Unity scene.

Deploy the application

The next step is to deploy your application to a supported device.

Android deployment process

Unity provides a number of settings when building for Android devices select from the menu (File > Build Settings > Player Settings ) to see the current settings. Also, choose your platform now Android or iOS.

  1. Click Resolution and Presentation to select the required Default Orientation.
  2. Click Icon to set your application icon.
  3. Click Other Settings. Set the Minimum API Level to Android 4.1 'JellyBean' (API level 16) or higher. Set Bundle Identifier to a valid name (e.g., com.mycompany.firstARapp).
  4. Save your scene (File > Save Scene).
  5. Open the build menu (File > Build Settings ). Make sure that your scene is part of Scenes in Build. If not, do one of the following:
  • Use Add Current to add the currently active scene.
  • Drag and drop your saved AR scene from the project view into the Window.

You can now build the application. Attach your Android device and then click Build And Run to initialize the deployment process.

iOS deployment process

Unity provides a number of settings when building for iOS devices (File > Build Settings > Platform > iOS icon).

  1. Before building, select the required Default Orientation. Note:The Vuforia AR Extension now supports Auto Rotation.
  2. Make sure that Target Platform is not set to armv6 (OpenGL ES 1.1). As of Vuforia version 6.2, the Unity extension supports OpenGL-ES 2 and 3.
  3. Make sure that Bundle Identifier is set to the correct value for your iOS developer profile.
  4. Now you can choose to build the application. First, save your scene (File > Save Scene).
  5. Open the build menu (File > Build Settings ).
  6. Make sure that your scene is part of Scenes in Build. If this is not the case:
    a. Use Add Current to add the currently active scene.
    OR
    b. Drag and drop your saved AR scene from the project view into the Window.
  7. Press Build And Run to initialize the deployment process.

When building and running apps for iOS, Unity generates an Xcode project. It launches Xcode and loads this project. The Vuforia AR Extension includes a PostProcessBuildPlayer script that performs the task of integrating the Vuforia library into the generated Xcode project. This is run automatically when you select Build from within Unity. Be aware that if you manually change the generated Xcode project, you may need to update the PostProcessBuildPlayer script to avoid overwriting your changes.

The generated Xcode project includes a file called AppController.mm. There are Unity provided options in this file to tailor the performance of the app for your own purpose. The PostProcessBuildPlayer script sets the THREAD_BASED_LOOP as a default because it gives the best visible performance with the samples provided alongside the Vuforia AR Extension. Consider changing these options to whatever gives the best performance for your own application.

Created AR scene

Using the application

You should have a printout of the appropriate Image Target in front of you. If you are working with a target from one of the sample apps, the PDFs are located at Editor/Vuforia/ForPrint/*.pdf. Otherwise, print out the image that you uploaded to the Target Manager and make sure that the aspect ratio doesn t change. When you look at the target using the device camera, you should see your cube object bound to the target. Congratulations, you have successfully augmented reality!

Running in the editor

The Vuforia Unity Extension supports the Play Mode feature, which provides AR application emulation through the Unity Editor using a webcam. Configure this feature through the Web Cam field on the VuforiaConfiguration asset.

To use Play Mode for Vuforia in Unity select the webcam that you want to use from the Camera Device menu, and activate Play Mode using the Play button at the top of the Editor UI.

You can also use the standard Unity Play Mode by checking Disable Vuforia Play Mode in the Web Cam field.

To use standard Play Mode, adjust the transform of the ARCamera object to get your entire scene in view, and then run the application in the Unity editor. There is no live camera image or tracking in standard Play Mode; instead, all Targets are assumed to be visible. This allows you to test the non-AR components of your application, such as scripts and animations, without having to deploy to the device each time.