Hand Retarget System

Hệ thống retarget cử động bàn tay theo thời gian thực: MediaPipe + DepthAI/Optical Flow ở backend, Three.js ở frontend. README này chứa toàn bộ hướng dẫn chạy và yêu cầu kỹ thuật cần thiết.

---

• Tổng quan & luồng xử lý
• Yêu cầu kỹ thuật
• Thiết lập môi trường
• Chạy hệ thống
• Cấu hình & tips
• Cấu trúc thư mục

---

Tổng quan & luồng xử lý

Pipeline xử lý mỗi khung hình (30 FPS mục tiêu):

[Webcam/OAK] → MediaPipe Hand Landmarker → Landmark packets
                              ↓
                      Pose Solver (Kabsch + finger quats)
                              ↓
                  Optical Flow (Lucas–Kanade per landmark)
                              ↓
                WebSocket stream → Three.js Skeleton Retarget

Thành phần chính

1. Backend (Python)

   • Ghi hình camera (webcam/OAK) tại backend/capture.py.
   • MediaPipe Hand Landmarker để lấy 21 điểm và handedness.
   • PoseSolver tính quaternion gốc bằng Kabsch + giới hạn khớp ngón.
   • Lucas–Kanade optical flow để theo dõi chuyển động.
   • WebSocket server (api.py) phát dữ liệu JSON theo thời gian thực.

2. Frontend (Three.js + Vite)

   • Kết nối WebSocket, nhận landmarks/quaternions/motion.
   • Ánh xạ vào skeleton GLB, cho phép chỉnh JSON mapping, hiển thị video.

3. Shared data

   • hand_mapping.json: ánh xạ landmarks → bones.
   • data/: nơi lưu kết quả thử nghiệm (tuỳ chọn).

Yêu cầu kỹ thuật

Phần cứng

• PC/Laptop với CPU đa nhân; GPU rời giúp Three.js hiển thị mượt hơn.
• Webcam ≥ 720p @ 30 FPS (bắt buộc).
• Tùy chọn: camera OAK/DepthAI (USB 3.0) nếu muốn chạy palm detection on-device.

Phần mềm

• Windows, macOS hoặc Linux (đã thử trên Windows 11).
• Python >= 3.10 cùng pip và quyền cài đặt gói hệ thống.
• Node.js LTS (khuyến nghị 18.x hoặc 20.x) + npm (đi kèm Node).
• Git (để clone repository nếu cần).
• Trình duyệt hỗ trợ WebGL 2 (Chrome, Edge, Firefox, v.v.).

Thiết lập môi trường

1. Clone mã nguồn

git clone <repo-url>
cd handmapping

2. Backend (Python)

cd backend
python -m venv .venv             # tùy chọn nhưng khuyến nghị
.venv\Scripts\activate           # PowerShell/CMD trên Windows
pip install --upgrade pip
pip install -r requirements.txt

Lưu ý DepthAI: cắm thiết bị OAK trước khi chạy lần đầu để quá trình cài depthai tải firmware cần thiết.

3. Frontend (Node.js)

cd frontend
npm install

Vite dùng cấu hình mặc định (port 5173). Mọi assets ở frontend/public hoặc import trực tiếp trong app.js.

Chạy hệ thống

1. Khởi động backend

cd backend
python api.py --host 0.0.0.0 --port 8765   # tham số tùy chọn

• WebSocket: ws://<host>:<port>/ws
• Health check: http://<host>:<port>/health
• Log sẽ cho biết khi webcam mở thành công và khi client kết nối.

2. Khởi động frontend

cd frontend
npm run dev

• Truy cập http://localhost:5173 (hoặc URL Vite hiển thị) bằng trình duyệt.
• Kiểm tra tab Console nếu không thấy dữ liệu WebSocket.

3. Trình tự đề xuất

1. Mở trang frontend để sẵn sàng nhận dữ liệu.
2. Nhấn "Connect" (nếu UI yêu cầu) hoặc chờ kết nối tự động tới ws://localhost:8765/ws.
3. Khi bàn tay xuất hiện ổn định, nhấn nút thiết lập Bind Pose để khóa tư thế gốc.
4. Dùng UI mapping để gán landmarks → bones, lưu lại để backend tải hand_mapping.json mới.

Cấu hình & Tips

• Chọn webcam khác: chỉnh chỉ số camera tại backend/capture.py (mặc định 0). Khởi động lại backend sau khi sửa.
• Mapping: file hand_mapping.json ở thư mục gốc. Bạn có thể chỉnh thủ công hoặc dùng UI kéo-thả ở frontend rồi bấm "Save" để ghi đè.
• Tùy biến host/port: truyền --host và --port cho api.py (thông qua argparse ở cuối file) hoặc sửa mặc định trong HandTrackingServer.
• Chế độ debug reload: khởi chạy HandTrackingServer(debug=True) nếu muốn tự động reload backend khi file Python thay đổi.
• DepthAI/OAK: khi thiết bị được phát hiện, capture.py ưu tiên stream từ OAK; nếu không, hệ thống quay lại webcam tiêu chuẩn.
• Băng thông WebSocket: dữ liệu ~2–5 KB/frame. Đảm bảo cùng LAN hoặc localhost để tránh độ trễ.

Xử lý sự cố thường gặp

1. Không mở được webcam: kiểm tra thiết bị khác đang sử dụng camera, hoặc dùng capture.open(index=1) với camera phụ.
2. Frontend không nhận dữ liệu: xác minh backend in "Client connected" và kiểm tra console trình duyệt xem có lỗi CORS / WebSocket.
3. FPS thấp: giảm độ phân giải trong capture.py hoặc tắt Optical Flow (flow.py) nếu chỉ cần landmarks.
4. Sai hướng mô hình: sử dụng các tùy chọn xoay trong frontend/app.js (phần load3DModel) để tinh chỉnh hướng GLB.

Cấu trúc thư mục

handmapping/
├─ backend/
│  ├─ api.py             # HTTP/WebSocket server + tracking loop
│  ├─ capture.py         # Webcam/OAK capture wrapper
│  ├─ mp_hands.py        # MediaPipe Tasks wrapper
│  ├─ pose_solver.py     # Kabsch + quaternion utilities
│  ├─ flow.py            # Lucas–Kanade optical flow
│  └─ requirements.txt   # Backend dependencies
├─ frontend/
│  ├─ app.js             # Three.js scene & mapping UI
│  ├─ index.html         # Entry point served by Vite
│  └─ package.json       # Frontend dependencies/scripts
├─ data/                 # Mẫu dữ liệu thử nghiệm (tùy chọn)
├─ hand_mapping.json     # Ánh xạ landmarks ↔ bones
└─ README.md             # Tài liệu hướng dẫn này

Chúc bạn retarget vui vẻ!