単眼カメラによるマーカレス上肢動作計測システム「UpperLimbs」

Last updated at 2025-06-26Posted at 2025-06-26

UpperLimbs - 3次元上肢動作計測システム

標準的なWebカメラとGoogleのMediaPipeフレームワークを使用して、上肢と手の動きをリアルタイムで3DトラッキングするためのPythonモジュールです。

このツールは、姿勢と手のランドマークをキャプチャし、統一された座標系に変換します。そして、生データへのアクセスや、骨格のライブ3Dビジュアライゼーションを生成するためのシンプルなメソッドを提供します。

デモ

特徴

リアルタイム性能: Webカメラや動画ファイルから上肢と手のランドマークを直接トラッキングします。
統一された3D座標: 姿勢と手のランドマークを、使いやすい単一のデータ構造に統合します。
肩中心の原点: 座標系の原点を両肩の中心に移動させることで、安定したシステムを構築します。
ライブ3Dビジュアライゼーション: 骨格を3Dで動的にプロットする組み込みメソッドが含まれています。
シンプルなAPI: データ分析、インタラクティブアート、理学療法の研究など、他のアプリケーションに簡単に統合できるように設計されています。

仕組み

このモジュールは、最終的な3D座標を生成するために、以下の単純な処理パイプラインに従います。

フレームのキャプチャ: Webカメラなどのビデオソースから画像をキャプチャします。
MediaPipeによる処理: 画像をMediaPipeのPoseモデルとHandsモデルに入力し、各部位の3Dワールドランドマークを検出・返します。
座標変換:
- 座標系の原点を、MediaPipeのデフォルトである腰の中心から両肩の中心点に移動させます。これにより、上半身の動きに対してより安定した原点が得られます。
- 手のランドマークは、それぞれ独自のローカル座標系を持っていますが、これらを姿勢モデルの手首のランドマークに位置合わせするように平行移動させます。
データの結合: 変換された姿勢と手のランドマークを、48点で構成される単一のリストに結合します。
出力: この最終的な座標リストは、.get_coordinates()で取得したり、.visualize()で視覚化したりすることができます。

インストール

競合を避けるため、仮想環境を使用することを強くお勧めします。

リポジトリをクローンする

git clone https://github.com/sthasmn/UpperLimbs.git
cd UpperLimbs

仮想環境の作成と有効化（オプションですが推奨）

# Mac/Linuxの場合
python3 -m venv venv
source venv/bin/activate

# Windowsの場合
python -m venv venv
.\venv\Scripts\activate

パッケージのインストール
このコマンドで、opencv、mediapipe、matplotlibなどの必要な依存関係もすべてインストールされます。
```
pip install .
```
ソースコードを修正する予定がある場合は、「編集可能モード」でインストールしてください。
```
pip install -e .
```

使い方

デモの実行

付属のmain.pyスクリプトは、Webカメラを使用した簡単なデモを提供します。

python main.py

Webカメラの映像に2Dランドマークが描画されたプレビューウィンドウが表示されます。
**v**キーを押すと、ライブ3Dビジュアライゼーションのウィンドウが開閉します。
**q**キーを押すと、アプリケーションが終了します。

プログラムでの使用

upperlimbsモジュールを独自のプロジェクトに統合するのは簡単です。

import cv2
import matplotlib.pyplot as plt
import upperlimbs

# 1. UpperLimbsクラスを初期化
ul = upperlimbs.UpperLimbs()

# 2. ビデオキャプチャを開始（0はWebカメラ、動画パスはビデオファイル用）
cap = cv2.VideoCapture(0)

while cap.isOpened():
    success, image = cap.read()
    if not success:
        break

    # 3. フレームを処理
    ul.process_frame(image)

    # 4. 座標データを取得
    coordinates = ul.get_coordinates()
    if coordinates:
        # 'coordinates'は48点のリストです。「出力される座標系」セクションを参照してください。
        # 正しいインデックスで左手首と右手首の座標を取得します。
        left_wrist_coords = coordinates[4]
        right_wrist_coords = coordinates[5]
        print(f"Right Wrist [X, Y, Z]: {right_wrist_coords}")

    # 5. (オプション) ライブ3Dプロットを表示
    ul.visualize()
    
    # 6. (オプション) 2Dプレビューを表示
    annotated_image = ul.draw_landmarks(image.copy())
    cv2.imshow("My Preview", annotated_image)

    # ESCキーで終了
    if cv2.waitKey(5) & 0xFF == 27:
        break

# 7. リソースを解放
cap.release()
cv2.destroyAllWindows()
ul.close()

APIリファレンス

主なインターフェースはUpperLimbsクラスです。

ul = upperlimbs.UpperLimbs(min_detection_confidence=0.5, min_tracking_confidence=0.5)
: プロセッサのインスタンスを初期化します。オプションでMediaPipeモデルの信頼度の閾値を調整できます。

coordinates = ul.process_frame(image)
: 単一の画像フレーム（BGR形式のNumPy配列）を処理し、48点の3D座標のリストを返します。

coordinates = ul.get_coordinates()
: 最後に正常に処理されたフレームの座標リストを返します。ランドマークが見つからなかった場合はNoneを返します。

ul.visualize()
: 最後に処理された座標に基づいて、骨格のMatplotlib 3Dプロットウィンドウを開くか更新します。

annotated_image = ul.draw_landmarks(image)
: MediaPipeによって検出された2Dの姿勢と手のランドマークを指定された画像に描画し、その画像を返します。

ul.close()
: MediaPipeモデルのリソースを解放します。処理が終了したら呼び出す必要があります。

出力される座標系

.get_coordinates()メソッドは、48点を含む単一のリストを返します。各点は[X, Y, Z]座標のサブリストです。

原点(0, 0, 0)は両肩の中心点です。単位は概ねメートル法ですが、検出された人物の姿勢に基づいてスケーリングされます。

+X はあなたの右方向です
+Y は上方向です
+Z は手前方向（画面から出てくる方向）です

48点の順序は以下の通りです：

インデックス範囲	部位	点の数	詳細
`0 - 5`	姿勢（胴体/腕）	6	上半身の主要な関節。詳細は下記参照。
`6 - 26`	左手	21	左手のすべてのランドマーク。左手首（インデックス4）に接続されます。
`27 - 47`	右手	21	右手のすべてのランドマーク。右手首（インデックス5）に接続されます。

姿勢ランドマーク（インデックス0-5）の詳細：

インデックス 0: 左肩
インデックス 1: 右肩
インデックス 2: 左肘
インデックス 3: 右肘
インデックス 4: 左手首
インデックス 5: 右手首

手のランドマーク（インデックス6-26および27-47）の詳細：

各手の21個のランドマークは、標準のMediaPipe Hand Landmark Modelに従います。これらの点の視覚的な図については、公式のMediaPipe Handsドキュメントを参照してください。

引用

このソフトウェアを研究や出版物で使用する場合は、以下の論文を引用していただけますと幸いです。

S. Shrestha, H. Takami, Y. Honda and M. Irie, "Research on Measurement System of Upper Limb by Using Single Monocular Web Camera and Inference AI," 2024 17th International Convention on Rehabilitation Engineering and Assistive Technology (i-CREATe), 2024, pp. 1-4, doi: 10.1109/i-CREATe62067.2024.10776555.

便宜上、以下のBibTeXエントリを使用できます。

@INPROCEEDINGS{10776555,
  author={Shrestha, Suman and Takami, Hibiki and Honda, Yuichiro and Irie, Mitsuru},
  booktitle={2024 17th International Convention on Rehabilitation Engineering and Assistive Technology (i-CREATe)}, 
  title={Research on Measurement System of Upper Limb by Using Single Monocular Web Camera and Inference AI}, 
  year={2024},
  volume={},
  number={},
  pages={1-4},
  keywords={Training;Visualization;Accuracy;Tracking;Low-pass filters;Cameras;Motion capture;Real-time systems;Artificial intelligence;Time-domain analysis},
  doi={10.1109/i-CREATe62067.2024.10776555}
}

依存関係

このプロジェクトの依存関係は、pip install .を実行すると自動的にインストールされます。

opencv-python
mediapipe
numpy
matplotlib

You get articles that match your needs
You can efficiently read back useful information
You can use dark theme

What you can do with signing up