Spatial Mapping components

The Unity Editor has low-level Script Ref API for gathering information about surfaces in your project environment. This low-level Script Ref API gives you maximum control over when to query the device for surface changes, and when to create or update the corresponding surface game objects. The Spatial Mapping components allow you to quickly get up and running with mixed reality, without directly using the low-level Script Ref API.

Spatial Mapping components

There are two Spatial Mapping components: the Spatial Mapping Renderer and the Spatial Mapping Collider. Go to Component > Add… (or click on Add Component in the Inspector window) to bring up the Add Component menu. The spatial mapping components are under the AR category in the Add Component menu.

You can use the components together or independently. Each Spatial Mapping component uses its own surface observer to understand changes in the physical world. Depending on how the component is configured, each Spatial Mapping component periodically queries the system to understand what changes have occurred in physical space. When the system notifies the component of the relevant changes, the component prioritizes the baking of the various changed surfaces. The baking process involves generating a Mesh Filter with a Mesh that corresponds to the physical surface. The Spatial Mapping Renderer and Spatial Mapping Collider components use this Mesh Filter in their own specific ways.

Spatial Mapping Renderer (Script)

The Spatial Mapping Renderer component gives a visual representation of Spatial Mapping surfaces. This is useful for visually debugging surfaces and adding visual effects to the environment.

The Spatial Mapping Renderer component periodically asks the system for changes in physical space. Each time the component is notified of these changes, it bakes the returned surface data into GameObjects. These GameObjects contain a Mesh Filter and a Mesh Renderer. The Renderer component manages the lifetime of the surface GameObjects. This means that the Spatial Mapping Renderer component handles creating, updating, and destroying the surface GameObject.

The component provides an easy way to change the material on all the generated surfaces dynamically. It ships with two material types:

• An Occlusion Material that appears transparent but conceals holograms. This is a useful material to use if, for example, you want a real-world desk to conceal an in-game holographic object placed underneath it.

• A wireframe Shader that applies to all the component’s surfaces. The colors of the wireframe represent distances. The following are the distance-to-color mappings.

  • 0 to 1 meters = Black

  • 1 to 2 meters = Red

  • 2 to 3 meters = Green

  • 3 to 4 meters = Blue

  • 4 to 5 meters = Yellow

  • 5 to 6 meters = Cyan

  • 6 to 7 meters = Magenta

  • 7 to 8 meters = Maroon

  • 8 to 9 meters = Teal

  • 9 to 10 meters = Orange

  • 10 meters or greater = White

Render Settings

For information on the General Settings see General Settings, below.

Notes:

• All surface GameObjects take their material from the Custom Render Setting. If you change the Custom Render Setting, all surface GameObjects’ render materials change to those of the Custom Render Setting. This reduces the number of draw calls, which in turn improves the rendering performance. Using a shared material also reduces the amount of memory that rendering uses.

• When you assign a new material to the Custom Material setting, it does not automatically change the surface material of your surface GameObjects. You must also set Custom Render Setting to Custom Material or Occlusion Material to apply the new material to all surfaces.

• If the Occlusion Material or Custom Material properties in Custom Render Setting are not assigned at runtime, they are destroyed with the Renderer component. However, any Occlusion Material or Custom Material assigned at runtime are not destroyed with the component, so you need to destroy them individually.

Example script: Change surface material at runtime

The following script example demonstrates how to to change the material applied to all surface GameObjects dynamically at runtime.

SpatialMappingRenderer renderer = spatialMappingGameObject.AddComponent<SpatialMappingRenderer>();
renderer.customMaterial = new Material(Shader.Find("VR/SpatialMapping/Wireframe"));
renderer.currentRenderSetting = SpatialMappingRenderer.RenderSetting.CustomMaterial;

Spatial Mapping Collider (Script)

The Spatial Mapping Collider component allows holographic content to interact with physical surfaces. It handles creating, updating, and destroying the surface GameObjects.

The component periodically queries the system for surface changes in the physical world. When the system reports surface changes, the Spatial Mapping Collider component prioritizes when each reported surface is baked. When a surface is baked, a new GameObject is created that has a Mesh Filter and Mesh Collider component. Once the surface has a Mesh Collider, you can cast rays against the surface and collide with it.

Collider Settings

For information on the General Settings see General Settings, below.

Example script: SpatialSurface raycast

The following example demonstrates how to raycast against GameObjects on the SpatialSurface Layer.

using UnityEngine;
using System.Collections; 

public class CustomLayerCollision : MonoBehaviour
{
    // Update is called once per frame.
    void Update()
    {
        // When the user presses the left mouse button,
        // Do a collision test.  You could fire the
        // DetectCollisions based on a gesture event.*

        if(Input.GetMouseButtonDown(0))
        {
            DetectCollisions();
        }
    } 

    void DetectCollisions()
    {
        // Raycast against all game objects that are on either the
        // spatial surface or UI layers.
        int layerMask = 1 << LayerMask.NameToLayer("SpatialSurface");
        // We use ScreenPointToRay to create a ray whose origin is the
        // main camera's position and direction is from the position of the main
        // camera to the position of where the mouse position would be in world space.
        RaycastHit[] hits = Physics.RaycastAll(Camera.main.ScreenPointToRay(Input.mousePosition), float.MaxValue, layerMask);

        if(hits.Length > 0)
        {
            foreach(RaycastHit hit in hits)
            {
                Debug.Log(string.Format("Hit Object **\"**{0}**\"** at position **\"**{1}**\"**", hit.collider.gameObject, hit.point));
            }
        }
        else
        {
            Debug.Log("Nothing was hit.");
        }
    }
}

Settings

General Settings

General Settings function in the same way for the Spatial Mapping Renderer (Script) and Spatial Mapping Collider (Script) components.

Level Of Detail

Performance optimization

• Keep in mind that each Spatial Mapping component is independent of other Spatial Mapping components. This means that each component maintains its own list of surfaces, even if multiple components see the same surface. Try to limit how many Spatial Mapping components you use, in order to optimize performance.

• If you expect the environment in your simulation to be fairly static and unchanging (like a board game), you can scan as much surface data as needed upfront and then set the Freeze Updates property to false. This increases performance slightly and consumes less power.

• There is a small cost in performance for moving a Spatial Mapping component. Try to avoid moving a GameObject that has a Spatial Mapping component.

• In Collider Settings > Level of Detail, use the Low setting. This increases performance and reduces power usage when calculating collision intersections.

• Spatial Mapping Mesh Colliders have less latency in updates than Spatial Mapping Mesh Renderers. This means the Colliders update faster than the Renderers.

• In Collider Settings > Mesh Layer, by default, all game objects are assigned to the Default Layer. However, it is good practise to assign your GameObjects to a specific Layer: Raycasting is an expensive calculation to perform, in that it can slow performance. By using Layers, you can filter which GameObjects you are doing your raycast calculations against, and so optimise performance. If you don’t have a lot of complicated Meshes on your Default Layer, then doing the raycast test for collision won’t have a large performance cost. However, it is best to organize your GameObjects into Layers to reduce the complexity of raycast tests when doing collisions.

See the Layers page and Raycast page for more information.