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

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.