MLKitFaceDetector 拓展：离线人脸检测（表情 / 睁闭眼 / 头部姿态）

• MLKitFaceDetector 拓展
  • 快速上手
    • 一、检测人脸并报告有几张
    • 二、判断有没有在笑（要先打开分类）
    • 三、追求速度：关掉所有可选项
    • 四、只检测画面里较大的人脸
  • 属性
  • 事件
  • 方法
  • 运行环境：AI 伴侣联机需要 Android 11 及以上
  • 常见问题

« 返回首页

MLKitFaceDetector 拓展

检测图片里的人脸：位置框、微笑概率、左右眼睁开概率、头部三轴转角， 还可选关键点（眼、耳、鼻、嘴）和面部轮廓。

这是人脸检测，不是人脸识别。它告诉你「这里有一张脸、在笑、眼睛闭着」， 不会告诉你「这是张三」。要做身份比对/人脸库检索需要别的方案（本拓展做不到）。

为什么选它：

• 完全离线。模型随 .aix 打包，设备不需要 Google Play 服务，断网也能用。
• 微笑和睁眼概率开箱可用 —— 做「笑一笑自动拍照」「闭眼检测」这类交互很直接。
• 支持跟踪 ID，同一张脸在连续多张图里能对应上。

常用场景：自拍趣味应用、笑脸抓拍、疲劳/闭眼提醒、人脸贴纸定位。

• .aix 拓展下载：

cn.fun123.MLKit.FaceDetector.aix

快速上手

一、检测人脸并报告有几张

when 图像选择器1.AfterPicking() {
  标签1.Text = "检测中…"
  FaceDetector1.DetectFromFile(图像选择器1.Selection)
}
when FaceDetector1.DetectionSuccess(resultJson, faceCount) {
  if faceCount > 0 {
    标签1.Text = join("检测到 ", faceCount, " 张人脸")
    标签_原始结果.Text = resultJson
  } else {
    标签1.Text = "没检测到人脸"
  }
}
when FaceDetector1.DetectionFailed(operation, errorMessage) {
  标签1.Text = errorMessage
}

二、判断有没有在笑（要先打开分类）

when Screen1.Initialize() {
  FaceDetector1.Classifications = true
}
when 按钮_校验.Click() {
  FaceDetector1.DetectFromFile(图像选择器1.Selection)
}
when FaceDetector1.DetectionSuccess(resultJson, faceCount) {
  标签_原始结果.Text = resultJson
}

resultJson 的形状（用「JSON 文本解码」块解析，smilingProbability 就是微笑概率 0～1）：

{"faceCount":1,
 "faces":[{"bounds":{"left":120,"top":80,"right":420,"bottom":460},
           "trackingId":-1,
           "smilingProbability":0.93,
           "leftEyeOpenProbability":0.98,
           "rightEyeOpenProbability":0.97,
           "headEulerAngleX":2.1,
           "headEulerAngleY":-5.4,
           "headEulerAngleZ":1.2}]}

smilingProbability / leftEyeOpenProbability / rightEyeOpenProbability 只有把 分类 属性设为「真」时才有值，否则这几个字段不会出现。

三、追求速度：关掉所有可选项

when Screen1.Initialize() {
  FaceDetector1.AccurateMode = false
  FaceDetector1.Landmarks = false
  FaceDetector1.Contours = false
  FaceDetector1.Classifications = false
}

四、只检测画面里较大的人脸

when Screen1.Initialize() {
  FaceDetector1.MinFaceSize = 0.25
}

属性

AccurateMode

精确模式。「真」= 更准但更慢；「假」= 更快。做单张照片分析用真，做连续帧用假。

Landmarks

是否检测关键点（左右眼、左右耳、鼻底、左右嘴角、左右脸颊的坐标）。 打开会变慢。做人脸贴纸定位时需要。

Contours

是否检测面部轮廓（脸、眉、眼、唇的密集点集）。 最耗性能的选项，且只对画面里最显眼的那张脸有效。

Classifications

是否给出微笑概率和睁眼概率。 要用 smilingProbability / leftEyeOpenProbability / rightEyeOpenProbability 就必须打开这个。

Tracking

是否启用人脸跟踪。打开后同一张脸在连续多张图里会有相同的 trackingId。 关闭时 trackingId 为 -1。

MinFaceSize

最小人脸尺寸，0～1，表示人脸宽度占图片宽度的比例。 默认较小（能检测到远处小脸）；调大（如 0.25）只检测近处大脸，会更快。

Busy

只读。是否正在检测。

事件

DetectionSuccess(resultJson,faceCount)

检测完成。faceCount 是人脸数量（可能为 0，表示没检测到，这不是错误）； resultJson 含每张脸的位置框、跟踪 ID、以及按属性开关决定的概率 / 关键点 / 轮廓（见示例二）。

DetectionFailed(operation,errorMessage)

检测失败。operation 是出错的方法名。

方法

DetectFromFile(path)

检测图片文件中的人脸。path 可以是素材文件名、设备路径、file:// 或 content:// 地址。

DetectFromBase64(base64)

检测 Base64 图片中的人脸。支持带 data:image/...;base64, 前缀的写法。

运行环境：AI 伴侣联机需要 Android 11 及以上

本拓展的识别模型放在依赖库自带的 assets 里，AI 伴侣联机调试要把它挂进 AssetManager，用的是 Android 11（API 30）才有的 ResourcesLoader —— 这是系统提供的 唯一公开办法，更低版本没有等价 API。所以：

打包 APK 之所以不受限制，是因为模型在编译时就被并进了 APK 的 assets，装到手机上 就是 App 自己的资源，与系统版本无关。伴侣的 APK 是提前编好装在手机上的，运行时没法 往自己已安装的包里加文件，只能靠系统的运行时挂载 API。

低版本设备上想验证功能，直接打包 APK 测即可；要用伴侣边改边调，请换 Android 11+ 的设备。

常见问题

smilingProbability 字段不见了。 分类 属性没打开。这三个概率字段只有 Classifications = 真 时才计算。

能识别”这是谁”吗？ 不能。这是人脸检测（有没有脸、什么状态），不是人脸识别（是谁）。 身份比对需要人脸特征提取 + 特征库检索，ML Kit 的这个 API 不提供。

检测很慢。 按耗时从大到小关掉：轮廓（最重）→ 关键点 → 精确模式。 另外把 最小人脸尺寸 调大（如 0.25）能显著提速。

faceCount 是 0 但图里明显有脸。 可能是脸太小（调低 最小人脸尺寸）、侧脸角度太大、遮挡太多、或光线太暗。 ML Kit 对正面/小角度侧脸效果最好。

能检测摄像头实时画面吗？ 本拓展是单张图片模式。实时检测要摄像头预览 + 逐帧处理，可参考本仓库 MLKit.CodeScanner 的实时预览实现思路，但本拓展当前不提供该能力。