Spatial Mapping Collider

The Spatial Mapping Collider component allows holographic content to interact with real-world physical Surfaces. This component handles creating, updating, and destroying the Surface GameObject Colliders in the Scene.

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 by Unity. Every time a Surface is baked by the system, a new GameObject is then generated by Unity, containing a Mesh Filter and Mesh Collider component. A Surface with a Mesh Collider allows raycasts to collide with it as with any other mesh in Unity. See Camera Raycast documentation for more information.

Note: This component only updates the Mesh Collider components of Surface GameObjects, and not the Mesh Renderers.

Note: Spatial Mapping Colliders update with less latency than Spatial Mapping Mesh Renderers. This means that Colliders update faster than Renderers.

Collider Settings

General Settings

The settings below are common to both Spatial Mapping Renderer and Spatial Mapping Collider components.

Level of Detail

Both Spatial Mapping components allow you to specify one of three Levels of Detail for each component’s generated spatial meshes (Low, Medium, or High) as depicted in the image below.

When possible, set the Level of Detail setting for Spatial Mapping Colliders to Low. This increases performance and reduces power usage when calculating collision intersections. However, setting Level of Detail to Low can negatively affect the visual effect of your application,

Using the Spatial Mapping Collider

Surface GameObjects

When you add a Spatial Mapping Collider component to a GameObject in your Scene, it generates its own separate set of Surface GameObjects during runtime. These appear in your Scene parented to a Surface Parent GameObject.

The Surface GameObjects generated by the Spatial Mapping Collider contain the following components:

• Mesh Filter

• World Anchor

• Mesh Collider

If you add multiple Spatial Mapping Collider components to your Scene, each individual component generates its own set of Surface GameObjects. For example, if two GameObjects in your Scene contain a Spatial Mapping Collider then your Scene contains two sets of Surface GameObjects; one generated by each component at runtime. This is important to keep in mind for optimization purposes. s Note: When first generated by the Spatial Mapping system, all Surface GameObjects are assigned to the Default Layer. However, it is good practice to assign your GameObjects to a specific Layer, because raycasting is an expensive calculation to perform. 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 a 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. You can change the layer assigned to all Surface GameObjects generated by a specific Spatial Mapping Collider component by changing the Collider Settings > Mesh Layer property.

Example script: SpatialSurface raycast on a tap gesture event

The following example demonstrates how to raycast against GameObjects on the SpatialSurface Layer and use a GestureRecognizer to initiate this raycast upon detection of a tap gesture event.

using UnityEngine;
using System.Collections; 

//Required for Gesture Recognizer
using UnityEngine.XR.WSA.Input;


public class CustomLayerCollision : MonoBehaviour
{

    //use this to capture gesture events

    private GestureRecognizer GR_recognizer;

    void Start()
    {
        //Initialise the GestureRecognizer

        GR_recognizer = new GestureRecognizer();

        //Initiate gesture capture

        GR_recognizer.StartCapturingGestures();

        //Tell the GestureRecognizer which events to listen for

        GR_recognizer.SetRecognizableGestures(GestureSettings.Tap);

        //Subscribe the Tapped event to the DetectCollisions method

        //This makes this method be called any time the GestureRecognizer detects a tap event

        GR_recognizer.Tapped += DetectCollisions;

        //When the user initiates a tap gesture, the DetectCollisions   

        //method is called by the Tapped event delegate to do a collision test using Raycasting

        //See [GestureRecognizer API reference](../ScriptReference/XR.WSA.Input.GestureRecognizer.html) for more details
    }
    //Method to fire a raycast on a Tap event
    public void DetectCollisions(TappedEventArgs tapEvent)
    {
        // Raycast against all GameObjects that are on either the
        // spatial Surface or UI layers.

        int layerMask = 1 << LayerMask.NameToLayer("SpatialSurface");

        //construct a Ray using the position and forward direction of the User’s head
        Ray GazeRay = new Ray(tapEvent.headPose.position, tapEvent.headPose.forward);

        //Raycast using constructed Ray from Gaze and store collisions in array hits

        RaycastHit[] hits = Physics.RaycastAll(GazeRay, 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.");
        }
    }
}

See documentation on Layers and Raycasting from Camera for more information.

• 2018–05–01 Page published with editorial review

• Spatial Mapping for Hololens documentation updated in 2017.3