Tau-J/rtmlib

rtmlib – 輕量級姿態估計庫

是什麼 – rtmlib 是一個極小的 Python 套件，可讓你在不引入龐大的 OpenMMLab 堆疊（mmcv, mmpose, mmdet, …）的情況下，使用流行的 RTMPose 與 ViTPose 模型進行人體與動物姿態估計。它僅依賴 numpy、opencv-python、opencv-contrib-python 與 onnxruntime，並可選擇性地使用 OpenVINO、TensorRT 或支援 GPU 的 ONNX Runtime 以提升速度。

為何重要 – 姿態估計是 AR/VR、體育分析、機器人、動畫以及眾多 AI 驅動應用中的核心電腦視覺任務。透過去除龐大的 OpenMMLab 依賴，rtmlib 使得在輕量級環境（如簡單腳本、Web UI 或邊緣裝置）中嵌入姿態推論變得極為容易，同時仍能存取最前沿的模型。

快速開始（單張影像）

import cv2
from rtmlib import Wholebody, draw_skeleton

img = cv2.imread('demo.jpg')
whole = Wholebody(
    to_openpose=False,          # False = mmpose 風格骨架
    mode='balanced',            # 'performance' | 'lightweight' | 'balanced'
    backend='onnxruntime',
    device='cpu'
)
keypoints, scores = whole(img)
img = draw_skeleton(img, keypoints, scores, kpt_thr=0.5, to_openpose=False)
cv2.imshow('pose', img)
cv2.waitKey(0)

相同的 API 也可透過 PoseTracker 類用於攝影機或影片串流。

主要建構模組

層	類別（高階）	功能
檢測器	`YOLOX`, `RFDETR`, `RTMDet`	檢測影像中的人體（或任意 COCO 類別）。
姿態估計器	`RTMPose`, `ViTPose`	預測身體、手、全身或 3D 姿態的關鍵點座標。
解決方案	`Wholebody`, `Body`, `Hand`, `Animal`, `Custom`, `Wholebody3d`	將檢測器 + 姿態估計器組合成一個可呼叫物件，回傳關鍵點與置信度分數。
工具	`draw_skeleton`, `draw_bbox`	在原始影像上可視化結果。

所有這些均可透過 mode 快捷方式（performance, lightweight, balanced）或明確傳入 ONNX 模型 URL/路徑來實例化。

模型資料庫（自動下載）

檢測器 – YOLOX 變體（nano, tiny, s, m, l, x），在 HumanArt+COCO（檢測真實人類與卡通角色）或一般 COCO 上訓練。

姿態估計器 – 數十種 ONNX 檢查點：

RTMPose（t, s, m, l, x）：17關鍵點身體、21關鍵點手、26關鍵點 HALPE、133關鍵點全身，以及 3D 變體。
同等規模的 RTMO（單階段）版本。
ViTPose++（s, b, l）：17關鍵點與 133關鍵點身體，以及 25關鍵點微調模型。

若原始 OpenMMLab 下載伺服器無法存取，套件將自動回退至 HuggingFace 鏡像（huggingface.co/Tau-J/RTMPose）。

安裝方式

# 從 PyPI（推薦）
pip install rtmlib -i https://pypi.org/simple

# 或從原始碼安裝
git clone https://github.com/Tau-J/rtmlib.git && cd rtmlib
pip install -r requirements.txt
pip install -e .   # 可編輯安裝
# 可選 GPU 後端
pip install onnxruntime-gpu openvino

Web UI

一個最小的 Gradio 界面（webui.py）允許你上傳影像或從攝影機串流中取得影片，並立即看到姿態疊加效果：

pip install gradio   # 若尚未安裝
python webui.py

UI 在後台使用相同的 Wholebody/draw_skeleton 流程。

典型應用場景

在研究筆記本或小型應用中快速原型化基於姿態的功能。
安裝完整 OpenMMLab 堆疊不切實際的邊緣部署。
使用 Animal 解決方案與 OpenPose 風格骨架進行鳥類、貓、狗、馬等動物的姿態估計。
自訂流程 – 透過低階 YOLOX, RTMPose, ViTPose 類，接入任意 ONNX 檢測器或姿態模型。

授權與引用

倉儲遵循底層 OpenMMLab 模型的相同授權（請查看 LICENSE 檔案）。若在出版物中使用 rtmlib，請依照 README 中引用部分的說明，引用原始 RTMPose / ViTPose 論文與 rtmlib GitHub URL。

總結 – rtmlib 為前沿姿態估計模型提供了乾淨、依賴輕量的封裝，具備現成的高階 API、小型模型資料庫，以及可選的 GPU/加速器後端以實現快速推論。