ArPlane

Describes the current best knowledge of a real-world planar surface.

Summary

Enumerations

ArPlaneType{
  AR_PLANE_HORIZONTAL_UPWARD_FACING = 0,
  AR_PLANE_HORIZONTAL_DOWNWARD_FACING = 1,
  AR_PLANE_VERTICAL = 2
}
enum
Simple summary of the normal vector of a plane, for filtering purposes.

Typedefs

ArPlane typedef
struct ArPlane_
A detected planar surface (reference type, long-lived).

Functions

ArPlane_acquireSubsumedBy(const ArSession *session, const ArPlane *plane, ArPlane **out_subsumed_by)
void
Acquires a reference to the plane subsuming this plane.
ArPlane_getCenterPose(const ArSession *session, const ArPlane *plane, ArPose *out_pose)
void
Returns the pose of the center position of the plane's bounding rectangle.
ArPlane_getExtentX(const ArSession *session, const ArPlane *plane, float *out_extent_x)
void
Retrieves the length of this plane's bounding rectangle measured along the local X-axis of the coordinate space defined by the output of ArPlane_getCenterPose.
ArPlane_getExtentZ(const ArSession *session, const ArPlane *plane, float *out_extent_z)
void
Retrieves the length of this plane's bounding rectangle measured along the local Z-axis of the coordinate space defined by the output of ArPlane_getCenterPose.
ArPlane_getPolygon(const ArSession *session, const ArPlane *plane, float *out_polygon_xz)
void
Returns the 2D vertices of a convex polygon approximating the detected plane, in the form [x1, z1, x2, z2, ...].
ArPlane_getPolygonSize(const ArSession *session, const ArPlane *plane, int32_t *out_polygon_size)
void
Retrieves the number of elements (not vertices) in the boundary polygon.
ArPlane_getType(const ArSession *session, const ArPlane *plane, ArPlaneType *out_plane_type)
void
Retrieves the type (orientation) of the plane.
ArPlane_isPoseInExtents(const ArSession *session, const ArPlane *plane, const ArPose *pose, int32_t *out_pose_in_extents)
void
Sets *out_pose_in_extents to non-zero if the given pose (usually obtained from an ArHitResult) is in the plane's rectangular extents.
ArPlane_isPoseInPolygon(const ArSession *session, const ArPlane *plane, const ArPose *pose, int32_t *out_pose_in_polygon)
void
Sets *out_pose_in_extents to non-zero if the given pose (usually obtained from an ArHitResult) is in the plane's polygon.

Enumerations

ArPlaneType

 ArPlaneType

Simple summary of the normal vector of a plane, for filtering purposes.

Properties
AR_PLANE_HORIZONTAL_DOWNWARD_FACING

A horizontal plane facing downward (for example a ceiling).

AR_PLANE_HORIZONTAL_UPWARD_FACING

A horizontal plane facing upward (for example a floor or tabletop).

AR_PLANE_VERTICAL

A vertical plane (for example a wall).

Typedefs

ArPlane

struct ArPlane_ ArPlane

A detected planar surface (reference type, long-lived).

Functions

ArPlane_acquireSubsumedBy

void ArPlane_acquireSubsumedBy(
  const ArSession *session,
  const ArPlane *plane,
  ArPlane **out_subsumed_by
)

Acquires a reference to the plane subsuming this plane.

Two or more planes may be automatically merged into a single parent plane, resulting in this function acquiring the parent plane when called with each child plane. A subsumed plane becomes identical to the parent plane, and will continue behaving as if it were independently tracked, for example being included in the output of ArFrame_getUpdatedTrackables.

In cases where a subsuming plane is itself subsumed, this function will always return the topmost non-subsumed plane.

Note: this function will set *out_subsumed_by to NULL if the plane is not subsumed.

ArPlane_getCenterPose

void ArPlane_getCenterPose(
  const ArSession *session,
  const ArPlane *plane,
  ArPose *out_pose
)

Returns the pose of the center position of the plane's bounding rectangle.

The pose's transformed +Y axis will be a normal vector pointing out of plane. The transformed +X and +Z axes represent right and up relative to the plane.

Details
Parameters
session
The ARCore session.
plane
The plane for which to retrieve center pose.
out_pose
An already-allocated ArPose object into which the pose will be stored.

ArPlane_getExtentX

void ArPlane_getExtentX(
  const ArSession *session,
  const ArPlane *plane,
  float *out_extent_x
)

Retrieves the length of this plane's bounding rectangle measured along the local X-axis of the coordinate space defined by the output of ArPlane_getCenterPose.

ArPlane_getExtentZ

void ArPlane_getExtentZ(
  const ArSession *session,
  const ArPlane *plane,
  float *out_extent_z
)

Retrieves the length of this plane's bounding rectangle measured along the local Z-axis of the coordinate space defined by the output of ArPlane_getCenterPose.

ArPlane_getPolygon

void ArPlane_getPolygon(
  const ArSession *session,
  const ArPlane *plane,
  float *out_polygon_xz
)

Returns the 2D vertices of a convex polygon approximating the detected plane, in the form [x1, z1, x2, z2, ...].

These x and z values are in the plane's local X-Z plane (y=0) and must be transformed by the pose (ArPlane_getCenterPose) to get the boundary in world coordinates.

Details
Parameters
session
The ARCore session.
plane
The plane to retrieve the polygon from.
out_polygon_xz
A pointer to an array of floats. The length of this array must be at least that reported by ArPlane_getPolygonSize.

ArPlane_getPolygonSize

void ArPlane_getPolygonSize(
  const ArSession *session,
  const ArPlane *plane,
  int32_t *out_polygon_size
)

Retrieves the number of elements (not vertices) in the boundary polygon.

The number of vertices is half this size.

ArPlane_getType

void ArPlane_getType(
  const ArSession *session,
  const ArPlane *plane,
  ArPlaneType *out_plane_type
)

Retrieves the type (orientation) of the plane.

See ArPlaneType.

ArPlane_isPoseInExtents

void ArPlane_isPoseInExtents(
  const ArSession *session,
  const ArPlane *plane,
  const ArPose *pose,
  int32_t *out_pose_in_extents
)

Sets *out_pose_in_extents to non-zero if the given pose (usually obtained from an ArHitResult) is in the plane's rectangular extents.

ArPlane_isPoseInPolygon

void ArPlane_isPoseInPolygon(
  const ArSession *session,
  const ArPlane *plane,
  const ArPose *pose,
  int32_t *out_pose_in_polygon
)

Sets *out_pose_in_extents to non-zero if the given pose (usually obtained from an ArHitResult) is in the plane's polygon.