Python 版人脸检测指南

借助 MediaPipe 人脸检测器任务，您可以检测图片或视频中的人脸。您可以使用 此任务在帧中定位人脸和面部特征。此任务使用 可处理单张图片或连续图片 图像流。该任务会输出人脸位置，以及以下信息 面部关键点：左眼、右眼、鼻尖、嘴巴、左眼悲剧以及 右眼的悲剧。

您可在 GitHub 如需详细了解功能、模型和配置选项 部分，请参阅概览。

代码示例

面部检测器的示例代码提供了该 API 的完整实现， 供您参考。此代码可帮助您测试此任务， 开始构建自己的面部检测器。您可以查看、运行 修改 人脸检测器示例代码 只需使用网络浏览器即可。

如果您要为 Raspberry Pi 实现人脸检测器，请参阅 Raspberry Pi 示例 app。

设置

本部分介绍了设置开发环境和 代码项目。有关 设置开发环境以使用 MediaPipe 任务，包括 平台版本要求，请参阅 Python 设置指南。

<ph type="x-smartling-placeholder">

软件包

MediaPipe Face Detector 任务需要 mediapipe PyPI 软件包。 您可以使用以下命令安装并导入这些依赖项：

$ python -m pip install mediapipe

导入

导入以下类以访问人脸检测器任务函数：

import mediapipe as mp
from mediapipe.tasks import python
from mediapipe.tasks.python import vision

型号

MediaPipe 人脸检测器任务需要一个与此训练兼容的模型， 任务。如需详细了解人脸检测器的可用训练模型，请参阅 任务概览的“模型”部分。

选择并下载模型，然后将其存储在本地目录中：

model_path = '/absolute/path/to/face_detector.task'

使用 BaseOptions 对象 model_asset_path 参数指定路径 要使用的模型。如需查看代码示例，请参阅下一部分。

创建任务

MediaPipe 人脸检测器任务使用 create_from_options 函数 设置任务。create_from_options 函数接受值 处理配置选项如需详细了解配置 选项，请参阅配置选项。

以下代码演示了如何构建和配置此任务。

这些示例还展示了图片任务构建的不同变体， 视频文件和直播服务

映像

import mediapipe as mp

BaseOptions = mp.tasks.BaseOptions
FaceDetector = mp.tasks.vision.FaceDetector
FaceDetectorOptions = mp.tasks.vision.FaceDetectorOptions
VisionRunningMode = mp.tasks.vision.RunningMode

# Create a face detector instance with the image mode:
options = FaceDetectorOptions(
    base_options=BaseOptions(model_asset_path='/path/to/model.task'),
    running_mode=VisionRunningMode.IMAGE)
with FaceDetector.create_from_options(options) as detector:
  # The detector is initialized. Use it here.
  # ...

视频

import mediapipe as mp

BaseOptions = mp.tasks.BaseOptions
FaceDetector = mp.tasks.vision.FaceDetector
FaceDetectorOptions = mp.tasks.vision.FaceDetectorOptions
VisionRunningMode = mp.tasks.vision.RunningMode

# Create a face detector instance with the video mode:
options = FaceDetectorOptions(
    base_options=BaseOptions(model_asset_path='/path/to/model.task'),
    running_mode=VisionRunningMode.VIDEO)
with FaceDetector.create_from_options(options) as detector:
  # The detector is initialized. Use it here.
  # ...

直播

import mediapipe as mp

BaseOptions = mp.tasks.BaseOptions
FaceDetector = mp.tasks.vision.FaceDetector
FaceDetectorOptions = mp.tasks.vision.FaceDetectorOptions
FaceDetectorResult = mp.tasks.vision.FaceDetectorResult
VisionRunningMode = mp.tasks.vision.RunningMode

# Create a face detector instance with the live stream mode:
def print_result(result: FaceDetectorResult, output_image: mp.Image, timestamp_ms: int):
    print('face detector result: {}'.format(result))

options = FaceDetectorOptions(
    base_options=BaseOptions(model_asset_path='/path/to/model.task'),
    running_mode=VisionRunningMode.LIVE_STREAM,
    result_callback=print_result)
with FaceDetector.create_from_options(options) as detector:
  # The detector is initialized. Use it here.
  # ...

有关创建与图片搭配使用的面部检测器的完整示例，请参阅 代码示例。

配置选项

此任务具有以下适用于 Python 应用的配置选项：

选项名称 说明 值范围 默认值
running_mode 设置任务的运行模式。有三个 模式：

IMAGE：单图输入的模式。

VIDEO：视频已解码帧的模式。

LIVE_STREAM：输入流媒体直播模式 例如来自相机的数据。在此模式下，resultListener 必须为 调用以设置监听器以接收结果 异步执行。		 {IMAGE, VIDEO, LIVE_STREAM} IMAGE
min_detection_confidence 被视为成功的面部检测的最低置信度分数。 Float [0,1] 0.5
min_suppression_threshold 将人脸检测视为重叠的最小非最大抑制阈值。 Float [0,1] 0.3
result_callback 设置结果监听器以接收检测结果 当面部检测器在直播中时异步 模式。只有在跑步模式设置为 LIVE_STREAM 时才能使用。 N/A Not set

准备数据

将输入准备为图片文件或 Numpy 数组， 然后将其转换为 mediapipe.Image 对象。如果输入是视频文件 或使用摄像头进行直播时，您可以使用外部媒体库，例如 OpenCV：以 Numpy 形式加载输入帧 数组。

映像

import mediapipe as mp

# Load the input image from an image file.
mp_image = mp.Image.create_from_file('/path/to/image')

# Load the input image from a numpy array.
mp_image = mp.Image(image_format=mp.ImageFormat.SRGB, data=numpy_image)

视频

import mediapipe as mp

# Use OpenCV’s VideoCapture to load the input video.

# Load the frame rate of the video using OpenCV’s CV_CAP_PROP_FPS
# You’ll need it to calculate the timestamp for each frame.

# Loop through each frame in the video using VideoCapture#read()

# Convert the frame received from OpenCV to a MediaPipe’s Image object.
mp_image = mp.Image(image_format=mp.ImageFormat.SRGB, data=numpy_frame_from_opencv)

直播

import mediapipe as mp

# Use OpenCV’s VideoCapture to start capturing from the webcam.

# Create a loop to read the latest frame from the camera using VideoCapture#read()

# Convert the frame received from OpenCV to a MediaPipe’s Image object.
mp_image = mp.Image(image_format=mp.ImageFormat.SRGB, data=numpy_frame_from_opencv)

运行任务

人脸检测器使用 detect、detect_for_video 和 detect_async 函数来触发推理。对于人脸检测，这涉及 预处理输入数据并检测图片中的人脸。

以下代码演示了如何使用任务模型执行处理。

映像

# Perform face detection on the provided single image.
# The face detector must be created with the image mode.
face_detector_result = detector.detect(mp_image)

视频

# Perform face detection on the provided single image.
# The face detector must be created with the video mode.
face_detector_result = detector.detect_for_video(mp_image, frame_timestamp_ms)

直播

# Send live image data to perform face detection.
# The results are accessible via the `result_callback` provided in
# the `FaceDetectorOptions` object.
# The face detector must be created with the live stream mode.
detector.detect_async(mp_image, frame_timestamp_ms)

请注意以下几点：

  • 在视频模式或直播模式下运行时， 为面部检测器任务提供输入帧的时间戳。
  • 在图片或视频模型中运行时，人脸检测器任务 阻塞当前线程，直到它处理完输入图像，或者 帧。
  • 在直播模式下运行时，人脸检测器任务会返回 而且不会阻塞当前线程它将调用结果 并在每次处理完一个监听器后都返回检测结果 输入帧。如果在执行人脸检测器任务时调用检测函数， 正忙于处理另一个帧，则任务将忽略新的输入帧。

有关对图片运行面部检测器的完整示例，请参阅 代码示例 了解详情。

处理和显示结果

人脸检测器会针对每次检测返回一个 FaceDetectorResult 对象 运行。结果对象包含检测到的人脸的边界框和一个 置信度分数。

以下示例展示了此任务的输出数据：

FaceDetectionResult:
  Detections:
    Detection #0:
      BoundingBox:
        origin_x: 126
        origin_y: 100
        width: 463
        height: 463
      Categories:
        Category #0:
          index: 0
          score: 0.9729152917861938
      NormalizedKeypoints:
        NormalizedKeypoint #0:
          x: 0.18298381567001343
          y: 0.2961040139198303
        NormalizedKeypoint #1:
          x: 0.3302789330482483
          y: 0.29289937019348145
        ... (6 keypoints for each face)
    Detection #1:
      BoundingBox:
        origin_x: 616
        origin_y: 193
        width: 430
        height: 430
      Categories:
        Category #0:
          index: 0
          score: 0.9251380562782288
      NormalizedKeypoints:
        NormalizedKeypoint #0:
          x: 0.6151331663131714
          y: 0.3713381886482239
        NormalizedKeypoint #1:
          x: 0.7460576295852661
          y: 0.38825345039367676
        ... (6 keypoints for each face)

下图直观显示了任务输出：

对于没有边界框的图片，请参阅原始图片。

面部检测器示例代码演示了如何显示 结果，请参阅 代码示例。 了解详情。