LỊCH SỬ — KHÔNG CÒN LÀ LỊCH THỰC HIỆN (26/09/2026).
Nội dung dưới đây giữ nguyên để truy vết đề xuất cũ; không xác nhận đã làm, đã duyệt hoặc đã đạt cổng.
Dùng lộ trình hiện hành, bảng camera và ma trận y khoa.
Một chỉ số chỉ được thử sau GCA; GCB phải trước tích hợp. Mọi hoạt động có người cần GC riêng.
Các giờ, ngày, ngưỡng và đầu ra bên dưới không tự chuyển thành cam kết hoặc tiêu chí được duyệt.

Tuần: W5/23 | : Sprint C2/4
Vai trò: NCS2 (Đỗ Đoàn Anh Tuấn, 10A6 PTTH Xuân Đỉnh)
Effort: 6h
Dependency: CAM-008
Checkpoint cuối ngày: Module metric_calculator.py hoàn thành các hàm hình học tính góc và logic FSM phát hiện pha đứng dậy / ngồi xuống.

Task: Hiện thực hoá thuật toán đo TUG trên Python (Phần 1)

ID: CAM-009-P1
Phân loại: 🔄 Hỗn hợp
Effort: 6 giờ

Mô tả

Khởi tạo mã nguồn module metric_calculator.py trong thư mục backend/movement-observation/src/. Xây dựng các hàm toán học tính góc khớp hông, gối từ toạ độ 3D chuẩn hoá của BlazePose. Hiện thực hoá lớp TUGTracker quản lý trạng thái FSM cho pha 1 (Ngồi trên ghế) và pha 2 (Đứng dậy), tính toán mốc thời gian bắt đầu rời ghế. Kiểm thử với chuỗi dữ liệu landmark mẫu.

File Tham chiếu (Input)

  • docs/research/designs/NCS2_tug_algorithm_design.md
  • backend/movement-observation/config/thresholds.yaml

File Kết quả (Output)

  • backend/movement-observation/src/metric_calculator.py
  • backend/movement-observation/tests/test_tug_fsm.py

DoD (Definition of Done)

  • [ ] Cài đặt hàm calculate_angle_3d(p1, p2, p3) tính góc hình học chính xác với sai số <0.01 rad.
  • [ ] Lớp TUGTracker phát hiện chính xác thời điểm người dùng bắt đầu đứng dậy từ chuỗi frame liên tục.
  • [ ] Unit test test_tug_fsm.py PASS trên dữ liệu giả lập và dữ liệu mẫu thực tế ban đầu.
  • [ ] Tuân thủ an toàn: Code chỉ xử lý số liệu toạ độ cơ học, không xuất kết luận bệnh lý.

Hướng dẫn triển khai

  1. Viết module toán học vector tính góc giữa các vector đùi (hip-knee) và cẳng chân (knee-ankle).
  2. Xây dựng bộ lọc trung bình trượt (moving average filter, cửa sổ 5 frame) để khử nhiễu rung lắc landmark.
  3. Tạo cấu trúc trạng thái Enum: SITTING, STANDING_UP, WALKING, TURNING, SITTING_DOWN, COMPLETED.
  4. Viết unit test cho các hàm tính góc và chuyển trạng thái cơ bản bằng pytest.

Rủi ro & Biện pháp giảm thiểu

  • Rủi ro: Tọa độ keypoints bị rung lắc đột ngột làm FSM nhảy sai trạng thái.
  • Biện pháp: Áp dụng debounce time tối thiểu 0.2s trước khi xác nhận chuyển pha hợp lệ.
  • Rủi ro: Thiếu dữ liệu mẫu đa dạng để kiểm thử FSM.
  • Biện pháp: Tự quay 3 video mẫu cử động bình thường và chậm chạp của thành viên nhóm để làm test vector.

Phân định vai trò

  • NCS2 (Đỗ Đoàn Anh Tuấn): Lập trình module Python, thuật toán hình học và viết test case FSM.
  • NCS1 (Võ Trần Gia Hiếu): Hỗ trợ chuẩn hoá coding style và thiết lập môi trường test pytest.