Legacy Documentation: Version 5.6 (Go to current version)
Spatial Mapping
Spatial Mapping basic low level API usage
Other Versions

Spatial mapping concepts

Spatial mapping is the process of mapping real-world objects into the virtual world. This is a great way to provide better real-world interaction to your Windows Holographic application.


The HoloLens device constantly scans its surroundings and refines its understanding of the world based on new sensor data. Updates occur frequently, so that the device can pick up environmental changes such as people moving through the room or doors opening and closing. The world mapping data set is saved on the device and persists across multiple applications and device restarts.

Transparent, black, and reflective surfaces are largely invisible to the device. If the device can’t detect something, it usually leaves an empty patch within the spatial mapping data. The same is true for parts of the world that it hasn’t been in or can’t see. For example, no data exists for rooms that it hasn’t observed.

Data organization

The device’s world mapping is chopped up into regularly-sized chunks called Surfaces. Surfaces are oriented in the world in a way convenient to the system. There’s no guarantee that Surfaces are arranged in any particular orientation, and they may not intersect a given world space, such as a room, in a good way. Data generated for a Surface overlaps neighboring Surfaces slightly.

Note that there is no semantic meaning or interpretation associated with any of the Surface data. The system does not know and cannot report on what’s in a Surface.

For example: the system cannot tell you that the blob on the desk is a mug, or what the vaguely chair-like object in the middle of the room is. It only reports on the configuration of the geometry in that area based on its understanding of the world, which is gleaned from its sensory input.


You access spatial mapping data through a SurfaceObserver. This is a volume describing a view into the system’s spatial mapping world. A SurfaceObserver can report on the set of Surfaces it intersects with that have been added, changed, or removed. This is the main API point for working with spatial mapping data.

Points to note

You need to be aware of the following issues. They are due to how the system works.

  1. The amount of spatial mapping data can be very large, which poses scalability challenges.
  2. Objects or people moving quickly within the room can make the data very irregular.
  3. Holes in the data can sometimes cause issues, particularly if you need continuous data for design reasons.

See Microsoft’s documentation on Spatial mapping to learn more about spatial mapping concepts.

Spatial Mapping
Spatial Mapping basic low level API usage