Thanks for tuning in to Google I/O! Watch AR content on-demand.

ArAugmentedFace

Describes a face detected by ARCore and provides functions to access additional center and face region poses as well as face mesh related data.

Augmented Faces supports front-facing (selfie) camera only, and does not support attaching anchors nor raycast hit testing. Calling ArTrackable_acquireNewAnchor will return AR_ERROR_ILLEGAL_STATE.

Summary

Enumerations
`ArAugmentedFaceRegionType{ AR_AUGMENTED_FACE_REGION_NOSE_TIP = 0, AR_AUGMENTED_FACE_REGION_FOREHEAD_LEFT = 1, AR_AUGMENTED_FACE_REGION_FOREHEAD_RIGHT = 2 }`	enum Defines face regions to query the pose for.

Typedefs
`ArAugmentedFace`	typedef `struct ArAugmentedFace_` A detected face trackable (reference type, long-lived).

Functions
`ArAugmentedFace_getCenterPose(const ArSession session, const ArAugmentedFace face, ArPose *out_pose)`	`void` Returns the pose of the center of the face.
`ArAugmentedFace_getMeshNormals(const ArSession session, const ArAugmentedFace face, const float *out_normals, int32_t out_number_of_normals)`	`void` Returns a pointer to an array of 3D normals in (x, y, z) packing, where each (x, y, z) is a unit vector of the normal to the surface at each vertex.
`ArAugmentedFace_getMeshTextureCoordinates(const ArSession session, const ArAugmentedFace face, const float *out_texture_coordinates, int32_t out_number_of_texture_coordinates)`	`void` Returns a pointer to an array of UV texture coordinates in (u, v) packing.
`ArAugmentedFace_getMeshTriangleIndices(const ArSession session, const ArAugmentedFace face, const uint16_t *out_triangle_indices, int32_t out_number_of_triangles)`	`void` Returns a pointer to an array of triangles indices in consecutive triplets.
`ArAugmentedFace_getMeshVertices(const ArSession session, const ArAugmentedFace face, const float *out_vertices, int32_t out_number_of_vertices)`	`void` Returns a pointer to an array of 3D vertices in (x, y, z) packing.
`ArAugmentedFace_getRegionPose(const ArSession session, const ArAugmentedFace face, const ArAugmentedFaceRegionType region_type, ArPose *out_pose)`	`void` Returns the pose of a face region in world coordinates when the face trackable state is `AR_TRACKING_STATE_TRACKING`.

Enumerations

ArAugmentedFaceRegionType

 ArAugmentedFaceRegionType

Defines face regions to query the pose for.

Left and right are defined relative to the person that the mesh belongs to. To retrieve the center pose use ArAugmentedFace_getCenterPose.

Properties
`AR_AUGMENTED_FACE_REGION_FOREHEAD_LEFT`	The region at the detected face's left side of the forehead.
`AR_AUGMENTED_FACE_REGION_FOREHEAD_RIGHT`	The region at the detected face's right side of the forehead.
`AR_AUGMENTED_FACE_REGION_NOSE_TIP`	The region at the tip of the nose.

Typedefs

ArAugmentedFace

struct ArAugmentedFace_ ArAugmentedFace

A detected face trackable (reference type, long-lived).

Trackable type: AR_TRACKABLE_FACE
Release with: ArTrackable_release

Functions

ArAugmentedFace_getCenterPose

void ArAugmentedFace_getCenterPose(
  const ArSession *session,
  const ArAugmentedFace *face,
  ArPose *out_pose
)

Returns the pose of the center of the face.

Details

Parameters

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

ArAugmentedFace_getMeshNormals

void ArAugmentedFace_getMeshNormals(
  const ArSession *session,
  const ArAugmentedFace *face,
  const float **out_normals,
  int32_t *out_number_of_normals
)

Returns a pointer to an array of 3D normals in (x, y, z) packing, where each (x, y, z) is a unit vector of the normal to the surface at each vertex.

There is exactly one normal vector for each vertex. These normals are relative to the center pose of the face.

The pointer returned by this function is valid until ArTrackable_release or the next ArSession_update is called. The application must copy the data if they wish to retain it for longer.

If the face's tracking state is AR_TRACKING_STATE_PAUSED, then the value of the size of the returned array is 0.

Details

Parameters

`session`	The ARCore session.
`face`	The face for which to retrieve normals.
`out_normals`	A pointer to an array of 3D normals in (x, y, z) packing.
`out_number_of_normals`	The number of normals in the mesh. The returned pointer will point to an array of size `out_number_of_normals` * 3, or `NULL` if the size is 0.

ArAugmentedFace_getMeshTextureCoordinates

void ArAugmentedFace_getMeshTextureCoordinates(
  const ArSession *session,
  const ArAugmentedFace *face,
  const float **out_texture_coordinates,
  int32_t *out_number_of_texture_coordinates
)

Returns a pointer to an array of UV texture coordinates in (u, v) packing.

There is a pair of texture coordinates for each vertex. These values never change.

The pointer returned by this function is valid until ArTrackable_release or the next ArSession_update is called. The application must copy the data if they wish to retain it for longer.

If the face's tracking state is AR_TRACKING_STATE_PAUSED, then the value of the size of the returned array is 0.

Details

Parameters

`session`	The ARCore session.
`face`	The face for which to retrieve texture coordinates.
`out_texture_coordinates`	A pointer to an array of UV texture coordinates in (u, v) packing.
`out_number_of_texture_coordinates`	The number of texture coordinates in the mesh. The returned pointer will point to an array of size `out_number_of_texture_coordinates` * 2, or `NULL` if the size is 0.

ArAugmentedFace_getMeshTriangleIndices

void ArAugmentedFace_getMeshTriangleIndices(
  const ArSession *session,
  const ArAugmentedFace *face,
  const uint16_t **out_triangle_indices,
  int32_t *out_number_of_triangles
)

Returns a pointer to an array of triangles indices in consecutive triplets.

Every three consecutive values are indices that represent a triangle. The vertex position and texture coordinates are mapped by the indices. The front face of each triangle is defined by the face where the vertices are in counter clockwise winding order. These values never change.

The pointer returned by this function is valid until ArTrackable_release or the next ArSession_update is called. The application must copy the data if they wish to retain it for longer.

If the face's tracking state is AR_TRACKING_STATE_PAUSED, then the value of the size of the returned array is 0.

Details

Parameters

`session`	The ARCore session.
`face`	The face for which to retrieve triangle indices.
`out_triangle_indices`	A pointer to an array of triangle indices packed in consecutive triplets.
`out_number_of_triangles`	The number of triangles in the mesh. The returned pointer will point to an array of size `out_number_of_triangles` * 3, or `NULL` if the size is 0.

ArAugmentedFace_getMeshVertices

void ArAugmentedFace_getMeshVertices(
  const ArSession *session,
  const ArAugmentedFace *face,
  const float **out_vertices,
  int32_t *out_number_of_vertices
)

Returns a pointer to an array of 3D vertices in (x, y, z) packing.

These vertices are relative to the center pose of the face with units in meters.

The pointer returned by this function is valid until ArTrackable_release or the next ArSession_update is called. The application must copy the data if they wish to retain it for longer.

If the face's tracking state is AR_TRACKING_STATE_PAUSED, then the value of the size of the returned array is 0.

Details

Parameters

`session`	The ARCore session.
`face`	The face for which to retrieve vertices.
`out_vertices`	A pointer to an array of 3D vertices in (x, y, z) packing.
`out_number_of_vertices`	The number of vertices in the mesh. The returned pointer will point to an array of size `out_number_of_vertices` * 3 or `NULL` if the size is 0.

ArAugmentedFace_getRegionPose

void ArAugmentedFace_getRegionPose(
  const ArSession *session,
  const ArAugmentedFace *face,
  const ArAugmentedFaceRegionType region_type,
  ArPose *out_pose
)

Returns the pose of a face region in world coordinates when the face trackable state is AR_TRACKING_STATE_TRACKING.

When face trackable state is AR_TRACKING_STATE_PAUSED, the identity pose will be returned.

Details

Parameters

`session`	The ARCore session.
`face`	The face for which to retrieve face region pose.
`region_type`	The face region for which to get the pose.
`out_pose`	The Pose of the selected region when `AR_TRACKING_STATE_TRACKING`, or an identity pose when `AR_TRACKING_STATE_PAUSED`.