全新推出：LiteRT：Google 专为设备端 AI 打造的高性能运行时，以前称为 TensorFlow Lite。

此页面由 Cloud Translation API 翻译。

Python 版人脸检测指南

借助 MediaPipe 人脸检测器任务，您可以检测图片或视频中的人脸。您可以使用此任务在画面中定位人脸和面部特征。此任务使用可处理单张图片或连续图片流的机器学习 (ML) 模型。该任务会输出脸部位置以及以下面部关键点：左眼、右眼、鼻尖、嘴巴、左眼屏点和右眼屏点。

这些说明中介绍的代码示例可在 GitHub 上找到。如需详细了解此任务的功能、模型和配置选项，请参阅概览。

代码示例

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

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

设置

本部分介绍了专门用于设置开发环境和代码项目以使用人脸检测器的关键步骤。如需了解有关设置开发环境以使用 MediaPipe 任务的一般信息（包括平台版本要求），请参阅 Python 设置指南。

软件包

MediaPipe 人脸检测器任务需要 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 函数接受配置选项要处理的值。如需详细了解配置选项，请参阅配置选项。

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

这些示例还展示了图片、视频文件和直播的任务构建变体。

Image

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：适用于单张图片输入的模式。视频：视频的解码帧的模式。 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 数组。

Image

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 函数触发推理。对于人脸检测，这涉及预处理输入数据和检测图片中的人脸。

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

Image

# 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)

下图显示了任务输出的可视化结果：

两名儿童，脸部周围有边界框

如需查看没有边界框的图片，请参阅原始图片。

人脸检测器示例代码演示了如何显示从任务返回的结果，如需了解详情，请参阅代码示例。