Estimated environmental lighting information associated with a captured video frame in a face-tracking AR session.

估计的环境照明信息与脸部追踪AR Session中捕获的视频帧相关联。

Overview

When you run a face tracking AR session (see ARFaceTrackingConfiguration) with the lightEstimationEnabled property set to YES, ARKit uses the detected face as a light probe to estimate the directional lighting environment in the scene. The lightEstimateproperty of each frame vended by the session contains an ARDirectionalLightEstimateinstance containing this information.

If you render your own overlay graphics for the AR scene, you can use this information in shading algorithms to help make those graphics match the real-world lighting conditions of the scene captured by the camera. (The ARSCNView class automatically uses this information to configure SceneKit lighting.)

概述

当您将lightEstimationEnabled属性设置为YES时，运行人脸跟踪ARSession（请参阅ARFaceTrackingConfiguration）时，ARKit会使用检测到的人脸作为光线探测器来估计场景中的定向照明环境。 Session给出的每个帧的lightEstimate属性包含一个包含此信息的ARDirectionalLightEstimate实例。

如果您为AR场景渲染自己的叠加图形，则可以在着色算法中使用此信息，以帮助使这些图形与相机捕捉的场景的真实照明条件相匹配。 （ARSCNView类自动使用此信息配置SceneKit照明。）

                    Examining Light Parameters

sphericalHarmonicsCoefficients
Data describing the estimated lighting environment in all directions.
描述所有方向的估计照明环境的数据。

Discussion

Spherical harmonics provide a compact mathematical model for the global lighting environment around a point in space, describing the distribution and colors of multiple directional light sources. When used in a renderer that supports environment-based lighting, spherical harmonics provide much less high-frequency detail than a cube map texture, but make much more efficient use of GPU resources.

ARKit provides second-level spherical harmonics in separate red, green, and blue data planes. Thus, this data buffer contains 3 sets of 9 coefficients, or a total of 27 values of 32-bit floating point type.

讨论

球面谐波为空间点周围的全球照明环境提供了一个紧凑的数学模型，描述了多个定向光源的分布和颜色。 在支持基于环境照明的渲染器中使用时，球面谐波比立方体贴图纹理提供更少的高频细节，但可以更高效地使用GPU资源。

ARKit在分开的红色，绿色和蓝色数据平面中提供二级球面谐波。 因此，该数据缓冲区包含3组9个系数，或总共27个32位浮点类型的值。

primaryLightDirection
A vector indicating the orientation of the strongest directional light source in the scene.
指示场景中最强定向光源的方向的矢量。

Discussion

When ARKit analyzes the directional lighting environment for a detected face, the resulting lighting estimate can represent the influence of multiple light sources with different directions and intensities. To access this level of detail for use in your custom rendering code, use the sphericalHarmonicsCoefficients property. 

If your app displays AR content using a technology that doesn’t support environment-based lighting, this primaryLightDirection property represents the average of directional light sources in the scene. This vector is normalized and in world coordinate space.

讨论

当ARKit分析检测面部的定向照明环境时，所得到的照明估计可以表示具有不同方向和强度的多个光源的影响。 要访问此级别的细节以用于自定义渲染代码，请使用sphericalHarmonicsCoefficients属性。

如果您的应用使用不支持基于环境照明的技术显示AR内容，则此primaryLightDirection属性表示场景中定向光源的平均值。 这个向量被标准化并且在世界坐标空间中。

primaryLightIntensity
The estimated intensity, in lumens, of the strongest directional light source in the scene.
估计的强度，流明中场景中最强的定向光源。

Discussion

When ARKit analyzes the directional lighting environment for a detected face, the resulting lighting estimate can represent the influence of multiple light sources with different directions and intensities. To access this level of detail for use in your custom rendering code, use the sphericalHarmonicsCoefficients property. 

If your app displays AR content using a technology that doesn’t support environment-based lighting, this primaryLightIntensity property represents the average of directional light sources in the scene. This value is scaled to be appropriate for use in rendering architectures that use realistic lighting metrics, with a value of 1000 representing neutral lighting.

For example, you can pass this value directly to the intensity property of a SceneKit directional light for lighting results that roughly match those of the real-world scene captured by the device camera. (However, passing this value to SceneKit is generally not necessary; the ARSCNView class automatically sets SceneKit lighting based on the sphericalHarmonicsCoefficients property.)

讨论

当ARKit分析检测面部的定向照明环境时，所得到的照明估计可以表示具有不同方向和强度的多个光源的影响。要访问此级别的细节以用于自定义渲染代码，请使用sphericalHarmonicsCoefficients属性。

如果您的应用使用不支持基于环境照明的技术显示AR内容，则此primaryLightIntensity属性表示场景中定向光源的平均值。该值被缩放为适合用于渲染使用逼真照明度量的体系结构，值为1000表示中性照明。

例如，您可以直接将此值传递给SceneKit方向灯的强度属性，以获得与设备相机捕捉的真实世界场景大致相同的照明效果。 （但是，将此值传递给SceneKit通常不是必需的; ARSCNView类会根据sphericalHarmonicsCoefficients属性自动设置SceneKit光照。）

Inherits From  ARLightEstimate