Working with the HoloLens sample in Unity

The Vuforia HoloLens Sample project provides a pre-configured Unity scene 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 Universal Windows Platform in File > Build Settings.
Vuforia Image
  1. Select the following platform build configuration settings
    SDK
     = Latest Installed
    UWP Build Type
     = D3D
  2. Define a unique Product Name, in Player Settings, to serve as the name of the app when installed on the HoloLens.
  3. Check Virtual Reality Supported and Vuforia Augmented Reality options, and set Virtual Reality SDKs to Windows Mixed Reality in "Player Settings > XR Settings".
Vuforia Image
  1. Check the following Capabilities in "Player Settings > Publish Settings"
    • InternetClient
    • WebCam
    • SpatialPerception - if you intend to use the Surface Observer API
Vuforia Image
  1. Open the "Vuforia Configuration" panel Window > Vuforia Configuration
  2. Select the following Digital Eyewear settings
    Device Type = "Digital Eyewear"
    Device Config = HoloLens
Vuforia Image
  1. Select Build to generate a Visual Studio project
  2. 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.

Vuforia Image

Scene elements & their configuration

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

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

Vuforia Image

Scene Hierarchy

ARCamera GameObject

The ARCamera is the scene camera rig for Vuforia Engine 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.

Vuforia Image

Vuforia Behaviour

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

The Open Vuforia Configuration button allows for quick access to the Vuforia Engine Configuration panel.

Voice Commands

The Voice Commands script on the ARCamera defines various voice commands available in the sample. Voice commands use the HoloLens Keyword Recognizer.

Frame Rate Settings

The Frame Rate Settings script configures Unity to run at the framerate recommended for the platform.

ImageTarget GameObjects

The ImageTarget GameObject encapsulates the ImageTargetBehavior and DefaultTrackableEventHandler. These are the primary script components that you will use to customize ImageTargets in a HoloLens application.
 

Vuforia Image

Image Target Behaviour

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

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.

    protected virtual void OnTrackingFound()
    {
        var rendererComponents = GetComponentsInChildren<Renderer>(true);
        var colliderComponents = GetComponentsInChildren<Collider>(true);
        var canvasComponents = GetComponentsInChildren<Canvas>(true);

        // Enable rendering:
        foreach (var component in rendererComponents)
            component.enabled = true;

        // Enable colliders:
        foreach (var component in colliderComponents)
            component.enabled = true;

        // Enable canvas':
        foreach (var component in canvasComponents)
            component.enabled = true;
    }


    protected virtual void OnTrackingLost()
    {
        var rendererComponents = GetComponentsInChildren<Renderer>(true);
        var colliderComponents = GetComponentsInChildren<Collider>(true);
        var canvasComponents = GetComponentsInChildren<Canvas>(true);

        // Disable rendering:
        foreach (var component in rendererComponents)
            component.enabled = false;

        // Disable colliders:
        foreach (var component in colliderComponents)
            component.enabled = false;

        // Disable canvas':
        foreach (var component in canvasComponents)
            component.enabled = false;
    }