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