Merge pull request #3774 from davidkline-ms/docs_spatial

Getting started documentation for spatial awareness

Author: keveleigh

Documentation/SpatialAwareness/ConfiguringSpatialAwarenessMeshObserver.md

@@ -0,0 +1,114 @@
+# Configuring the Spatial Awareness Mesh Observer
+
+The spatial swareness mesh observer profile provides options for configuring:
+- [General Settings](#general-settings)
+- [Physics Settings](#physics-settings)
+- [Level of Detail Settings](#level-of-detail-settings)
+- [Display Settings](#display-settings)
+
+## General Settings
+
+![Mesh Observer General Settings](../../External/ReadMeImages/SpatialAwareness/MeshObserverGeneralSettings.png)
+
+### Startup Behavior
+
+The startup behavior specifies the behavior of the observer when it is first instantiated. The options are Auto Start and Manual Start. When set to Manual Start, applications will need to call one of the following IMixedRealitySpatialAwarenessSystem methods:
+
+- ResumeObserver<T>(string name)
+- ResumeObservers()
+- ResumeObservers<T>()
+
+The default value is Auto Start.
+
+### Update Interval
+
+The time, in seconds, between requests to the platform to update spatial mesh data. Typical values fall in the range of 0.1 and 5.0 seconds. 
+
+### Is Stationary Observer
+
+Indicates whether or not the observer is to remain stationary or to move and update with the user.
+
+> When stationary, if user moves further than the [Observation Extents](#observation-extents) away from the origin. In this instance, there would be no mesh data around the user until they moved closer to the origin.
+
+### Observer Shape
+
+The observer shape defines the type of volume that the mesh observer will use when observing meshes. The supported options are:
+
+- [Axis Aligned Cube](#axis-aligned-cube)
+- [User Aligned Cube](#user-aligned-cube)
+- Sphere
+
+#### Axis Aligned Cube
+
+An axis aligned cube volume is a rectangular shape that stays aligned with the axes of the world coordinate system, as determened at application startup.
+
+#### User Aligned Cube
+
+A user aligned cube volume is a rectangular shape that rotates to align with the users local coordinate system.
+
+### Observation Extents
+
+The observation extents define the distance from the observation point that meshes will be observed. When the [Observer Shape](#observer-shape) is set to Sphere, the X value of the extents will be used as the radius of the sphere.
+
+## Physics Settings
+
+![Mesh Observer Physics Settings](../../External/ReadMeImages/SpatialAwareness/MeshObserverPhysicsSettings.png)
+
+### Physics Layer
+
+The physics layer specifies which layer on which the spatial mesh objects will be placed in order to interact with the Unity Physics and RayCast systems. The Mixed Reality Toolkit reserves layer 31 by default for use by Spatial Awareness observers.
+
+#### Recalculate Normals
+
+Specifies whether or not the mesh observer will recalculate the normals of the mesh following observation. This setting is available to ensure applications receive meshes that contain valid normals data on platforms that do not return them with meshes. 
+
+## Level of Detail Settings
+
+![Mesh Observer Level of Detail Settings](../../External/ReadMeImages/MeshObserverLevelOfDetailSettings.png)
+
+### Level of Detail
+
+Specifies the level of detail (LOD) of the spatial mesh data. Currently defined values are Coarse, Fine and Custom.
+
+The Coarse LOD generally place a smaller impact on application performance and are an excellent choice for navigation and plane finding.
+
+The Fine LOD generally exact a higher performance impact on application performance and are a great option for occlusion meshes.
+
+The Custom LOD require the application to specify the [Triangles / Cubic Meter](#triangles-per-cubic-meter) value and allows applications to tune the accuracy vs. performance impact of the spatial mesh observer.
+
+> Note: It is not guaranteed that all Triangles/Cubic Meter values are honored by all platforms. Experimentation and profiling is highlu recommended when using a custom LOD. 
+
+### Triangles per Cubic Meter
+
+When using the Custom [Level of Detail](#level-of-detail), specifies the requested value for the triangle density for the spatial mesh.
+
+## Display Settings
+
+![Mesh Observer Display Settings](../../External/ReadMeImages/MeshObserverDisplaySettings.png)
+
+*Mesh Observer Display Settings*
+
+### Display Option
+
+Specifies how spatial meshes are to be displayed by the observer. Supported values are None, Visible and Occlusion. Setting Visible or Occlusion instructs the observer to select the appropriate material. Specifying None causes the observer to not render the mesh.
+
+> Note: Setting Display Option to None does _not_ stop the observer from running. If you wish to stop the observer, applications will need to call one of the following IMixedRealitySpatialAwarenessSystem methods:
+> - SuspendObserver<T>(string name)
+> - SuspendObservers()
+> - SuspendObservers<T>()
+
+### Visible Material
+
+Indicates the material to be used when visualizing the spatial mesh.
+
+### Occlusion Material
+
+Indicates the material to be used to cause the spatial mesh to occlude holograms.
+
+## See Also
+
+- [IMixedRealitySpatialAwarenessObserver API documentation](xref:Microsoft.MixedReality.Toolkit.SpatialAwareness.IMixedRealitySpatialAwarenessObserver)
+- [IMixedRealitySpatialAwarenessMeshObserver API documentation](xref:Microsoft.MixedReality.Toolkit.SpatialAwareness.IMixedRealitySpatialAwarenessMeshObserver)
+- [BaseSpatialObserver API documentation](xref:Microsoft.MixedReality.Toolkit.SpatialAwareness.BaseSpatialObserver)
+- [Spatial Awareness System](SpatialAwarenessSystemGettingStarted.md)
+- [Using Spatial Awareness in an Application](../TODO.md)

Documentation/SpatialAwareness/SpatialAwarenessGettingStarted.md

@@ -0,0 +1,89 @@
+# Spatial Awareness
+
+The Spatial Awareness system provides real-world environmental awareness in mixed reality 
+applications. When introduced on Microsoft HoloLens, spatial awareness provided a collection 
+of meshes, representing the geometry of the environment, which allowed for compelling interactions 
+between holograms and the real-world.
+
+## Getting Started
+
+Adding support for spatial awareness requires two key components of the Mixed Reality Toolkit: the 
+spatial awareness system and a supported platform provider.
+
+1. [Enable](enable-spatial-awareness) the spatial awareness system
+2. [Register](register-observers) and [configure](configure-observers) one or more spatial observers
+3. [Build and deploy](build-and-deploy) to a platform that supports spatial awareness
+
+### Enable Spatial Awareness
+
+The spatial awareness system is managed by the MixedRealityToolkit object (or another 
+[service registrar](xref:Microsoft.MixedReality.Toolkit.IMixedRealityServiceRegistrar) component). 
+
+> The following steps presume use of the MixedRealityToolkit object. Steps required for other service registrars may be different.
+
+1. Select the MixedRealityToolkit object in the scene hierarchy.
+
+![MRTK Configured Scene Hierarchy](../../External/ReadMeImages/MRTK_ConfiguredHierarchy.png)
+
+2. Navigate the Inspector panel to the Spatial Awareness System section and check Enable
+
+![Enable Spatial Awareness](../../External/ReadMeImages/SpatialAwareness/MRTKConfig_SpatialAwareness.png)
+
+3. Select the Spatial Awareness System implementation
+
+![Select the Spatial Awareness System Implementation](../../External/ReadMeImages/SpatialAwareness/SpatialAwarenessSelectSystemType.png)
+
+> Users of the default profile (DefaultMixedRealityToolkitConfigurationProfile) will have the spatial awareness system pre-configured to use the MixedRealitySpatialAwarenessSystem from the Mixed Reality 
+Toolkit Spatial Awareness Service package.
+
+### Register observers
+
+Before the spatial awareness system can provide applications with data about the real-world, at least 
+one spatial observer must be registered. Spatial observers are generally platform specific components 
+that may vary in the type(s) of data (ex: meshes) provided.
+
+1. Open or expand the Spatial Awareness System profile
+
+![Spatial Awareness System Profile](../../External/ReadMeImages/SpatialAwareness/SpatialAwarenessProfile.png)
+
+2. Click "Add Spatial Observer"
+3. Select the Spatial Observer implementation
+
+![Select the Spatial Observer Implementation](../../External/ReadMeImages/SpatialAwareness/SpatialAwarenessSelectObserver.png)
+
+> Users of the default profile (DefaultMixedRealitSpatialAwarenessSystemProfile) will have the spatial awareness system pre-configured to use the WindowsMixedRealitySpatialMeshObserver from the Mixed Reality 
+Toolkit Windows Mixed Reality Provider package.
+
+#### Configure observers
+
+Once the spatial observer(s) have been registered with the system, they can be configured to provide 
+the desired data.
+
+> When configuring a spatial observer, many implementations will auto-populate the observer's configuration profile with common default values.
+
+1. Open or expand the Spatial Observer profile
+
+![Spatial Mesh Observer Profile](../../External/ReadMeImages/SpatialAwareness/SpatialAwarenessMeshObserverProfile.png)
+
+2. Configure the desired options
+
+The illustration in the previous step shows the configuration profile for a spatial mesh observer. 
+Please see [Configuring the Spatial Awareness Mesh Observer](ConfiguringSpatialAwarenessMeshObserver.md) for more information pertaining to the specific 
+settings available to mesh observers. Other observers may have similar settings.
+
+### Build and Deploy
+
+Once the spatial awareness system is configured with the desired observer(s), the project can be built 
+and deployed to the target platform.
+
+> Some platforms, including Microsoft HoloLens, provide support for remote execution from within Unity. 
+This feature enables rapid development and testing without requring the build and deploy step. Be sure to do final acceptance testing using an built and deployed version of the application, running 
+
+
+## See Also
+
+- [Spatial Awareness API documentation](xref:Microsoft.MixedReality.Toolkit.SpatialAwareness)
+- [Configuring the Spatial Awareness Mesh Observer](ConfiguringSpatialAwarenessMeshObserver.md)
+- [Using Spatial Awareness in an Application](../TODO.md)
+
+

Documentation/toc.yml

@@ -56,8 +56,11 @@
         href: TODO.md
     - name: UX Building Blocks
       href: TODO.md
-    - name: Spatial Mapping
-      href: TODO.md
+    - name: Spatial Awareness
+      href: SpatialAwareness/SpatialAwarenessGettingStarted.md
+      items:
+      - name: Configuring the Spatial Awareness Mesh Observer
+        href: SpatialAwareness/ConfiguringSpatialAwarenessMeshObserver.md
     - name: In-Editor Input Simulation
       href: TODO.md
     - name: Performance Diagnostic Tool