Working with the HoloLens sample in Unity

The Vuforia HoloLens Sample project provides a pre-configured scene in the Unity Editor that you can use as a reference and starting point for your own Holographic apps that use Vuforia. This document will show you how to author a Vuforia scene for HoloLens, and how to customize event handling to implement custom app behaviors.

Also see: Developing Vuforia Apps for HoloLens

Supported Versions

See: Vuforia Supported Versions

Note that the Unity HoloLens Technical Preview does not currently support Vuforia s Play Mode simulator. You will need to deploy your apps to a device to run your HoloLens scenes. Alternatively you can develop your scene in an alternate version of Unity that supports Play Mode and then migrate it to the HTP edition when you re ready to deploy to HoloLens.

Importing the sample

To import the HoloLens sample into a new Unity project..
  1. Either double click on the HoloLens-x-x-x.unitypackage to launch the Import Package dialog or import the same Unity package by selecting it from the Unity Editor menu from Assets > Import Package > Custom Package.
  2. Click the Import buttons at the bottom right of the Importing Package window.

To import the HoloLens sample into an existing Vuforia Unity project..
  1. Follow the steps in the How To Migrate Your Existing Apps
  2. Follow the steps to import the HoloLens sample into a Unity project above.

To import the HoloLens sample into an existing Unity project that doesn t already contain the Vuforia Unity extension.
  1. Save a separate copy of your project.
  2. Either double click on the HoloLens -x.x.x.unitypackage to launch the Import Package dialog or import the same Unity package by selecting it from the Unity Editor menu from Assets > Import Package > Custom Package.
  3. Review the folder and asset names used in the sample project to determine if they will clash with named assets that you are using in your project, and if so abort the import, rename your assets, and return to step 2.
  4. Once you have ensured that there are no project conflicts, click the Import buttons at the bottom right of the Importing Package window.

Adding a License Key

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

Building and executing the sample

1. Apply the recommended Unity Engine Options for Power and Performance
2. Add the sample scenes to Scenes in Build
3. Set your platform build target for Windows Store in File > Build Settings.
4. Select the following platform build configuration settings
  • SDK = Universal10
  • UWP Build Type = D3D
5. Define a unique Product Name, in Player Settings, to serve as the name of the app when installed on the HoloLens.
6. Check Virtual Reality Supported and the Windows Holographic option in "Player Settings > Other Settings"
User-added image
7. Check the following Capabilities in "Player Settings > Publish Settings"
  • InternetClient
  • WebCam
  • SpatialPerception - if you intend to use the Surface Observer API
User-added image
10. Select Build to generate a Visual Studio project
11. Build the executable from Visual Studio and install it on your HoloLens.

See: https://developer.microsoft.com/en-us/windows/holographic/exporting_and_building_a_unity_visual_studio_solution

Visual Studio Build Configuration

Set your build target for x86.

Scene elements & their configuration

The HoloLens sample uses the ARCamera and ImageTarget prefabs. These can be found in the project s Vuforia folder along with the other assets and resources in this sample.

User-added image

The sample s scene Hierarchy demonstrates how to set-up a Vuforia HoloLens scene in Unity.

Scene Hierarchy

HoloLensCamera

The HoloLensCamera object is a standard Unity scene camera that has been configured the properties recommended for HoloLens apps. The sample shows how to bind this camera to the ARCamera to enable Vuforia to transform target poses into the HoloLens spatial coordinate system.

ARCamera

The ARCamera is the scene camera rig for Vuforia apps in Unity. It defines the properties of both of its child scene cameras, as well as the device camera and rendering behavior of the scene.


Components:

VuforiaConfiguration



Camera Device Mode setting enables you to prioritize render quality vs frame rate for your app. Selecting MODE_DEFAULT will typically prioritize rendering except on devices with lower performance characteristics.

Max Simultaneous Tracked Images this value defines the maximum number of targets that can be tracked simultaneously.

World Center Mode defines which object in the scene hierarchy will serve as the origin ( 0,0,0 ) of the scene s world space. When CAMERA is chosen the scene is rendered within the camera coordinate frame. This is the recommended World Center for Vuforia when developing a HoloLens app.

Database Load and Activate



Load Data Set automatically loads the associated dataset from Streaming Assets / QCAR when the app initializes.

Activate automatically activates the dataset after it is loaded.

Note: if you don t load and activate datasets through the Editor, you ll need to do so using the Vuforia API, See: How To Load and Activate Multiple Device Databases at Runtime

Voice Commands

The Voice Commands script on the ARCamera defines voice commands for starting and stopping Extended Tracking on the Image Targets, and registers these with the HoloLens Keyword Recognizer, it then starts the recognizer. This occurs when the app is first started.
User-added image

ImageTargetChips & ImageTargetStones

The ImageTarget prefabs encapsulate the ImageTargetBehavior and Default Trackable Event Handler. These are the primary script components that you will use to customize an app that uses HoloLens.

Components:

Image Target Behaviour

User-added image

Database identifies the database that contains the Image Target that will be assigned to this Image Target Behaviour

Image Target defines which target in the database to assign to this Image Target Behaviour

Enable Extended Tracking activates the extended tracking feature to support content registration when the target is not in view. This feature must be activated to enable Vuforia to work with the HoloLens spatial mapping engine.

Default Trackable Event Handler
The Default Trackable Event Handler component is responsible for handling callbacks to the Image Target Behaviour arising from changes in the state of the Image Target, such as when it has been detected and is then being tracked.

This script is used to enable and disable rendering and collision detection on digital content that is a child of the target.
Extend this script s OnTrackingFound() and OnTrackingLost() methods to implement custom event handling for your app.

User-added image