v147 · Web APIs · Plane Types

Plane Types

The XRPlane interface — orientation values, polygon vertices, spatial pose, and how to use detected planes as placement anchors for virtual objects in AR.

plane orientations

orientation: "horizontal"

Floors, tables, shelves. Normal vector points roughly upward. Used for surface placement of virtual objects.

orientation: "vertical"

Walls, windows, doors. Normal vector points roughly horizontally. Used for wall-mounted overlays.

XRPlane properties

Property	Type	Description
`plane.orientation`	`"horizontal" \| "vertical"`	Whether the plane is roughly horizontal or vertical in world space
`plane.polygon`	`DOMPointReadOnly[]`	Convex polygon vertices in the plane's local space. In metres. XZ-plane when horizontal, XY-plane when vertical.
`plane.planeSpace`	`XRSpace`	The plane's local coordinate space. Pass to `frame.getPose()` to get the plane's world pose.
`plane.lastChangedTime`	`number`	The timestamp (in milliseconds) of the last update to this plane's shape or pose.

placing an object on a plane

function placeOnPlane(frame, referenceSpace, plane) {
  // Get the plane's world pose
  const pose = frame.getPose(plane.planeSpace, referenceSpace);
  if (!pose) return;

  // Plane's world-space transform matrix (column-major, Float32Array)
  const matrix = pose.transform.matrix;

  // The plane's polygon gives the surface boundary
  // in the plane's local coordinate system
  const bounds = plane.polygon;

  // Find the centre of the polygon
  let cx = 0, cz = 0;
  for (const v of bounds) { cx += v.x; cz += v.z; }
  cx /= bounds.length;
  cz /= bounds.length;

  // Place a virtual object at the plane's centre
  const objectMatrix = mat4.create();
  mat4.multiply(objectMatrix, matrix, mat4.fromTranslation([cx, 0, cz]));
  renderObject(objectMatrix);
}

scenario focus

Select a scenario to focus its rendered example and summary.

implementation reference

Need the exact API surface, compatibility boundaries, errors, lifecycle, and source links? Read the matching gendn reference ↗