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