姿势特征点检测指南（Android 版）

通过 MediaPipe Pose Markerer 任务，您可以检测图片或视频中人体的特征点。您可以使用此任务识别关键的身体位置，分析姿势并对动作进行分类。此任务使用适用于单个图片或视频的机器学习 (ML) 模型。该任务会在图片坐标和三维世界坐标中输出身体姿势地标。

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

代码示例

MediaPipe Tasks 示例代码是 Android 版姿势地标应用的简单实现。该示例使用实体 Android 设备上的摄像头来检测连续视频串流中的姿势。该应用还可以从设备图库中检测图片和视频中的姿势。

您可以使用该应用作为基础来开发自己的 Android 应用，也可以在修改现有应用时参考该应用。姿势地标示例代码托管在 GitHub 上。

下载代码

以下说明介绍了如何使用 git 命令行工具创建示例代码的本地副本。

如需下载示例代码，请执行以下操作：

1. 使用以下命令克隆 Git 代码库：

   git clone https://github.com/google-ai-edge/mediapipe-samples
   

2. （可选）将您的 Git 实例配置为使用稀疏结账，这样您就只有 Pose Markerer 示例应用的文件：

   cd mediapipe
   git sparse-checkout init --cone
   git sparse-checkout set examples/pose_landmarker/android
   

创建示例代码的本地版本后，您可以将项目导入 Android Studio 并运行应用。有关说明，请参阅 Android 设置指南。

关键组件

以下文件包含此姿势地标示例应用的关键代码：

• PoseLandmarkerHelper.kt - 初始化姿势地标建筑，并处理模型和委托选择。
• CameraFragment.kt - 处理设备相机以及图片和视频输入数据。
• GalleryFragment.kt - 与 OverlayView 交互以显示输出图片或视频。
• OverlayView.kt - 针对检测到的姿势实现显示。

初始设置

本部分介绍了专门针对姿势地标来设置开发环境和代码项目的关键步骤。如需了解如何为使用 MediaPipe 任务设置开发环境的一般信息（包括平台版本要求），请参阅 Android 设置指南。

依赖项

姿势特征点任务使用 com.google.mediapipe:tasks-vision 库。请将以下依赖项添加到 Android 应用的 build.gradle 文件中：

dependencies {
    implementation 'com.google.mediapipe:tasks-vision:latest.release'
}

模型

MediaPipe Pose Markerer 任务需要使用与此任务兼容的经过训练的模型包。如需详细了解姿势特征点可用的经过训练的模型，请参阅任务概览“模型”部分。

选择和下载模型，并将其存储在项目目录中：

<dev-project-root>/src/main/assets

在 ModelAssetPath 参数中指定模型的路径。在示例代码中，模型在 PoseLandmarkerHelper.kt 文件中定义：

val modelName = "pose_landmarker_lite.task"
baseOptionsBuilder.setModelAssetPath(modelName)

创建任务

MediaPipe Pose Markerer 任务使用 createFromOptions() 函数来设置该任务。createFromOptions() 函数接受配置选项的值。如需详细了解配置选项，请参阅配置选项。

姿势特征点支持以下输入数据类型：静态图片、视频文件和实时视频串流。您需要在创建任务时指定与输入数据类型对应的运行模式。选择输入数据类型对应的标签页，以查看如何创建任务。

val baseOptionsBuilder = BaseOptions.builder().setModelAssetPath(modelName)
val baseOptions = baseOptionBuilder.build()

val optionsBuilder = 
    poseLandmarker.poseLandmarkerOptions.builder()
        .setBaseOptions(baseOptionsBuilder.build())
        .setMinPoseDetectionConfidence(minPoseDetectionConfidence)
        .setMinTrackingConfidence(minPoseTrackingConfidence)
        .setMinPosePresenceConfidence(minposePresenceConfidence)
        .setNumPoses(maxNumPoses)
        .setRunningMode(RunningMode.IMAGE)

val options = optionsBuilder.build()
poseLandmarker = poseLandmarker.createFromOptions(context, options)
    

val baseOptionsBuilder = BaseOptions.builder().setModelAssetPath(modelName)
val baseOptions = baseOptionBuilder.build()

val optionsBuilder = 
    poseLandmarker.poseLandmarkerOptions.builder()
        .setBaseOptions(baseOptionsBuilder.build())
        .setMinPoseDetectionConfidence(minPoseDetectionConfidence)
        .setMinTrackingConfidence(minPoseTrackingConfidence)
        .setMinPosePresenceConfidence(minposePresenceConfidence)
        .setNumPoses(maxNumPoses)
        .setRunningMode(RunningMode.VIDEO)

val options = optionsBuilder.build()
poseLandmarker = poseLandmarker.createFromOptions(context, options)
    

val baseOptionsBuilder = BaseOptions.builder().setModelAssetPath(modelName)
val baseOptions = baseOptionBuilder.build()

val optionsBuilder = 
    poseLandmarker.poseLandmarkerOptions.builder()
        .setBaseOptions(baseOptionsBuilder.build())
        .setMinPoseDetectionConfidence(minPoseDetectionConfidence)
        .setMinTrackingConfidence(minPoseTrackingConfidence)
        .setMinPosePresenceConfidence(minposePresenceConfidence)
        .setNumPoses(maxNumPoses)
        .setResultListener(this::returnLivestreamResult)
        .setErrorListener(this::returnLivestreamError)
        .setRunningMode(RunningMode.LIVE_STREAM)

val options = optionsBuilder.build()
poseLandmarker = poseLandmarker.createFromOptions(context, options)
    

姿势特征点示例代码实现允许用户在处理模式之间切换。这种方法会使任务创建代码更加复杂，可能不适合您的用例。您可以在 PoseLandmarkerHelper.kt 文件的 setupPoseLandmarker() 函数中查看此代码。

配置选项

此任务具有以下 Android 应用的配置选项：

准备数据

Pose Markerer 适用于图片、视频文件和直播视频。该任务会处理数据输入预处理，包括大小调整、旋转和值归一化。

以下代码演示了如何移交数据进行处理。这些示例详细介绍了如何处理图片、视频文件和直播视频流中的数据。

import com.google.mediapipe.framework.image.BitmapImageBuilder
import com.google.mediapipe.framework.image.MPImage

// Convert the input Bitmap object to an MPImage object to run inference
val mpImage = BitmapImageBuilder(image).build()
    

import com.google.mediapipe.framework.image.BitmapImageBuilder
import com.google.mediapipe.framework.image.MPImage

val argb8888Frame =
    if (frame.config == Bitmap.Config.ARGB_8888) frame
    else frame.copy(Bitmap.Config.ARGB_8888, false)

// Convert the input Bitmap object to an MPImage object to run inference
val mpImage = BitmapImageBuilder(argb8888Frame).build()
    

import com.google.mediapipe.framework.image.BitmapImageBuilder
import com.google.mediapipe.framework.image.MPImage

// Convert the input Bitmap object to an MPImage object to run inference
val mpImage = BitmapImageBuilder(rotatedBitmap).build()
    

在姿势特征点示例代码中，数据准备在 PoseLandmarkerHelper.kt 文件中进行处理。

运行任务

根据您处理的数据类型，使用特定于该数据类型的 poseLandmarker.detect...() 方法。对单个图片使用 detect()，对视频文件中的帧使用 detectForVideo()，对视频流使用 detectAsync()。对视频串流执行检测时，请确保在单独的线程上运行检测，以免阻塞用户插入线程。

以下代码示例简单展示了如何在这些不同数据模式下运行姿势地标：

val result = poseLandmarker.detect(mpImage)
    

val timestampMs = i * inferenceIntervalMs

poseLandmarker.detectForVideo(mpImage, timestampMs)
    .let { detectionResult ->
        resultList.add(detectionResult)
    }
    

val mpImage = BitmapImageBuilder(rotatedBitmap).build()
val frameTime = SystemClock.uptimeMillis()

poseLandmarker.detectAsync(mpImage, frameTime)
    

请注意以下几点：

• 在视频模式或直播模式下运行时，您必须向姿势地标任务提供输入帧的时间戳。
• 在图片或视频模式下运行时，姿势地标任务会阻塞当前线程，直到其处理完输入图片或帧。为避免阻止用户干预，请在后台线程中执行处理。
• 在直播模式下运行时，姿势特征点任务会立即返回，并且不会阻塞当前线程。每当处理完输入帧时，它都会使用检测结果调用结果监听器。

在姿势地标示例代码中，detect、detectForVideo 和 detectAsync 函数在 PoseLandmarkerHelper.kt 文件中定义。

处理和显示结果

姿势特征点每次运行检测时都会返回一个 poseLandmarkerResult 对象。结果对象包含每个姿势地标的坐标。

下面显示了此任务的输出数据示例：

PoseLandmarkerResult:
  Landmarks:
    Landmark #0:
      x            : 0.638852
      y            : 0.671197
      z            : 0.129959
      visibility   : 0.9999997615814209
      presence     : 0.9999984502792358
    Landmark #1:
      x            : 0.634599
      y            : 0.536441
      z            : -0.06984
      visibility   : 0.999909
      presence     : 0.999958
    ... (33 landmarks per pose)
  WorldLandmarks:
    Landmark #0:
      x            : 0.067485
      y            : 0.031084
      z            : 0.055223
      visibility   : 0.9999997615814209
      presence     : 0.9999984502792358
    Landmark #1:
      x            : 0.063209
      y            : -0.00382
      z            : 0.020920
      visibility   : 0.999976
      presence     : 0.999998
    ... (33 world landmarks per pose)
  SegmentationMasks:
    ... (pictured below)

输出包含每个地标的归一化坐标 (Landmarks) 和世界坐标 (WorldLandmarks)。

输出包含以下标准化坐标 (Landmarks)：

• x 和 y：地标坐标，在 0.0 到 1.0 之间按图片宽度 (x) 和高度 (y) 进行标准化。

• z：地标深度，以臀部中点的深度为起点。值越小，特征点越靠近镜头。z 量级使用的尺度与 x 大致相同。

• visibility：地标在图片中可见的可能性。

输出包含以下世界坐标 (WorldLandmarks)：

• x、y 和 z：真实的三维坐标（以米为单位），臀部中点为原点。

• visibility：地标在图片中可见的可能性。

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

可选的分割掩码表示每个像素属于检测到的人物的可能性。下图是任务输出的分割掩码：

姿势特征点示例代码演示了如何显示任务返回的结果。如需了解详情，请参阅 OverlayView 类。