Spatial Mapping Collider

The Spatial Mapping Collider component allows holographicThe former name for Windows Mixed Reality. More info
See in Glossary content to interact with real-world physical Surfaces. This component handles creating, updating, and destroying the Surface GameObjectThe fundamental object in Unity scenes, which can represent characters, props, scenery, cameras, waypoints, and more. A GameObject’s functionality is defined by the Components attached to it. More info
See in Glossary CollidersAn invisible shape that is used to handle physical collisions for an object. A collider doesn’t need to be exactly the same shape as the object’s mesh - a rough approximation is often more efficient and indistinguishable in gameplay. More info
See in Glossary in the SceneA Scene contains the environments and menus of your game. Think of each unique Scene file as a unique level. In each Scene, you place your environments, obstacles, and decorations, essentially designing and building your game in pieces. More info
See in Glossary.

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 FilterA mesh component that takes a mesh from your assets and passes it to the Mesh Renderer for rendering on the screen. More info
See in Glossary and Mesh ColliderA free-form collider component which accepts a mesh reference to define its collision surface shape. More info
See in Glossary component. A Surface with a MeshThe main graphics primitive of Unity. Meshes make up a large part of your 3D worlds. Unity supports triangulated or Quadrangulated polygon meshes. Nurbs, Nurms, Subdiv surfaces must be converted to polygons. More info
See in Glossary 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 RenderersA mesh component that takes the geometry from the Mesh Filter and renders it at the position defined by the object’s Transform component. More info
See in Glossary.

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 collisionA collision occurs when the physics engine detects that the colliders of two GameObjects make contact or overlap, when at least one has a rigidbody component and is in motion. More info
See in Glossary 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