MediaPipe-inspired TensorRT hand landmark library for NVIDIA GPUs

MediaPipeのハンドトラッキング構成を参考に開発した、NVIDIA GPU向けTensorRT手骨格検出ライブラリです。

このプロジェクトは、MediaPipeのようなシンプルな使い方で、TensorRTによる高速な手の検出・21点ランドマーク推論を利用できるようにすることを目的としています。

PipeTRTは、自分自身の開発だけではなく、将来同じようにJetsonやNVIDIA GPUを用いたエッジAI開発を行う学生や開発者が、手軽に利用できるライブラリを目指しています。

デモンストレーション映像

リリース 0.1.2

PipeTRT v0.1.2では、TensorRTのバージョン差によるEngine生成処理の互換性を改善しました。

TensorRTのメジャーバージョンを判定し、使用しているTensorRTに応じてEngine生成処理を切り替えます。

これにより、従来のWindows + NVIDIA GeForce RTX環境に加えて、NVIDIA Jetson Xavier NX上のTensorRT 8.5環境でも動作を確認しました。

現在はPython 3.8以上、3.12未満の環境を対象としています。

カメラ映像や画像から手を検出し、21点のHand Landmarkを取得できます。

内部では以下の処理を行います。

1. Palm Detection
2. ROI生成・変換
3. Hand Landmark推論
4. ROI Tracking
5. 21点ランドマークの出力

Palm DetectionとHand Landmarkの推論にはNVIDIA TensorRTを使用しています。

Note

v0.1.xは初期リリースです。 APIや内部仕様は今後変更される可能性があります。

v0.1.2の主な変更点

• TensorRTのメジャーバージョン判定を追加
• TensorRT 8系でのEngine生成に対応
• TensorRT 8系でEXPLICIT_BATCHを使用する処理を追加
• TensorRTのバージョンに応じたFP16 Engine生成処理を追加
• NVIDIA Jetson Xavier NXでの動作確認
• TensorRT 8.5.2.2での動作確認
• Python 3.8環境での動作確認

機能

v0.1.2では以下の機能を利用できます。

• TensorRTによるPalm Detection
• 手領域（ROI）の生成
• 回転を考慮したROI変換
• TensorRTによるHand Landmark推論
• 21点のHand Landmark取得
• Landmarkを利用したROI Tracking
• Palm DetectionとTrackingの自動切り替え
• MediaPipe風のHandLandmarker API
• 静止画・リアルタイムカメラ映像への対応
• 各処理の推論時間・処理時間の取得
• Python 3.8以上への対応
• TensorRTのバージョン差を考慮したEngine生成

動作確認環境

現在、以下の環境で動作確認しています。

Windows

• Windows
• Python 3.8 / 3.11
• NVIDIA GeForce RTX 3070
• NVIDIA CUDA
• NVIDIA TensorRT

NVIDIA Jetson

以下の環境で動作を確認しています。

• NVIDIA Jetson Xavier NX 8GB
• JetPack 5.1.2
• Python 3.8.10
• CUDA 11.4
• TensorRT 8.5.2.2

Note

現在Jetson環境については、Jetson Xavier NX + JetPack 5.1.2で動作確認を行っています。 すべてのJetsonシリーズおよびJetPackバージョンでの動作を保証するものではありません。

対応Pythonバージョン

Python >= 3.8, < 3.12

現在、Python 3.8およびPython 3.11で動作確認を行っています。

インストール

PipeTRTはPyPIからインストールできます。

pip install pipetrt

対応Pythonバージョンは以下です。

Python >= 3.8, < 3.12

Note

PipeTRTはNVIDIA GPUおよびTensorRTを使用します。 CUDA・TensorRTなどの対応状況は、使用する環境によって異なる場合があります。

GitHubからインストール

GitHub上のソースコードからインストールする場合は、リポジトリをCloneします。

git clone https://github.com/Konoa-1025/PipeTRT.git
cd PipeTRT
pip install .

開発用インストール

PipeTRT自体の開発やコードの変更を行う場合は、Editable Installを利用できます。

git clone https://github.com/Konoa-1025/PipeTRT.git
cd PipeTRT
pip install -e .

使い方

基本

import pipetrt

hands = pipetrt.HandLandmarker()

result = hands.detect(frame)

print(result.hand_landmarks)

hands.close()

detect()にOpenCVの画像（NumPy配列）を渡すことで、手のランドマークを取得できます。

OpenCVでリアルタイム検出

import cv2
import pipetrt


hands = pipetrt.HandLandmarker()

cap = cv2.VideoCapture(0)

while True:
    ret, frame = cap.read()

    if not ret:
        break

    result = hands.detect(frame)

    if result.hand_landmarks is not None:
        for landmark in result.hand_landmarks:
            x = int(landmark[0])
            y = int(landmark[1])

            cv2.circle(
                frame,
                (x, y),
                4,
                (0, 255, 0),
                -1
            )

    cv2.imshow("PipeTRT", frame)

    if cv2.waitKey(1) & 0xFF == ord("q"):
        break

cap.release()
hands.close()
cv2.destroyAllWindows()

取得できるデータ

HandLandmarker.detect()はHandLandmarkerResultを返します。

現在、以下のデータを取得できます。

• hand_landmarks
• palm_result
• roi
• roi_image
• timings

hand_landmarks

21点のHand Landmarkを取得できます。

result.hand_landmarks

timings

各処理にかかった時間を取得できます。

print(result.timings)

Palm Detection、ROI変換、Hand Landmark推論などの処理時間を確認できます。

処理の流れ

Input Frame
     |
     v
Palm Detection
     |
     v
ROI Generation
     |
     v
Hand Landmark
     |
     v
ROI Tracking
     |
     v
21 Hand Landmarks

注意

• 本プロジェクトはMediaPipeにインスパイアされていますが、Google公式のMediaPipeプロジェクトとは独立した非公式プロジェクトです。
• TensorRTを利用していますが、NVIDIA公式のプロジェクトではありません。
• GitHub上などで公開されている情報・データを調査し、利用条件を確認した上で開発しています。使用・参考にしたものについてはreference.mdに記載しています。
• このライブラリでは画像処理をローカル環境内で実行します。PipeTRT自体が画像を第三者へ送信したり、外部サーバーへ保存したりする機能はありません。
• 使用しているデータ等について権利者から案内・通告があった場合、プログラムの修正や該当リリースの公開停止を行う場合があります。
• Pythonのバージョンが対応範囲内であっても、CUDA・TensorRT・NVIDIA GPUなどの環境によって動作状況が異なる場合があります。
• Jetsonについては現在Jetson Xavier NX + JetPack 5.1.2環境で動作確認を行っており、その他のJetsonシリーズ・JetPackバージョンについては検証中です。
• このプロジェクトでは学習を目的としてAIを開発補助に使用しています。生成された内容をそのまま公開するのではなく、内容の確認・理解・独自の実装やリファクタリングを行った上でリリースしています。そのため、開発版とリリース版には時間差が生じる場合があります。最新の開発状況についてはdevブランチを確認してください。

License

Apache License 2.0