Merge pull request #290 from chrisfromwork/documentationFixes

Improve documentation for release/1.1.0

README.md

@@ -2,7 +2,11 @@
 
 Spectator View is an augmented reality product that enables viewing HoloLens experiences from secondary devices. Spectator View has multiple configurations and supports a variety of scenarios from filming quick prototypes to producing keynote demos.
 
-## Getting Started
+## Samples
+
+The Spectator View repository contains multiple sample projects. **The instructions for building and running samples will differ from instructions for adding the Spectator View codebase to your own project.** To see how to set up samples go [here](samples/README.md). To add Spectator View to your own project, see below.
+
+## Getting started with your own project
 
 ### Obtaining the code
 
@@ -49,13 +53,9 @@ Depending on what release you are using the correct setup script may vary. Choos
 
 ![Marker](doc/images/SetupRepo.png)
 
-### Samples
-
-After going through the setup steps in 'Obtaining the code' and 'Setting up your local environment', sample projects will be configured for use in your clone of the MixedReality-SpectatorView repository. It's easy to get started by building off one of the samples or by inspecting them to understand project setup. For more information, see [Samples](samples/README.md).
-
 ### Adding references to your own project
 
-After obtaining a local clone of the MixedReality-SpectatorView repository and resolving its external dependencies (see above), the suggested mechanism for referencing the code is by adding symbolic linked directories to your Unity project's Assets folder. You can do this with the following:
+After setting up a submodule for the MixedReality-SpectatorView repository and resolving its external dependencies (see above), the suggested mechanism for referencing the code is by adding symbolic linked directories to your Unity project's Assets folder. You can do this with the following:
 
 > Note: Symbolic linked directories should be setup as relative paths. Using relative paths should allow directories to resolve correctly regardless of where you or your team members clone your project repository in their local file systems. The instructions below demonstrate setting up symbolic linked directories based on the following paths:
 >* **Project repository directory:** c:\Your\Unity\Project

doc/SpectatorView.Architecture.md

@@ -20,7 +20,7 @@
 
 ### 2. Spectating with a video camera rig
 
-1. A HoloLens is mounted to the video camera. [Calibration](SpectatorView.Setup.VideoCamera.md) is then performed to calculate camera intrinsics (Properties such as lens focal length and principal points that are needed for compositing holograms into the video camera feed) and camera extrinsics (The transform of the video camera to the mounted HoloLens). This data is stored on this HoloLens mounted to the video camera.
+1. A HoloLens is mounted to the video camera. [Calibration](SpectatorView.Setup.VideoCamera.md#calibration) is then performed to calculate camera intrinsics (Properties such as lens focal length and principal points that are needed for compositing holograms into the video camera feed) and camera extrinsics (The transform of the video camera to the mounted HoloLens). This data is stored on this HoloLens mounted to the video camera.
 2. The PC obtains a video camera stream through a capture card.
 3. The PC connects to sockets open on both the user HoloLens and video camera rig HoloLens through the unity editor.
 4. The PC obtains camera intrinsic and extrinsic information from the DSLR mounted HoloLens and updates its unity camera to reflect these values.

doc/SpectatorView.Setup.VideoCamera.md

@@ -29,7 +29,7 @@ Documentation below highlights the process of setting up a Video Camera filming
 
 Video camera filming relies on a physically mounted HoloLens 2 device generating position and orientation information for your video camera in the shared application space. This allows the Unity editor to understand where the video frame was filmed from in order to generate and composite Holograms into the feed. To get accurate tracking of your video camera in the physical world, you need to calculate the physical transform between the HoloLens 2 device and the video camera sensor. This is achieved through calibration.
 
-The below instructions assume that you have already gone through the repository setup instructions [here](../README.md) to obtain and reference the Spectator View codebase.
+The below instructions assume that you have already gone through the repository setup instructions [here](../README.md#getting-started-with-your-own-project) to obtain and reference the Spectator View codebase.
 
 ## Setup
 

doc/SpectatorView.Setup.md

@@ -39,11 +39,11 @@ To setup spectator view with a video camera, see [here](SpectatorView.Setup.Vide
 
 # Preparing your project
 
-To use the Spectator View codebase, its suggested to clone and reference the MixedReality-SpectatorView repository through symbolic linked directories in your Unity project. Before beginning on the steps below, go through the repository setup process [here](../README.md). This will ensure that the Unity editor components referenced below exist in your project.
+To use the Spectator View codebase, its suggested to clone and reference the MixedReality-SpectatorView repository through symbolic linked directories in your Unity project. Before beginning on the steps below, go through the repository setup process [here](../README.md#getting-started-with-your-own-project). This will ensure that the Unity editor components referenced below exist in your project.
 
 ## Spatial Alignment Strategy Dependencies
 
-Spectator View requires multiple devices understanding a shared application origin in the physical world. In order to establish this shared application origin, you will need to choose and use a spatial alignment strategy. Different dependencies are needed for different strategies. For more information on spatial alignment strategies, see [here](../src/SpectatorView.Unity/Assets/SpatialAlignment/README.md).
+Spectator View requires multiple devices understanding a shared application origin in the physical world. In order to establish this shared application origin, you will need to choose and use a [spatial alignment strategy](../src/SpectatorView.Unity/Assets/SpatialAlignment/README.md#detailed-breakdown-of-spatial-alignment-strategies). You will only need to go through one setup process below for the spatial alignment strategy you choose.
 
 Not all spatial alignment strategies support all platforms. See the chart below to determine which strategy best addresses your intended user scenarios.
 
@@ -122,7 +122,7 @@ If you are building Azure Spatial Anchors on iOS, you will need to take some add
 
 > Note: **Asset Caches need to be updated on one development machine and shared across development machines**. Asset Caches aren't currently created in a deterministic manner and can't be recreated in new development environments. The easiest way to share this with a team is to commit changes to the Generated.StateSynchronization.AssetCaches folder that will appear in the Unity project's Assets directory. For more information on Asset Caches see [SpectatorView.StateSynchronization](../src/SpectatorView.Unity/Assets/SpectatorView/Scripts/StateSynchronization/README.md).
 
-### HoloLens 2 & HoloLens
+### HoloLens 2 & HoloLens as the Host/User
 
 1. Make sure your Unity project contains the asset caches that were created in the 'Before building' steps.
 2. Open the project scene that you intend to use with SpectatorView. (**Note:** For spectating with a HoloLens device, use `SpectatorView.HoloLens.Spectator` scene.)
@@ -136,6 +136,14 @@ If you are building Azure Spatial Anchors on iOS, you will need to take some add
 5. Press the 'HoloLens' button on the `Platform Switcher` attached to `Spectator View` in the Unity inspector (This should configure the correct build settings and app capabilities).
 6. Build and deploy the application to your HoloLens device.
 
+### HoloLens 2 & HoloLens as a Spectator
+
+1. Make sure your Unity project contains the asset caches that were created in the 'Before building' steps.
+2. Open the `SpectatorView.HoloLens.Spectator` Unity scene.
+3. Press the 'HoloLens' button on the `Platform Switcher` attached to `Spectator View` in the Unity inspector (This should configure the correct build settings and app capabilities).
+4. Declare the `SpectatorView.HoloLens.Spectator` as the scene included in your Unity Build settings.
+5. Build and deploy the application to your HoloLens device.
+
 ### Android
 
 1. Make sure your Unity project contains the asset caches that were created in the 'Before building' steps.
@@ -147,9 +155,12 @@ If you are building Azure Spatial Anchors on iOS, you will need to take some add
 
 5. Make sure to declare the SpectatorView.Android scene as the scene included. If SpectatorView.Android does not exist in your list of scenes to choose from in the build settings, open the scene in the Unity editor. Then reopen the build settings and press 'Add Open Scenes'.
 
-![Marker](images/AndroidSceneSelection.png)
+![Marker](images/AndroidSpectatorViewExampleBuildSettings.png)
+
+6. `Build and Run` the application through Unity's Build Settings. If you're targeting a new Android development device, you may need to enable developer options and debugging. For information on setting up your Android device for debugging, see [here](https://developer.android.com/studio/debug/dev-options).
 
-6. Build and deploy the application. If you're targeting a new Android development device, you may need to enable developer options and debugging. For information on setting up your Android device for debugging, see [here](https://developer.android.com/studio/debug/dev-options).
+> Note: You may need to the `Run Device` dropdown to find your desired Android device.
+> ![Marker](images/AndroidDeviceSelectorBuildSettings.png)
 
 ### iOS
 

docfx.json

@@ -36,6 +36,7 @@
           "src/SpectatorView.Native/**/*.md",
           "samples/README.md",
           "samples/Build2019Demo.Unity/README.md",
+          "samples/SpectatorView.Example.Unity/README.md",
           "doc/*.md" ]
       }
     ],

samples/Build2019Demo.Unity/README.md

@@ -1,6 +1,6 @@
 # //BUILD 2019 Demo
 
-This sample of using SpectatorView is very similar to the live code demo presented at //BUILD 2019 conference.
+This sample of using SpectatorView is very similar to the live code demo presented at //BUILD 2019 conference. It showcases the [Azure Spatial Anchors](https://azure.microsoft.com/en-us/services/spatial-anchors/) alignment strategy.
 
 [![//BUILD 2019 Video](../../doc/images/Build2019DemoVideo.png)](https://www.youtube.com/watch?v=P8og3nC5FaQ&t=2255 "//BUILD 2019 Video")
 
@@ -12,7 +12,7 @@ In order to run the demo, you will need at least two MR/AR capable devices. You
 
 ### Instructions
 
-These instructions assume that a HoloLens 2 device will be used to host the shared experience and that an Android phone will be used to spectate the shared experience. For iOS, replace references to Android with iOS.
+These instructions assume that a HoloLens 2 device will be used to host the shared experience and that a mobile device will be used to spectate the shared experience.
 
 #### Prepare your local codebase
 
@@ -38,24 +38,30 @@ These instructions assume that a HoloLens 2 device will be used to host the shar
 
 ##### HoloLens 2
 
-1. Build UWP Player containing `Demo/Scenes/Finished_Scene.unity` scene, and deploy this application to the HoloLens 2 device.
-2. Launch the `SpectatorView.Build2019Demo` on the HoloLens 2, and wait for the experience to start.
+1. Select `HoloLens` as your target platform using Spectator View's `PlatformSwitcher` (This can be found in the Unity inspector for the `SpectatorView` prefab GameObject).
+2. Build UWP Player containing `Demo/Scenes/Finished_Scene.unity` scene, and deploy this application to the HoloLens 2 device.
+3. Launch the `SpectatorView.Build2019Demo` on the HoloLens 2, and wait for the experience to start.
+
+![Marker](./../../doc/images/HoloLensBuild2019SampleBuildSettings.png)
 
 ##### Android
 
-1. Export Android Player containing `MixedReality-SpectatorView/SpectatorView/Scenes/SpectatorView.Android.unity` scene to an Android Studio solution.
-2. Open the Android Studio solution and change the main activity in the AndroidManifest.xml file to `Microsoft.MixedReality.SpectatorView.Unity.ScreenRecorderActivity`.
-3. Update the AndroidManifest.xml in Android Studio to contain `android.permission.CAMERA`, `android.permission.INTERNET`, `android.permission.RECORD_AUDIO` and `android.permission.WRITE_EXTERNAL_STORAGE` uses-permissions.
-4. Build the Android Studio solution and deploy this application to the spectating Android device.
-5. Launch the `SpectatorView.Build2019Demo` on the Android device and connect to the HoloLens device by specifying the HoloLens's IP Address.
+1. Select `Android` as your target platform using Spectator View's `PlatformSwitcher` (This can be found in the Unity inspector for the `SpectatorView` prefab GameObject).
+2. `Build and Run` the Android Player containing `MixedReality-SpectatorView/SpectatorView/Scenes/SpectatorView.Android.unity`.
+3. Launch the `SpectatorView.Build2019Demo` on the Android device and connect to the HoloLens device by specifying the HoloLens's IP Address.
+
+![Marker](./../../doc/images/AndroidBuild2019SampleBuildSettings.png)
 
 ##### iOS
 
-1. Build the iOS Player containing `MixedReality-SpectatorView/SpectatorView/Scenes/SpectatorView.iOS.unity` scene.
-2. Follow the Azure Spatial Anchors [official instructions](https://docs.microsoft.com/en-us/azure/spatial-anchors/quickstarts/get-started-unity-ios#open-the-xcode-project).
-5. Launch the `SpectatorView.Build2019Demo` on the iOS device and connect to the HoloLens device by specifying the HoloLens's IP Address.
+1. Select `iOS` as your target platform using Spectator View's `PlatformSwitcher` (This can be found in the Unity inspector for the `SpectatorView` prefab GameObject).
+2. Build the iOS Player containing `MixedReality-SpectatorView/SpectatorView/Scenes/SpectatorView.iOS.unity` scene.
+3. Follow the Azure Spatial Anchors [official instructions](https://docs.microsoft.com/en-us/azure/spatial-anchors/quickstarts/get-started-unity-ios#open-the-xcode-project).
+4. Launch the `SpectatorView.Build2019Demo` on the iOS device and connect to the HoloLens device by specifying the HoloLens's IP Address.
+
+![Marker](./../../doc/images/iOSBuild2019SampleBuildSettings.png)
 
-> Note 1: Additional setup instructions and troubleshooting for spectating with mobile devices can be found [here](../../doc/SpectatorView.Setup.md).
+> Note 1: Additional setup instructions and troubleshooting for spectating with mobile devices can be found [here](../../doc/SpectatorView.Setup.md#building--deploying).
 
 ## Sample Project Contents
 
@@ -75,4 +81,4 @@ The demo consists of a simple experience with a buttons panel and a slider, conf
 The MixedRealityToolkit-Unity project introduces some dependencies on System.Numerics.* types that can cause errors when building the UWP player. That going said, although these errors are generated during the build, they do not prevent the build from succeeding. Its suggested to ignore these errors when building the sample application for the time being.
 
 ### __Additional Issues__
-For more information on troubleshooting other build issues, checkout the `Troubleshooting` section in our detailed setup steps [here](../../doc/SpectatorView.Setup.md).
+For more information on troubleshooting other build issues, checkout the `Troubleshooting` section in our detailed setup steps [here](../../doc/SpectatorView.Setup.md#troubleshooting).

samples/README.md

@@ -1,22 +1,22 @@
 # Spectator View Samples
 
-This folder contains sample and demo projects that are maintained by the SpectatorView team. Below you will find the instructions on how to get started, as well as the sample folder structure setup and dependencies.
+This folder contains sample and demo projects that are maintained by Spectator View contributors. Below you will find the instructions on how to get started, as well as the sample folder structure setup and dependencies.
 
 ## Getting Started
 
-Ensure you have all the required software, for detailed instructions see [Required Software](../doc/SpectatorView.Setup.md).
+Ensure you have all the required software, for detailed instructions see [Required Software](../doc/SpectatorView.Setup.md#software--hardware-requirements).
 
 - Git Tools
 - Visual Studio
 - Unity 2018.3.14f1
-- __(Optional)__ Windows 10.0.18362.0 SDK
+- Windows 10.0.18362.0 SDK
 - __(Optional)__ Android Studio
 - __(Optional)__ XCode
 
 Once you have the required software, follow these steps:
 
-1. Using your favorite Git management tool, clone this repository if you haven't yet.
-2. Then with git, pull the latest version of the code.
+1. Using your favorite Git management tool, clone this repository.
+2. Then with git, checkout the latest release of the code. (This will be the `release/*.*.` branch with the highest version number)
 3. Run `/tools/scripts/SetupRepository.bat` as an administrator to get ensure the appropriate submodules for the sample projects are cloned and the correct directories are linked into the sample project.
     - On Mac or Linux, you can run `/tools/scripts/SetupRepository.sh`.
 
@@ -26,7 +26,12 @@ Once you have the required software, follow these steps:
 
 This repository currently has the following samples:
 
-- [//BUILD 2019 Demo](./Build2019Demo.Unity/README.md)
+1. [//BUILD 2019 Demo](./Build2019Demo.Unity/README.md)
+    - This sample shows how to use [Azure Spatial Anchors](https://azure.microsoft.com/en-us/services/spatial-anchors/) to spatially align devices in the physical world.
+    - This sample also shows to use Spectator View with the [Mixed Reality Toolkit](http://aka.ms/mrtk).
+2. [SpectatorView.Example.Unity](./SpectatorView.Example.Unity/README.md)
+    - This sample shows how to use [QR Code detection](https://docs.microsoft.com/en-us/windows/mixed-reality/qr-code-tracking) on HoloLens 2 to spatially align devices in the physical world.
+    - This sample can also use [ArUco marker detection](https://docs.opencv.org/master/d5/dae/tutorial_aruco_detection.html) on HoloLens 1 to spatially align devices in the physical world.
 
 ## Troubleshooting