HarmonyOS 鸿蒙NEXT Core Vision人脸检测器API的详细说明

1. 核心功能 (Core Functionality)

• 检测图像中的人脸位置和朝向： 主要功能是识别图像（静态图片或视频帧）中是否存在人脸，并定位其位置（通过边界框表示）。
• 检测人脸关键点： 能够返回人脸的关键点坐标（Landmarks），例如：
  • 眼睛（左右眼中心）
  • 鼻子（鼻尖）
  • 嘴巴（左右嘴角）
• 检测人脸朝向： 提供人脸相对于摄像头的旋转角度（偏航角、俯仰角、翻滚角 - pitch, roll, yaw）。
• 多人脸检测： 支持在同一帧图像中检测多张人脸。

2. 输入源 (Input Sources)

• 支持多种图像数据格式作为输入：
  • PixelMap (HarmonyOS的像素图对象)
  • ImageSource (图像源对象)
  • ArrayBuffer (包含图像原始数据的缓冲区，需配合Image对象使用)

3. 主要API接口与类 (Key APIs & Classes)

• faceDetector (全局对象)： 人脸检测服务的入口点。
• createFaceDetector() : 用于创建人脸检测器实例 (FaceDetector)。
• FaceDetector 类：
• detect() : 核心方法，执行人脸检测。接受图像数据源和检测配置选项 (DetectOptions) 作为参数，返回一个Promise<Array<Face>>。
• release() : 释放检测器占用的资源。重要：使用完毕后必须调用以释放资源。
• DetectOptions 接口： 配置检测行为的选项。
  • performanceMode：性能模式 (PerformanceMode.LOW_POWER 低功耗模式 / PerformanceMode.FAST 快速模式)，影响检测速度和精度。
  • faceFieldOptions：指定需要检测并返回的人脸属性字段 (如 boundingBox, landmarks, rotationAngle, confidence 等)。
  • maxFaces：设置单次检测最多返回的人脸数量。
  • minFaceSize：设置最小可检测的人脸尺寸（占图像短边的比例）。
  • confidenceThreshold：置信度阈值，低于此阈值的结果将被过滤掉。
• Face 接口： 表示检测到的单个人脸的结果对象。
  • boundingBox：人脸在图像中的矩形区域 (Rect)。
  • landmarks：人脸关键点数组 (Array<Landmark>), 每个点包含 x, y 坐标。
  • rotationAngle：人脸的旋转角度 (FaceRotation)，包含 pitch, roll, yaw 值。
  • confidence：人脸存在的置信度 (0.0 - 1.0)。
• Rect, Landmark, FaceRotation: 用于描述位置、关键点、旋转角度的数据结构。

4. 使用流程 (Workflow)

1. 权限申请： 在应用的 config.json 中声明 ohos.permission.CAMERA 权限（如果检测相机数据流）。
2. 创建检测器： 使用 faceDetector.createFaceDetector(context) 创建 FaceDetector 实例。
3. 准备输入源： 获取需要检测的图像数据 (PixelMap, ImageSource, ArrayBuffer)。
4. 配置选项： 创建 DetectOptions 对象，根据需要设置性能模式、需要返回的字段、最大人脸数等。
5. 执行检测： 调用 detector.detect(source, options) 进行异步检测。
6. 处理结果： 在 Promise 的 then 方法中获取检测到的 Face[] 数组，遍历处理每个人脸信息（位置、关键点、朝向、置信度）。
7. 释放资源： 检测完成后，调用 detector.release() 释放资源。

5. 示例代码 (Snippet - Core Part)

// 1. 导入模块
import faceDetector from '@ohos.multimedia.vision.faceDetector';
import image from '@ohos.multimedia.image';

// 2. 假设已获取到 imageSource (如从相机或图片库)
// 3. 创建检测器
let detector = faceDetector.createFaceDetector(context); // context 是 AbilityContext 或 UIAbilityContext

// 4. 配置选项：检测边界框、关键点、旋转角，最多5张脸，使用快速模式
let options = {
  performanceMode: faceDetector.PerformanceMode.FAST,
  faceFieldOptions: {
    boundingBox: true,
    landmarks: true,
    rotationAngle: true
  },
  maxFaces: 5
};

// 5. 执行检测
detector.detect(imageSource, options)
  .then(faces => {
    console.log('检测到人脸数量: ' + faces.length);
    faces.forEach((face, index) => {
      console.log(`第 ${index + 1} 张脸:`);
      console.log(' - 位置: ' + JSON.stringify(face.boundingBox));
      console.log(' - 关键点: ' + JSON.stringify(face.landmarks));
      console.log(' - 朝向 (pitch, roll, yaw): ' + `${face.rotationAngle.pitch}, ${face.rotationAngle.roll}, ${face.rotationAngle.yaw}`);
      console.log(' - 置信度: ' + face.confidence);
    });
  })
  .catch(err => {
    console.error('人脸检测失败: ' + JSON.stringify(err));
  })
  .finally(() => {
    // 6. 释放检测器 (非常重要!)
    detector.release();
  });

6. 重要技术参数/限制 (Technical Parameters/Limits)

• 支持的图像格式： JPEG, PNG, YUV 等常见格式（具体依赖 PixelMap/ImageSource 支持）。
• 关键点数量： 文档示例通常返回5个关键点（双眼、鼻尖、两嘴角）。具体返回哪些点由 faceFieldOptions.landmarks 配置决定。
• 性能： 检测速度受 performanceMode、图像大小、检测的人脸数量和复杂度、设备硬件性能影响。
• 最小人脸尺寸： 受 minFaceSize 设置和设备能力限制，通常建议人脸宽度大于图像短边的 1/20 到 1/15 以保证可靠检测。
• 设备兼容性： API 的可用性和性能因搭载 HarmonyOS 的设备硬件能力而异。

7. 关键注意事项 (Important Notes)

• 资源释放 (release()) : 必须在使用完 FaceDetector 实例后调用 release() 以避免内存泄漏和资源耗尽。
• 权限 (CAMERA) : 如果检测的源是实时相机数据流，必须在 config.json 中声明 ohos.permission.CAMERA 权限并在运行时动态申请。
• 异步操作： detect() 是异步操作，返回 Promise，需要使用 .then/.catch 或 async/await 处理结果和错误。
• 性能优化：
  • 选择合适的 performanceMode (FAST 用于实时预览，LOW_POWER 用于后台或对速度要求不高的场景)。
  • 根据实际需要配置 faceFieldOptions，避免请求不必要的数据提升速度。
  • 适当设置 maxFaces 和 minFaceSize。
  • 对输入图像进行适当缩放（在满足最小人脸检测尺寸前提下）可以显著提高检测速度。

总结：

HarmonyOS Core Vision Face Detector API 可以实现人脸检测、关键点定位和人脸朝向判断。需要关注权限申请、资源释放、配置优化以及异步处理等关键点。