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

Setting	Description
Enable Collisions	Check this box to enable Surface Mesh Colliders. This means that holographic content can collide with Surfaces.
Mesh Layer	Set the Layer property on all the Surface Mesh Colliders. Note that you need to set Layers for raycasts. When performing a raycast, you must indicate which Layers you want the ray intersection to test against. See Camera Raycast documentation for more information, and see Example script: SpatialSurface raycast, below. By default, Unity assigns all GameObjects to the Default Layer. However, it is good practice to assign your GameObjects to a specific Layer. We recommend that you create a new layer specifically for Spatial Mapping Surfaces and assign this Layer to the Mesh Layer property.
Physic Material	Specify which Physic Material to assign to each Surface GameObject’s Mesh Collider. The default is None (Physic Material). A Physic Material specifies how other Rigidbody components should interact with it. For example, you might want to create a Surface that simulates ice, and therefore applies less friction to a GameObject moving on it. The Spatial Mapping Collider component applies its Physic Material to all of the Mesh Colliders on its Surface GameObjects. See documentation on Physic Material for more information

General Settings

SpatialMapping General Settings

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

Setting	Description
Surface Parent	Select the Surface Parent GameObject that you want Surface GameObjects generated by Spatial Mapping components to inherit from. Leave this as None(Game Object), to automatically generate a Surface Parent GameObject.
Freeze Updates	Check this box to stop the component querying the system for Surface changes. Note: Each Spatial Mapping component periodically queries the Spatial Mapping data for Surface changes in physical space. Querying and baking Surfaces costs memory, performance, and power. For environments that you expect to be mostly static, we recommend that you allow users to look around the environment for a duration of time without updating the Surface GameObjects. If you expect the environment in your simulation to be mostly static and unchanging (like a board game), you can scan as much Surface data as you need when your application starts, and then set the Freeze Updates property to true to prevent further updates. This increases performance slightly and consumes less power.
Time Between Updates	The time in decimal format seconds (for example, 3.7 or 4.6) between queries for Surface changes in physical space. The default is 2.5 seconds. Note that the more regular the queries, the higher the cost in memory, performance, and power.
Removal Update Count	The number of updates before a Surface GameObject is removed by the system. You can think of an update as a frame in this case. The default is 10 updates. Note: The removal update countdown begins when Spatial Mapping notifies the component that a Surface GameObject is no longer in the SurfaceObserver’s bounding volume (in that it is no longer within the defined area that the system reports on). This setting allows you to specify the number of updates that should happen after this event before Spatial Mapping removes the Surface GameObject.
Level of Detail	The quality of the Mesh that the component generates (Low, Medium, or High). The default quality is Medium. The higher the quality, the more refined and accurate the generated Collider or rendered Mesh. Using lower quality settings results in a lower cost in performance and power consumption. See the image below this table for an example of the three Level Of Detail modes.
Bounding Volume Type	The component’s bounding volume area shape, in which the application receives Spatial Mapping data. This can be either a Sphere or Axis Aligned Box. The default is Axis Aligned Box. Note: The bounding volume is the defined area about which the system reports physical Surface changes and limits the extents of the Spatial Mapping Mesh.
Size In Meters	The size of the bounding volume used by component (in meters). Configure Sphere by radius; the default radius is 2 meters. Configure Axis Aligned Box by its extents; the default is a Vector3 (4,4,4). Note: The observer’s bounding volume is the defined area about which Spatial Mapping reports physical Surface changes.

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

• Spatial Mapping for Hololens documentation updated in 2017.3