Skip to content

Commit 547e179

Browse files
American-DipperAmerican-Dipper
authored
Merge pull request #76844 from julianparismorgan/asa-start-from-scratch-unity-hololens
Tutorial on starting from scratch with a new Unity / HoloLens app with Azure Spatial Anchors
2 parents 57134ad + becd10d commit 547e179

File tree

4 files changed

+604
-2
lines changed

4 files changed

+604
-2
lines changed

‎articles/spatial-anchors/toc.yml

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -28,6 +28,8 @@
2828
href: tutorials/tutorial-share-anchors-across-devices.md
2929
- name: Sharing in Unity with Azure Cosmos DB
3030
href: tutorials/tutorial-use-cosmos-db-to-store-anchors.md
31+
- name: Starting a new Unity HoloLens app
32+
href: tutorials/tutorial-new-unity-hololens-app.md
3133
- name: Starting a new Android app
3234
href: tutorials/tutorial-new-android-app.md
3335
- name: How-to

‎articles/spatial-anchors/tutorials/tutorial-new-unity-hololens-app.md

Lines changed: 202 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,202 @@
1+
---
2+
title: Tutorial - Step-by-step instructions to create a new HoloLens Unity app using Azure Spatial Anchors | Microsoft Docs
3+
description: In this tutorial, you learn how to create a new HoloLens Unity app using Azure Spatial Anchors.
4+
author: julianparismorgan
5+
manager: vriveras
6+
services: azure-spatial-anchors
7+
8+
ms.author: pmorgan
9+
ms.date: 05/14/2019
10+
ms.topic: tutorial
11+
ms.service: azure-spatial-anchors
12+
---
13+
14+
# Tutorial: Step-by-step instructions to create a new HoloLens Unity app using Azure Spatial Anchors
15+
16+
This tutorial will show you how to create a new HoloLens Unity app with Azure Spatial Anchors.
17+
18+
## Prerequisites
19+
20+
To complete this tutorial, make sure you have:
21+
22+
1. A Windows machine with <a href="https://www.visualstudio.com/downloads/" target="_blank">Visual Studio 2017+</a> installed with the **Universal Windows Platform development** workload and the **Windows 10 SDK (10.0.17763.0 or newer)** component, and <a href="https://git-scm.com/download/win" target="_blank">Git for Windows</a>.
23+
2. The [C++/WinRT Visual Studio Extension (VSIX)](https://aka.ms/cppwinrt/vsix) for Visual Studio should be installed from the [Visual Studio Marketplace](https://marketplace.visualstudio.com/).
24+
3. A HoloLens device with [developer mode](https://docs.microsoft.com/windows/mixed-reality/using-visual-studio) enabled. This article requires a HoloLens device with the [Windows 10 October 2018 Update](https://docs.microsoft.com/windows/mixed-reality/release-notes-october-2018 ) (also known as RS5). To update to the latest release on HoloLens, open the **Settings** app, go to **Update & Security**, then select the **Check for updates** button.
25+
26+
## Getting started
27+
28+
We'll first set up our project and Unity scene:
29+
1. Start Unity.
30+
2. Select **New**.
31+
4. Ensure **3D** is selected.
32+
5. Name your project and enter a save **Location**.
33+
6. Click **Create project**.
34+
7. Save the empty default scene to a new file using: **File** > **Save As**.
35+
8. Name the new scene **Main** and press the **Save** button.
36+
37+
**set up the Project Settings**
38+
39+
We'll now set some Unity project settings that help us target the Windows Holographic SDK for development.
40+
41+
First, lets set quality settings for our application.
42+
1. Select **Edit** > **Project Settings** > **Quality**
43+
2. In the column under the **Windows Store** logo, click on the arrow at the **Default** row and select **Very Low**. You'll know the setting is applied correctly when the box in the **Windows Store** column and **Very Low** row is green.
44+
45+
We need to let Unity know that the app we are trying to export should create an immersive view instead of a 2D view. We create an immersive view by enabling Virtual Reality support on Unity targeting the Windows 10 SDK.
46+
47+
1. Go to **Edit** > **Project Settings** > **Player**.
48+
2. In the **Inspector Panel** for **Player Settings**, select the **Windows Store** icon.
49+
3. Expand the **XR Settings** group.
50+
4. In the **Rendering** section, check the **Virtual Reality Supported** checkbox to add a new **Virtual Reality SDK's** list.
51+
5. Verify that **Windows Mixed Reality** appears in the list. If not, select the **+** button at the bottom of the list and choose **Windows Mixed Reality**.
52+
53+
> [!NOTE]
54+
> If you do not see the Windows Store icon, double check to make sure you selected the Windows Store .NET Scripting Backend prior to installation. If not, you may need to reinstall Unity with the correct Windows installation.
55+
56+
**verify .NET configuration**
57+
1. Go to **Edit** > **Project Settings** > **Player** (you may still have **Player** open from the previous step).
58+
2. In the **Inspector Panel** for **Player Settings**, select the **Windows Store** icon.
59+
3. In the **Other Settings** Configuration section, make sure that **Scripting Backend** is set to **.NET**.
60+
61+
**set capabilities**
62+
1. Go to **Edit** > **Project Settings** > **Player** (you may still have **Player** open from the previous step).
63+
2. In the **Inspector Panel** for **Player Settings**, select the **Windows Store** icon.
64+
3. In the **Publishing Settings** Configuration section, check **InternetClientServer** and **SpatialPerception**.
65+
66+
**set up the main virtual camera**
67+
1. In the **Hierarchy Panel**, select **Main Camera**.
68+
2. In the **Inspector**, set its transform position to **0,0,0**.
69+
3. Find the **Clear Flags** property, and change the dropdown from **Skybox** to **Solid Color**.
70+
4. Click on the **Background** field to open a color picker.
71+
5. Set **R, G, B, and A** to **0**.
72+
6. Select **Add Component** and search for **Spatial Mapping Collider**.
73+
74+
**create our script**
75+
1. In the **Project** pane, create a new folder, **Scripts**, under the **Assets** folder.
76+
2. Right click on the folder, then select **Create >**, **C# Script**. Title it **AzureSpatialAnchorsScript**.
77+
3. Go to **GameObject** -> **Create Empty**.
78+
4. Select it, and in the **Inspector** rename it from **GameObject** to **MixedRealityCloud**. Select **Add Component** and search for and add the **AzureSpatialAnchorsScript**.
79+
80+
## Trying it out
81+
To test out that everything is working, build your app in **Unity** and deploy it from **Visual Studio**. Follow Chapter 6 from the [**MR Basics 100: Getting started with Unity** course](https://docs.microsoft.com/windows/mixed-reality/holograms-100#chapter-6---build-and-deploy-to-device-from-visual-studio) to do so. You should see the Unity start screen, and then a clear display.
82+
83+
## Place an object in the real world
84+
Let's create & place an object using your app. Open the Visual Studio solution that we created when we [deployed our app](#trying-it-out).
85+
86+
First, add the following imports into your `Assembly-CSharp (Universal Windows)\Scripts\AzureSpatialAnchorsScript.cs`:
87+
88+
[!code-csharp[AzureSpatialAnchorsScript](../../../includes/spatial-anchors-new-unity-hololens-app-finished.md?range=19-24)]
89+
90+
Then, add the following members variables into your `AzureSpatialAnchorsScript` class:
91+
92+
[!code-csharp[AzureSpatialAnchorsScript](../../../includes/spatial-anchors-new-unity-hololens-app-finished.md?range=26-37,43-47,55-74)]
93+
94+
Next, add the following code into your `Start()` method. This code will hook up `GestureRecognizer`, which will detect when there is an air tap and call `HandleTap`.
95+
96+
[!code-csharp[AzureSpatialAnchorsScript](../../../includes/spatial-anchors-new-unity-hololens-app-finished.md?range=76-85,88&highlight=4-10)]
97+
98+
We now have to add the following `HandleTap()` method below `Update()`. It will do a ray cast and get a hit point at which to place a sphere.
99+
100+
[!code-csharp[AzureSpatialAnchorsScript](../../../includes/spatial-anchors-new-unity-hololens-app-finished.md?range=264-274,295-297,301-309)]
101+
102+
We now need to create the sphere. The sphere will initially be white, but this value will be adjusted later on. Add the following `CreateAndSaveSphere()` method:
103+
104+
[!code-csharp[AzureSpatialAnchorsScript](../../../includes/spatial-anchors-new-unity-hololens-app-finished.md?range=311-324,389)]
105+
106+
Run your app from **Visual Studio** to validate it once more. This time, tap the screen to create & place your white sphere over the surface of your choice.
107+
108+
## Set up the dispatcher pattern
109+
110+
When working with Unity, all Unity APIs, for example APIs you use to do UI updates, need to happen on the main thread. In the code we'll write however, we get callbacks on other threads. We want to update UI in these callbacks, so we need a way to go from a side thread onto the main thread. To execute code on the main thread from a side thread, we'll use the dispatcher pattern.
111+
112+
Let's add a member variable, dispatchQueue, which is a Queue of Actions. We will push Actions onto the queue, and then dequeue and run the Actions on the main thread.
113+
114+
[!code-csharp[AzureSpatialAnchorsScript](../../../includes/spatial-anchors-new-unity-hololens-app-finished.md?range=33-46&highlight=6-9)]
115+
116+
Next, let's add a way to add an Action to the Queue. Add `QueueOnUpdate()` right after `Update()` :
117+
118+
[!code-csharp[AzureSpatialAnchorsScript](../../../includes/spatial-anchors-new-unity-hololens-app-finished.md?range=102-112)]
119+
120+
Let's now use the Update() loop to check if there is an Action queued. If so, we will dequeue the action and run it.
121+
122+
[!code-csharp[AzureSpatialAnchorsScript](../../../includes/spatial-anchors-new-unity-hololens-app-finished.md?range=90-100&highlight=4-10)]
123+
124+
## Get the Azure Spatial Anchors SDK
125+
126+
We'll now download the Azure Spatial Anchors SDK. Go to [Azure Spatial Anchors GitHub releases page](https://github.com/Azure/azure-spatial-anchors-samples/releases). Under Assets, download the **AzureSpatialAnchors.unitypackage** file.
127+
128+
In Unity, go to **Assets**, click **Import Package** > **Custom Package...**. Navigate to the package and select **Open**.
129+
130+
In the new **Import Unity Package** window that pops up, select **None** at the bottom left. Then under **AzureSpatialAnchorsPlugin** > **Plugins**, select **Common**, **Editor**, and **HoloLens**. Click **Import** in the bottom-right corner.
131+
132+
We now need to restore Nuget packages in order to get Azure Spatial Anchors SDK. Build from **Unity** and then open and build the resulting **Visual Studio** solution again, as detailed in [Trying it out](#trying-it-out).
133+
134+
In your **Visual Studio** solution, add the following import into your `<ProjectName>\Assets\Scripts\AzureSpatialAnchorsScript.cs`:
135+
136+
[!code-csharp[AzureSpatialAnchorsScript](../../../includes/spatial-anchors-new-unity-hololens-app-finished.md?range=18-21&highlight=1)]
137+
138+
Then, add the following member variables into your `AzureSpatialAnchorsScript` class:
139+
140+
[!code-csharp[AzureSpatialAnchorsScript](../../../includes/spatial-anchors-new-unity-hololens-app-finished.md?range=43-58&highlight=6-11)]
141+
142+
## Attach a local Azure Spatial Anchor to the local anchor
143+
144+
Let's set up Azure Spatial Anchor's CloudSpatialAnchorSession. We'll start by adding the following `InitializeSession()` method inside your `AzureSpatialAnchorsScript` class. Once called, it will ensure an Azure Spatial Anchors session is created and properly initialized during the startup of your app.
145+
146+
[!code-csharp[AzureSpatialAnchorsScript](../../../includes/spatial-anchors-new-unity-hololens-app-finished.md?range=169-197,200-204)]
147+
148+
We now need to write code to handle delegate calls. We'll add more to them as we continue.
149+
150+
[!code-csharp[AzureSpatialAnchorsScript](../../../includes/spatial-anchors-new-unity-hololens-app-finished.md?range=206-221)]
151+
152+
Now, let's hook your `initializeSession()` method into your `Start()` method.
153+
154+
[!code-csharp[AzureSpatialAnchorsScript](../../../includes/spatial-anchors-new-unity-hololens-app-finished.md?range=76-88&highlight=12)]
155+
156+
Finally, add the following code into your `CreateAndSaveSphere()` method. It will attach a local Azure Spatial Anchor to the sphere that we're placing in the real world.
157+
158+
[!code-csharp[AzureSpatialAnchorsScript](../../../includes/spatial-anchors-new-unity-hololens-app-finished.md?range=311-337,390&highlight=16-31)]
159+
160+
Before proceeding any further, you'll need to create an Azure Spatial Anchors account Identifier and Key, if you don't already have them. Follow the following section to obtain them.
161+
162+
[!INCLUDE [Create Spatial Anchors resource](../../../includes/spatial-anchors-get-started-create-resource.md)]
163+
164+
## Upload your local anchor into the cloud
165+
166+
Once you have your Azure Spatial Anchors account Identifier and Key, go and paste the `Account Id` into `SpatialAnchorsAccountId` and the `Account Key` into `SpatialAnchorsAccountKey`.
167+
168+
Finally, let's hook everything together. In your `SpawnNewAnchoredObject()` method, add the following code. It will invoke the `CreateAnchorAsync()` method as soon as your sphere is created. Once the method returns, the code below will perform one final update to your sphere, changing its color to blue.
169+
170+
[!code-csharp[AzureSpatialAnchorsScript](../../../includes/spatial-anchors-new-unity-hololens-app-finished.md?range=311-389&highlight=28-78)]
171+
172+
Run your app from **Visual Studio** once more. Move around your head and then air tap to place your sphere. Once we have enough frames, the sphere will turn into yellow, and the cloud upload will start. Once the upload finishes, your sphere will turn blue. Optionally, you could also use the Output window inside **Visual Studio** to monitor the log messages your app is sending. You'll be able to watch the recommended for create progress, as well as the anchor identifier that the cloud returns once the upload is completed.
173+
174+
> [!NOTE]
175+
> If you get "DllNotFoundException: Unable to load DLL 'AzureSpatialAnchors': The specified module could not be found.", you should **Clean** and **Build** your solution again.
176+
177+
## Locate your cloud spatial anchor
178+
179+
One your anchor is uploaded to the cloud, we're ready to attempt locating it again. Let's add the following code into your `HandleTap()` method. This code will:
180+
181+
* Call `ResetSession()`, which will stop the `CloudSpatialAnchorSession` and remove our existing blue sphere from the screen.
182+
* Initialize `CloudSpatialAnchorSession` again. We do this so we're sure the anchor we're going to locate comes from the cloud instead of being the local anchor we created.
183+
* Create a **Watcher** that will look for the anchor we uploaded to Azure Spatial Anchors.
184+
185+
[!code-csharp[AzureSpatialAnchorsScript](../../../includes/spatial-anchors-new-unity-hololens-app-finished.md?range=264-302&highlight=13-31,34-36)]
186+
187+
Let's now add our `ResetSession()` and `CleanupObjects()` methods. You can put them below `QueueOnUpdate()`
188+
189+
[!code-csharp[AzureSpatialAnchorsScript](../../../includes/spatial-anchors-new-unity-hololens-app-finished.md?range=114-167)]
190+
191+
We now need to hook up the code that will be invoked when the anchor we're querying for is located. Inside of `InitializeSession()`, add the following callbacks:
192+
193+
[!code-csharp[AzureSpatialAnchorsScript](../../../includes/spatial-anchors-new-unity-hololens-app-finished.md?range=195-201&highlight=4-5)]
194+
195+
196+
Now lets add code that will create & place a green sphere once the CloudSpatialAnchor is located. It will also enable screen tapping again, so you can repeat the whole scenario once more: create another local anchor, upload it, and locate it again.
197+
198+
[!code-csharp[AzureSpatialAnchorsScript](../../../includes/spatial-anchors-new-unity-hololens-app-finished.md?range=223-262)]
199+
200+
That's it! Run your app from **Visual Studio** one last time to try out the whole scenario end to end. Move around your device, and place your white sphere. Then, keep moving your head to capture environment data until the sphere turns yellow. Your local anchor will be uploaded, and your sphere will turn blue. Finally, tap your screen once more, so that your local anchor is removed, and then we'll query for its cloud counterpart. Continue moving your device around until your cloud spatial anchor is located. A green sphere should appear in the correct location, and you can rinse & repeat the whole scenario again.
201+
202+
[!INCLUDE [AzureSpatialAnchorsScript](../../../includes/spatial-anchors-new-unity-hololens-app-finished.md)]

‎articles/spatial-anchors/tutorials/tutorial-use-cosmos-db-to-store-anchors.md

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -67,7 +67,7 @@ Locate the `StorageConnectionString` property, and set the value to be the same
6767

6868
## Next steps
6969

70-
In this tutorial, you've used Azure Cosmos DB to share anchor identifiers across devices. To learn more about how to use Azure Spatial Anchors in a new Android app, continue to the next tutorial.
70+
In this tutorial, you've used Azure Cosmos DB to share anchor identifiers across devices. To learn more about how to use Azure Spatial Anchors in a new Unity HoloLens app, continue to the next tutorial.
7171

7272
> [!div class="nextstepaction"]
73-
> [Starting a new Android app](./tutorial-new-android-app.md)
73+
> [Starting a new Android app](./tutorial-new-unity-hololens-app.md)

0 commit comments

Comments
 (0)