Spatial Mapping common troubleshooting issues

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.

Collision data generation takes a long time

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.

Best practice solution:

• 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 triangle densities generate large amounts of geometry

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.

Best practice solution:

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).

Queuing too many Mesh requests results in unnecessary work

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.

Best practice solution:

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.

Overlapping SurfaceObserver volumes create duplicate RequestMeshAsync calls

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.

Updating a SurfaceObserver generates no onSurfaceChanged callbacks

This is a common issue, typically caused by issues in the set-up process.

Best practice solution:

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