uid: arfoundation-plane-manager

AR plane manager

The plane manager is a type of trackable manager.

The plane manager creates GameObjects for each detected plane in the environment. A plane is a flat surface represented by a pose, dimensions, and boundary points. The boundary points are convex.

Examples of features in the environment that can be detected as planes are horizontal tables, floors, countertops, and vertical walls.

You can specify a detection mode, which can be horizontal, vertical, or both. Some platforms require extra work to perform vertical plane detection, so if you only need horizontal planes, you should disable vertical plane detection.

Responding to planes

Planes can be added, updated, and removed. Once per frame, the AR plane manager can invoke the planesChanged event with Lists of planes that have been added, updated, and removed since the last frame.

When a plane is detected, the AR Plane Manager instantiates the Plane Prefab to represent the plane. The Plane Prefab can stay null, but the plane manager ensures the instantiated GameObject has an ARPlane component on it. The ARPlane component only contains data about the detected plane.

When a plane is updated, it's likely that its boundary vertices have also changed. To respond to this event, subscribe to the plane's ARPlane.boundaryChanged event. This event only fires if at least one boundary vertex has changed by at least the Vertex Changed Threshold, or if the total number of vertices changes.

Visualizing planes

To visualize planes, you need to create a prefab or GameObject which includes a component that subscribes to ARPlane's boundaryChanged event. ARFoundation provides an ARPlaneMeshVisualizer. This component generates a Mesh from the boundary vertices and assigns it to a MeshCollider, MeshFilter, and LineRenderer, if present.

To create a new GameObject which you can then use to create your prefab, right-click in your Scene view and select GameObject > XR > AR Default Plane from the context menu that appears.

After you create the GameObject, assign it to the ARPlaneManager's Plane Prefab field. You can use it directly or create a prefab by dragging the GameObject into your Assets folder. The default plane looks like this:

It is recommended to save the AR Default Plane as a prefab first, delete the AR Default Plane GameObject, and then use that in the prefab field as leaving the plane in your scene will leave a zero scale plane artifact in the scene.

The AR Foundation package includes these components for ease of use, but you can create your own visualizers (or other logic) as you see fit.

Disabling planes

As long as the AR Plane Manager is enabled, it will continue to create, update, and remove planes. To stop rendering existing planes, deactivate their GameObjects like this:

foreach (var plane in planeManager.trackables)
{
    plane.gameObject.SetActive(false);
}

You shouldn't Destroy an ARPlane while the plane manager is still managing it.