pipetrt 0.1.2

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