pose-landmarker-react-native

English | 简体中文

简介

pose-landmarker-react-native 是一个将 MediaPipe Pose Landmarker（任务 API）封装为 React Native 原生模块的库。当前主要支持 Android（通过 .task 模型与 MediaPipe Tasks for Android），提供图像、视频与实时流（LIVE_STREAM）三种推理模式。它负责加载模型、执行推理并将结果以 JS 对象或事件回调的形式暴露给上层应用。

主要用途：

• 在 React Native 应用中检测人体姿态关键点（2.5D 和世界坐标）。
• 支持静态图片、视频帧和低延迟的实时推理（需应用侧提供相机帧管道）。

特性

• 支持 IMAGE / VIDEO / LIVE_STREAM 三种运行模式
• 支持可配置的置信度与多人体检测
• 可通过本地文件或打包资源加载 MediaPipe .task 模型
• Android 原生实现（iOS 支持可在后续添加）

安装

将包添加到你的项目依赖：

# npm
npm install pose-landmarker-react-native

# 或 yarn
yarn add pose-landmarker-react-native

安装后重新编译原生应用以触发 autolinking：

cd android && ./gradlew assembleDebug

（此模块当前仅在 Android 上有实现；iOS 尚未提供）

Android 要点

• Min SDK: 21+
• 如果仅对静态图片进行检测，应用不需要相机权限。若要处理相机帧或实时流，需要在应用中集成 CameraX / Camera API 并将帧传入该模块。
• 模型文件：你可以在 init() 时通过 modelPath 提供一个设备上的绝对路径（如 /data/user/0/<your.app.id>/files/pose_landmarker_lite.task），或将 .task 文件打包到 android/src/main/assets/ 并使用 modelAssetPath 来引用它。

官方模型下载地址（示例）： https://storage.googleapis.com/mediapipe-models/pose_landmarker/

快速开始（示例代码）

import PoseLandmarker from "pose-landmarker-react-native";

// 初始化（IMAGE 模式示例）
await PoseLandmarker.init({
  modelPath: "/data/user/0/<your.app.id>/files/pose_landmarker_lite.task",
  runningMode: "IMAGE", // 'IMAGE' | 'VIDEO' | 'LIVE_STREAM'
  numPoses: 1,
  minPoseDetectionConfidence: 0.5,
  minPosePresenceConfidence: 0.5,
  minTrackingConfidence: 0.5,
  outputSegmentationMasks: false,
});

// 静态图片检测
const result = await PoseLandmarker.detect("/sdcard/Download/sample.jpg");
console.log(result.poses[0]?.landmarks);

// VIDEO 模式（按时间戳请求）
await PoseLandmarker.init({
  modelPath: "/data/.../pose_landmarker_lite.task",
  runningMode: "VIDEO",
});
const frameResult = await PoseLandmarker.detectForVideo(
  "/sdcard/frame.jpg",
  Date.now()
);

// LIVE_STREAM 模式（通过事件回调收到结果）
await PoseLandmarker.init({
  modelPath: "/data/.../pose_landmarker_lite.task",
  runningMode: "LIVE_STREAM",
});
const unsub = PoseLandmarker.onResult((res) =>
  console.log("stream result", res)
);
PoseLandmarker.onError((err) => console.warn("stream error", err));
await PoseLandmarker.detectAsync("/sdcard/frame.jpg", Date.now()); // 将帧入队列
unsub();

await PoseLandmarker.close();

结果数据结构（TypeScript 风格说明）：

interface Point2_5D {
  x: number;
  y: number;
  z: number;
  visibility?: number;
}
interface Point3D {
  x: number;
  y: number;
  z: number;
}
interface PoseResult {
  landmarks: Point2_5D[];
  worldLandmarks?: Point3D[];
}

interface DetectResult {
  poses: PoseResult[];
  timestamp?: number;
}

模型运行时下载示例（Expo FileSystem）

如果你想在运行时下载模型并传给 init()：

import * as FileSystem from "expo-file-system";

const MODEL_URL =
  "https://storage.googleapis.com/mediapipe-models/pose_landmarker/pose_landmarker_lite/float16/latest/pose_landmarker_lite.task";
const MODEL_PATH = FileSystem.documentDirectory + "pose_landmarker_lite.task";

async function ensureModel() {
  const info = await FileSystem.getInfoAsync(MODEL_PATH);
  if (!info.exists) {
    await FileSystem.downloadAsync(MODEL_URL, MODEL_PATH);
  }
  return MODEL_PATH;
}

// 使用示例
const path = await ensureModel();
await PoseLandmarker.init({ modelPath: path });

API 参考

• init(options): Promise
• detect(imagePath): Promise (IMAGE 模式)
• detectForVideo(imagePath, timestampMs): Promise (VIDEO 模式)
• detectForVideoByVideoUrl(videoPath, timestampMs): Promise (VIDEO 模式)
• detectAsync(imagePath, timestampMs): Promise (LIVE_STREAM 模式；结果通过事件回调)
• detectAsyncByVideoUrl(videoPath, timestampMs): Promise (LIVE_STREAM 模式；结果通过事件回调)
• onResult(listener): 返回 unsubscribe 函数
• onError(listener): 返回 unsubscribe 函数
• close(): Promise

选项说明（常用）：

• modelPath: 设备上 .task 模型的绝对路径
• modelAssetPath: 打包在资源里的模型路径（默认 'pose_landmarker_lite.task')
• runningMode: 'IMAGE' | 'VIDEO' | 'LIVE_STREAM'
• numPoses: 要检测的最大人体数（默认 1)
• minPoseDetectionConfidence, minPosePresenceConfidence, minTrackingConfidence: 数值阈值，范围 0 ~ 1
• outputSegmentationMasks: 是否输出分割掩码（布尔）

限制与提示

• 当前仅实现 Android；iOS 可通过集成 MediaPipe Tasks iOS SDK 在后续添加。
• LIVE_STREAM 模式需要应用侧负责相机帧采集与帧的传递（例如使用 CameraX）。本模块负责推理与事件分发。
• 对实时应用，注意控制帧率与队列长度以避免延迟累积。

故障排查（Troubleshooting）

• 模型加载失败：确认 modelPath 指向存在的 .task 文件，或将模型放入 android/src/main/assets/ 并使用 modelAssetPath。
• 权限与文件访问：在 Android 上，如果你从外部存储读取模型或图片，确认运行时权限已申请并允许访问。
• 性能：使用更轻量的模型（如 pose_landmarker_lite）或降低分辨率可提升推理速度。

English

Overview

pose-landmarker-react-native is a React Native bridge for MediaPipe's Pose Landmarker (Task API). It exposes Android native inference for detecting human pose landmarks in three running modes: IMAGE, VIDEO, and LIVE_STREAM. The module loads a .task model and performs inference, returning results to JavaScript either directly or via event callbacks.

Use cases:

• Pose keypoint detection (2.5D + world coordinates) in React Native apps.
• Static image, video frame, and low-latency streaming inference (camera pipeline provided by the app).

Features

• IMAGE / VIDEO / LIVE_STREAM running modes
• Configurable confidence thresholds and multi-person detection
• Load model from bundled asset or device file path
• Android native implementation (iOS to be added)

Installation

Install the package and rebuild native app for autolinking:

npm install pose-landmarker-react-native
# or
yarn add pose-landmarker-react-native

cd android && ./gradlew assembleDebug

Android notes

• Min SDK 21+
• Camera permission isn't required for static image detection. For camera frames/streaming, integrate your camera pipeline (e.g., CameraX) and feed frames to the module.
• Model file: supply modelPath (absolute device path) at init() or bundle the .task file in android/src/main/assets/ and use modelAssetPath.

Quick Start (JS examples)

See the Chinese section above for identical code examples demonstrating IMAGE, VIDEO, and LIVE_STREAM usage.

API reference

Same as the Chinese section; public methods include init, detect, detectForVideo, detectAsync, onResult, onError, and close.

Limitations & Tips

Same as the Chinese section. For realtime usage, keep an eye on frame enqueueing and model size to balance latency and accuracy.

Contributing

Contributions are welcome. Please open issues for bugs or feature requests. If you submit code, follow repository code style and include a short description of the change.

License

Check package.json for license information. If none is listed, assume MIT or contact the maintainer.

If you'd like, I can also:

• add a short example app under example/ showing CameraX -> module integration (Android),
• or add an API surface TypeScript typings file to the repo.

If you want any phrasing changed or more examples (e.g., how to parse landmarks into skeletal joints), tell me which parts to expand.