Information about the pose, topology, and expression of a face detected in a face-tracking AR session.

有关在面部跟踪AR Session中检测到的人脸姿态，拓扑和表情的信息。

Overview

When you run a face-tracking AR session (see ARFaceTrackingConfiguration), the session automatically adds to its list of anchors an ARFaceAnchor object when it detects the user’s face with the front-facing camera. Each face anchor provides information about the face’s current position and orientation, topology, and facial expression.

概述

当您运行人脸跟踪AR Session（请参阅ARFaceTrackingConfiguration）时，Session会在用前置摄像头检测到用户的脸部时自动向其锚点列表中添加一个ARFaceAnchor对象。 每个脸部锚点提供关于脸部的当前位置和方向，拓扑和面部表情的信息。

Tracking Face Position and Orientation

The inherited transform property describes the face’s current position and orientation in world coordinates; that is, in a coordinate space relative to that specified by the worldAlignment property of the session configuration. Use this transform matrix to position virtual content you want to “attach” to the face in your AR scene.

This transform matrix creates a face coordinates system for positioning other elements relative to the face. Units of face coordinate space are in meters, with the origin centered behind the face as indicated in the figure below.

跟踪脸部位置和方向

继承的transform属性描述了人脸在世界坐标中的当前位置和方向; 即在相对于Session配置的worldAlignment属性指定的坐标空间中。 使用这个变换矩阵来定位想要“附加”到AR场景中的脸部的虚拟内容。

该变换矩阵创建用于定位其他元素相对于脸部的脸部坐标系统。 如下图所示，脸部坐标空间单位为米，原点位于脸部后方。

The coordinate system is right-handed—the positive x direction points to the viewer’s right (that is, the face’s own left), the positive y direction points up (relative to the face itself, not to the world), and the positive z direction points outward from the face (toward the viewer).

坐标系是右手的，正x方向指向观察者的右侧（即，脸部自己的左侧），正y方向指向（相对于脸部本身而不是世界），以及正z 方向从脸部向外（朝向观察者）指向。

Using Face Topology

The geometry property provides an ARFaceGeometry object representing detailed topology for the face, which conforms a generic face model to match the dimensions, shape, and current expression of the detected face. 

You can use this model as the basis for overlaying content that follows the shape of the user’s face—for example, to apply virtual makeup or tattoos. You can also use this model to create occlusion geometry—a 3D model that doesn't render any visible content (allowing the camera image to show through), but that obstructs the camera's view of other virtual content in the scene.

使用面拓扑

geometry属性提供了一个ARFaceGeometry对象，该对象表示面部的详细拓扑结构，它符合通用面部模型以匹配检测到的面部的尺寸，形状和当前表达式。

您可以使用此模型作为覆盖用户脸部形状的内容的基础 - 例如，应用虚拟化妆或纹身。 您还可以使用此模型创建遮挡几何图形 - 一种不会呈现任何可见内容（允许摄像机图像显示）的3D模型，但会妨碍相机对场景中其他虚拟内容的查看。

Tracking Facial Expressions

The blendShapes property provides a high-level model of the current facial expression, described via a series of many named coefficients that represent the movement of specific facial features relative to their neutral configurations. You can use blend shape coefficients to animate 2D or 3D content, such as a character or avatar, in ways that follow the user’s facial expressions.

跟踪面部表情

blendShapes属性提供当前面部表情的高级模型，通过一系列多个命名系数进行描述，这些系数表示特定面部特征相对于其中配置的移动。 您可以使用混合形状系数按照用户面部表情的方式为2D或3D内容（如角色或头像）制作动画。

                                     Using Face Geometry

geometry
A coarse triangle mesh representing the topology of the detected face.
表示检测到的脸部拓扑的粗糙三角形网格。

Discussion

This mesh provides vertex, index, and texture coordinate buffers describing the 3D shape of the face, conforming a generic face model to match the dimensions, shape, and current expression of the detected face. 

You can visualize the face geometry by passing these buffers to your preferred rendering engine. To visualize a face geometry using SceneKit, create an ARSCNFaceGeometry instance and use its updateFromFaceGeometry: method to update it to mach the face geometry.

讨论

该网格提供了描述脸部三维形状的顶点，索引和纹理坐标缓冲区，使通用脸部模型符合检测脸部的尺寸，形状和当前表达式。

您可以通过将这些缓冲区传递给您的首选渲染引擎来可视化人脸几何。 要使用SceneKit可视化人脸几何，请创建一个ARSCNFaceGeometry实例并使用其updateFromFaceGeometry：方法更新它以加工人脸几何。

ARFaceGeometry
A 3D mesh describing face topology used in face-tracking AR sessions
描述用于面部跟踪ARSession的面部拓扑的3D网格

Overview

This class provides a general model for the detailed topology of a face, in the form of a 3D mesh appropriate for use with various rendering technologies or for exporting 3D assets. (For a quick way to visualize a face geometry using SceneKit, see the ARSCNFaceGeometry class.)

When you obtain a face geometry from an ARFaceAnchor object in a face-tracking AR session, the model conforms to match the dimensions, shape, and current expression of the detected face. You can also create a face mesh using a dictionary of named blend shape coefficients, which provides a detailed, but more efficient, description of the face’s current expression.

In an AR session, you can use this model as the basis for overlaying content that follows the shape of the user’s face—for example, to apply virtual makeup or tattoos. You can also use this model to create occlusion geometry, which hides other virtual content behind the 3D shape of the detected face in the camera image.

概述

该类为适用于各种渲染技术或用于导出3D Asset的3D网格提供了面部详细拓扑的一般模型。 （要使用SceneKit快速查看面部几何图形，请参阅ARSCNFaceGeometry类。）

当您从面部跟踪AR会话中的ARFaceAnchor对象获取面部几何体时，该模型符合检测到的面部的尺寸，形状和当前表达式。 您还可以使用名为混合形状系数的字典创建脸部网格，其中提供了有关脸部当前表情的详细但更有效的描述。

在AR会话中，您可以使用此模型作为覆盖用户脸部形状的内容的基础 - 例如，应用虚拟化妆或纹身。 您还可以使用此模型创建遮挡几何图形，该遮挡几何图形将其他虚拟内容隐藏在摄像机图像中检测到的脸部的3D形状后面。

Note

Face mesh topology is constant across ARFaceGeometry instances. That is, the values of the vertexCount, textureCoordinateCount, and triangleCount properties never change, the triangleIndices buffer always describes the same arrangement of vertices, and the textureCoordinates buffer always maps the same vertex indices to the same texture coordinates. 

Only the vertices buffer changes between face meshes provided by an AR session, indicating the change in vertex positions as ARKit adapts the mesh to the shape and expression of the user's face.

注意

面网格拓扑在ARFaceGeometry实例中保持不变。 也就是说，vertexCount，textureCoordinateCount和triangleCount属性的值始终不变，triangleIndices缓冲区始终描述相同的顶点排列，并且textureCoordinates缓冲区始终将相同的顶点索引映射到相同的纹理坐标。

只有顶点缓冲区在AR Session提供的面孔网格之间变化，指示顶点位置的变化，因为ARKit将网格调整为用户面部的形状和表情。

Accessing Mesh Data

vertexCount
The number of elements in the vertices buffer.
顶点缓冲中的元素数量。

Discussion

Face mesh topology is constant across ARFaceGeometry instances, so the value of this property is the same for all instances.

讨论

面网格拓扑在ARFaceGeometry实例中保持不变，因此此属性的值对于所有实例都是相同的。

vertices
A buffer of vertex positions for each point in the face mesh.
面网格中每个点的顶点位置的缓冲区。

Discussion

Each float3 value in this buffer represents the position of a vertex in the mesh, in face coordinates. (See Tracking Face Position and Orientation.)

The vertexCount property provides the number of elements in the buffer.

讨论

此缓冲区中的每个float3值表示网格中顶点的位置，以面坐标表示。 （请参阅跟踪脸部位置和方向。）

vertexCount属性提供缓冲区中元素的数量。

textureCoordinateCount
The number of elements in the textureCoordinates buffer.
textureCoordinates缓冲区中元素的数量。

Discussion

Face mesh topology is constant across ARFaceGeometry instances, so the value of this property is the same for all instances.

讨论

面网格拓扑在ARFaceGeometry实例中保持不变，因此此属性的值对于所有实例都是相同的。

textureCoordinates
A buffer of texture coordinate values for each point in the face mesh.
面部网格中每个点的纹理坐标值的缓冲区。

Discussion

Each float2 value in this buffer represents the UV texture coordinates for the vertex at the corresponding index in the vertices buffer.

The textureCoordinateCount property provides the number of elements in the buffer. 

Face mesh topology is constant across ARFaceGeometry instances, so the data in this buffer always maps the same vertex indices to the same texture coordinates.

讨论

此缓冲区中的每个float2值表示顶点缓冲区中相应索引处顶点的UV纹理坐标。

textureCoordinateCount属性提供缓冲区中元素的数量。

面网格拓扑在ARFaceGeometry实例中保持不变，因此此缓冲区中的数据始终将相同的顶点索引映射到相同的纹理坐标。

triangleCount
The number of triangles described by the triangleIndices buffer.
描述的三角形的数量triangleIndices缓冲。

Discussion

Each set of three indices forms a triangle, so the number of indices in the triangleIndicesbuffer is three times the triangleCount value.

Face mesh topology is constant across ARFaceGeometry instances, so the value of this property is the same for all instances.

讨论

每组三个索引形成一个三角形，因此triangleIndices缓冲区中索引的数量是triangleCount值的三倍。

面网格拓扑在ARFaceGeometry实例中保持不变，因此此属性的值对于所有实例都是相同的。

triangleIndices
A buffer of indices describing the triangle mesh formed by the face geometry's vertex data.
索引缓冲区，用于描述由面几何的顶点数据形成的三角形网格。

Discussion

Each 16-bit integer value in this buffer represents an index into the vertices and textureCoordinates buffers. Each set of three indices identifies the vertices that form a single triangle in the mesh. (That is, this buffer is appropriate for use as an index buffer for a triangle mesh in GPU-based rendering or creating 3D model asset files.)

Each set of three indices forms a triangle, so the number of indices in the triangleIndicesbuffer is three times the triangleCount value.

Face mesh topology is constant across ARFaceGeometry instances, so this buffer always describes the same arrangement of vertices. Only the vertices buffer changes between face meshes provided by an AR session, indicating the change in vertex positions as ARKit adapts the mesh to the shape and expression of the user's face.

讨论

此缓冲区中的每个16位整数值都表示顶点和textureCoordinates缓冲区的索引。 每组三个索引都标识形成网格中单个三角形的顶点。 （也就是说，此缓冲区适合用作基于GPU渲染或创建3D模型 Asset文件的三角形网格的索引缓冲区。）

每组三个索引形成一个三角形，因此triangleIndices缓冲区中索引的数量是triangleCount值的三倍。

面网格拓扑在ARFaceGeometry实例中保持不变，因此此缓冲区始终描述相同的顶点排列。 只有顶点缓冲区在AR Session提供的面孔网格之间变化，指示顶点位置的变化，因为ARKit将网格调整为用户面部的形状和表情。

               Creating a Mesh from Blend Shapes

- initWithBlendShapes:
Creates a face geometry matching the facial expression described in the specified dictionary.
创建与指定字典中描述的面部表情匹配的面部几何。

Parameters

blendShapes

A dictionary of blend shape coefficients describing a facial expression in terms of the positions of specific facial features. For any coefficient not specified in this dictionary, ARKit assumes a value of 0.0.
混合形状系数字典，用于描述特定脸部特征位置的脸部表情。 对于本字典中未指定的任何系数，ARKit假定值为0.0。

Return Value

A face geometry object, or nil if ARKit face tracking is not supported on the current device.

返回类型

面部几何对象，如果ARKit面部跟踪在当前设备上不受支持，则为零。

Discussion

Each key in the blendShapes dictionary is an ARBlendShapeLocation constant identifying a facial feature. The corresponding value is the position of that feature relative to its neutral configuration, ranging from 0.0 (neutral) to 1.0 (maximum movement). 

The format of this dictionary is identical to that provided by the ARFaceAnchor blendShapesproperty. You can use that property and this initializer to efficiently save and restore facial expression data; the serialized form of a blend shapes dictionary is more portable than that of the face mesh those coefficients describe

讨论

blendShapes字典中的每个键都是标识面部特征的ARBlendShapeLocation常量。 相应的值是该特征相对于内在配置的位置，范围从0.0（中性）到1.0（最大移动）。

该字典的格式与ARFaceAnchor blendShapes属性提供的格式相同。 您可以使用该属性和此初始化程序有效地保存和恢复面部表情数据; 混合形状词典的序列化形式比那些系数描述的脸部网格更容易携带。

Inherits From NSObject

Conforms To NSCopying, NSSecureCoding