Tau-J/rtmlib

rtmlib – 가벼운 포즈 추정 라이브러리

무엇인가요 – rtmlib는 인체 및 동물 포즈 추정을 위해 인기 있는 RTMPose 및 ViTPose 모델을 사용할 수 있게 해주는 매우 작고 가벼운 Python 패키지입니다. 무거운 OpenMMLab 스택(mmcv, mmpose, mmdet, …)을 포함하지 않습니다. numpy, opencv-python, opencv-contrib-python, onnxruntime만 의존하며, 필요에 따라 OpenVINO, TensorRT 또는 GPU 지원 ONNX Runtime을 사용하여 성능을 향상시킬 수 있습니다.

왜 중요한가요 – 포즈 추정은 AR/VR, 스포츠 분석, 로봇공학, 애니메이션 및 다양한 AI 기반 앱에서 핵심적인 컴퓨터 비전 작업입니다. 큰 OpenMMLab 의존성을 제거함으로써 rtmlib는 가벼운 환경(예: 간단한 스크립트, 웹 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 (1단계) 버전.
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

웹 UI

최소한의 Gradio 인터페이스(webui.py)를 통해 이미지 업로드 또는 웹캠 스트림을 받아 즉시 포즈 오버레이를 확인할 수 있습니다:

pip install gradio   # 이미 설치되어 있지 않은 경우
python webui.py

UI는 내부적으로 동일한 Wholebody/draw_skeleton 파이프라인을 사용합니다.

일반적인 사용 사례

연구 노트북이나 소규모 앱에서 포즈 기반 기능을 빠르게 프로토타이핑.
전체 OpenMMLab 스택 설치가 불가능한 엣지 디바이스에 배포.
Animal 솔루션과 OpenPose 스타일 스켈레톤을 사용하여 새, 고양이, 개, 말 등 동물의 포즈 추정.
커스텀 파이프라인 – 저수준 YOLOX, RTMPose, ViTPose 클래스를 통해 원하는 ONNX 검출기나 포즈 모델을 연결.

라이선스 및 인용

리포지토리는 하위 OpenMMLab 모델과 동일한 라이선스를 따릅니다 (LICENSE 파일 확인). rtmlib를 논문에 사용할 경우, 원본 RTMPose / ViTPose 논문과 rtmlib GitHub URL을 README의 인용 섹션에 따라 인용해 주세요.

결론 – rtmlib는 최신 포즈 추정 모델을 깔끔하고 의존성 최소화된 래퍼로 제공하며, 준비된 고수준 API, 작은 모델 자료관, 그리고 빠른 추론을 위한 선택적 GPU/가속기 백엔드를 갖추고 있습니다.