| # Implementation Plan |
|
|
| ## Trang Thai Hien Tai |
|
|
| Du an da chuyen tu prototype Taekwondo/Streamlit sang ung dung Reflex phan tich bai tap hit dat. Luong xu ly production hien tai nam trong cac module `push_up/*` va `reflex_frontend/*`. |
|
|
| ## Kien Truc Chinh |
|
|
| ```text |
| Reflex UI |
| -> upload video hoc vien |
| -> push_up.analysis_service.analyze_pushup() |
| -> VideoProcessor + MediaPipe Pose |
| -> PushUpEvaluator |
| -> PushUpRuleEngine |
| -> frame artifacts + rule-based arrows |
| -> optional NVIDIA VLM feedback |
| -> Reflex result cards |
| ``` |
|
|
| ## Module Chinh |
|
|
| - `reflex_frontend/state.py`: quan ly upload, tien trinh xu ly, state ket qua. |
| - `reflex_frontend/ui.py`: giao dien trang chu, danh sach bai tap, trang phan tich hit dat, card ket qua tung rep. |
| - `push_up/processor.py`: doc video, phat hien huong nguoi tap, flip neu can, trich xuat landmark theo frame. |
| - `push_up/engine.py`: boc MediaPipe Pose, tinh cac chi so kinematics nhu elbow angle, hip angle, body line angle, depth signal. |
| - `push_up/evaluator.py`: segment rep, can chinh voi template bang DTW, ket hop diem rule score va DTW score. |
| - `push_up/rules.py`: phat hien loi ky thuat bang nguong deterministic. |
| - `push_up/analysis_service.py`: orchestration cua toan bo flow, tao payload cho UI, luu artifact, ve arrow. |
| - `push_up/feedback_graph.py`: goi text LLM/VLM qua NVIDIA OpenAI-compatible API va validate JSON feedback. |
| - `scripts/run_pushup_eval_tests.py`: batch test tat ca video trong `data/tests` va xuat file JSON tong hop. |
|
|
| ## Luong Phan Tich Video |
|
|
| 1. UI luu video upload vao thu muc tam cua Reflex. |
| 2. `prepare_template_cache()` dam bao video mau da duoc xu ly va cache landmark tai `data/processed/pushup_template.pkl`. |
| 3. `VideoProcessor` doc video hoc vien, lay mau frame, auto flip neu nguoi tap nam nguoc huong template. |
| 4. `PoseEngine` trich xuat 33 landmark pose va tinh kinematics. |
| 5. `PushUpEvaluator` segment rep dua tren depth signal va elbow angle. |
| 6. Moi rep duoc so sanh voi golden template bang DTW va pose similarity. |
| 7. `PushUpRuleEngine` chay rule-based checks: |
| - `not_deep_enough` |
| - `hip_sag` |
| - `body_not_straight` |
| - `head_misaligned` |
| - `hip_pike` |
| 8. `analysis_service` tao card ket qua tung rep, main error, feedback rule-based, va summary. |
| 9. Khi `save_artifacts=True`, app luu frame hoc vien/mau va ve arrow vao frame hoc vien. |
| 10. Neu rep co rule-based error va co `NVIDIA_API_KEY`, VLM duoc goi de sinh feedback chu cho rep loi. |
|
|
| ## Quyet Dinh Thiet Ke |
|
|
| - Rule engine la nguon quyet dinh loi chinh, diem rule, feedback rule-based va arrow target. |
| - VLM khong duoc dung de quyet dinh toa do arrow vi de tra sai vi tri tren nen anh. |
| - VLM chi sinh feedback ngan bang tieng Viet dua tren anh hoc vien, anh mau va rule context. |
| - Arrow label dung tieng Viet co dau va duoc render bang Pillow de tranh loi Unicode cua OpenCV. |
| - Ket qua test batch mac dinh tat VLM de lap lai, nhanh hon va khong ton API. |
|
|
| ## Viec Can Lam Tiep |
|
|
| - Them expected assertions vao batch test, vi du `hv01_mong_cao` phai co `hip_pike`. |
| - Luu anh artifact cho test run co chon loc thay vi tat ca rep neu can giam dung luong. |
| - Tach `llm_*` field thanh `vlm_*` trong payload/UI de ten bien khop voi y nghia hien tai. |
| - Them exercise registry neu mo rong sang bai tap khac. |
|
|
