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!
When you visit any website, it may store or retrieve information on your browser, mostly in the form of cookies. This information might be about you, your preferences or your device and is mostly used to make the site work as you expect it to. The information does not usually directly identify you, but it can give you a more personalized web experience. Because we respect your right to privacy, you can choose not to allow some types of cookies. Click on the different category headings to find out more and change our default settings. However, blocking some types of cookies may impact your experience of the site and the services we are able to offer.
More information
These cookies enable the website to provide enhanced functionality and personalisation. They may be set by us or by third party providers whose services we have added to our pages. If you do not allow these cookies then some or all of these services may not function properly.
These cookies allow us to count visits and traffic sources so we can measure and improve the performance of our site. They help us to know which pages are the most and least popular and see how visitors move around the site. All information these cookies collect is aggregated and therefore anonymous. If you do not allow these cookies we will not know when you have visited our site, and will not be able to monitor its performance.
These cookies may be set through our site by our advertising partners. They may be used by those companies to build a profile of your interests and show you relevant adverts on other sites. They do not store directly personal information, but are based on uniquely identifying your browser and internet device. If you do not allow these cookies, you will experience less targeted advertising. Some 3rd party video providers do not allow video views without targeting cookies. If you are experiencing difficulty viewing a video, you will need to set your cookie preferences for targeting to yes if you wish to view videos from these providers. Unity does not control this.
These cookies are necessary for the website to function and cannot be switched off in our systems. They are usually only set in response to actions made by you which amount to a request for services, such as setting your privacy preferences, logging in or filling in forms. You can set your browser to block or alert you about these cookies, but some parts of the site will not then work. These cookies do not store any personally identifiable information.