Spatial Mapping generates a large amount of data. This has an impact on your application’s speed and performance. This section discusses common issues that can arise from using Spatial Mapping, and guidance on how to avoid those issues.
Generating 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 data requires more CPU processing time than any other aspect of Spatial Mapping. Ensuring that collision data is only requested when necessary optimizes usage of CPU resources and increase battery life.
Only request collision data where necessary. Avoiding collision data requests when they are not necessary decreases the latency for other Spatial Mapping requests, and prolongs battery life.
Use a Surface’s update time and bounding boxes to prioritize data requests, and only request Surfaces that are high priority.
High values of trianglesPerCubicMeter, set through the SurfaceData struct when requesting Surface data using the RequestMeshAsync method, generate a very large amount of geometry in your 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. This is especially true in spaces containing many objects (like a cluttered office). Large amounts of geometry in your Scene increase data generation latency and the memory usage of your application. Higher 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 densities in your Scene can also slow down run-time systems such as renderingThe process of drawing graphics to the screen (or to a render texture). By default, the main camera in Unity renders its view to the screen. More info
See in Glossary and physics, which can affect performance.
Use the minimum resolution of Spatial Mapping data that your application requires. To do this, you need to test your application and the accuracy of the generated Spatial Mapping mesh, but the result is a balance of accuracy and performance that ultimately offers a much more positive user experience. Lower resolutions of generated Meshes result in less CPU time being spent by your application when the Mesh updates. This reduces the power consumption of your device, increases battery life, and also reduces latency in retrieving Mesh data. Lower resolution Meshes also use less memory and have a less impact on run-time systems such as rendering and physics (which expects low complexity geometry).
SurfaceObservers report all added, updated, and removed Surfaces within their volume when you call the SurfaceObserver.Update method.
This adds a list of all changed Surfaces to the work queue and can result in unused Surfaces remaining in the work queue after Spatial Mapping has removed them. These Surfaces still take up CPU time when moving through the system, but do not generate any Mesh data. This increases the latency of any waiting requests.
Limit the number of Surfaces in the work queue where possible. Querying Meshes is an expensive operation with high latency, so keeping only a single RequestMeshAsync request in use at any given time minimizes any slowdown that these operations cause. Applications can use a Surface’s reported update time and bounds to prioritize RequestMeshAsync
calls.
It is also important to prioritize Surface data requests so that your application receives the most important data first. Examples of common ways to prioritize include:
Prioritizing new Surfaces above updating existing ones.
Prioritizing Surfaces that are closer to the user over those further away.
SurfaceObservers report changes for all Surfaces that overlap their volume. A Surface can overlap multiple SurfaceObserver
volumes if they are close together. This makes it possible for application code to request the same Surfaces multiple times, which can lead to performance issues.
Best practice solution:
Use a single work submission queue for requests from SurfaceObserver
.
For many applications, a single SurfaceObserver
is often all you need.
Using a single SurfaceObserver
can help you reduce the complexity of developing your application. However, there are several advanced uses for Spatial MappingThe process of mapping real-world surfaces into the virtual world. More info
See in Glossary that require multiple SurfaceObserver
members. In these cases, you should use a single work queue for all SurfaceObserver
members in your Scene in order to uniquely prioritize Mesh requests.
This is a common issue, typically caused by issues in the set-up process.
Set a valid volume on your SurfaceObserver
, using a method such as SetVolumeAsAxisAlignedBox.
You should also make sure that you enable the Spatial Perception capability in Publishing Settings (menu: File > Build Settings > Player Settings > Publishing Settings).
For more information relating to Capability and Publishing Settings for WMR, see Unity’s Windows Mixed Reality quick starter guide.
2018–05–01 Page published with editorial review
Spatial Mapping for Hololens documentation updated in 2017.3
Did you find this page useful? Please give it a rating:
Thanks for rating this page!
What kind of problem would you like to report?
Is something described here not working as you expect it to? It might be a Known Issue. Please check with the Issue Tracker at issuetracker.unity3d.com.
Thanks for letting us know! This page has been marked for review based on your feedback.
If you have time, you can provide more information to help us fix the problem faster.
Provide more information
You've told us this page needs code samples. If you'd like to help us further, you could provide a code sample, or tell us about what kind of code sample you'd like to see:
You've told us there are code samples on this page which don't work. If you know how to fix it, or have something better we could use instead, please let us know:
You've told us there is information missing from this page. Please tell us more about what's missing:
You've told us there is incorrect information on this page. If you know what we should change to make it correct, please tell us:
You've told us this page has unclear or confusing information. Please tell us more about what you found unclear or confusing, or let us know how we could make it clearer:
You've told us there is a spelling or grammar error on this page. Please tell us what's wrong:
You've told us this page has a problem. Please tell us more about what's wrong:
Thanks for helping to make the Unity documentation better!