| --- |
| title: GAIT_API |
| emoji: 🚶 |
| colorFrom: blue |
| colorTo: indigo |
| sdk: docker |
| app_file: app.py |
| pinned: false |
| --- |
| |
| # Gait Analysis API |
|
|
| Clinical gait analysis service built with FastAPI, OpenCV, and MediaPipe Pose. |
|
|
| It processes a front-view walking video and returns: |
|
|
| - extracted gait biomarkers |
| - rule-based clinical interpretation |
| - overall gait stability score |
| - annotated skeleton video |
| - clinical dashboard plot |
|
|
| The notebook prototype is kept in [gait.ipynb](<gait.ipynb>), and the production API implementation is in [app.py](app.py). |
|
|
| ## Table of contents |
|
|
| - Overview |
| - Project structure |
| - How it works |
| - API reference |
| - Local development |
| - Docker usage |
| - Storage cleanup strategy |
| - Hugging Face Spaces deployment |
| - GitHub Actions auto-deploy |
| - Troubleshooting |
|
|
| ## Overview |
|
|
| This API is designed for single-video gait assessment. |
|
|
| Core stack: |
|
|
| - FastAPI for REST endpoints |
| - MediaPipe Pose for landmark extraction |
| - OpenCV for video I/O and skeleton overlay |
| - NumPy/SciPy for signal processing and feature extraction |
| - Matplotlib for biomarker visualizations |
|
|
| Dependencies are listed in [requirements.txt](requirements.txt). |
|
|
| ## Project structure |
|
|
| - [app.py](app.py): Main API + gait analysis pipeline |
| - [requirements.txt](requirements.txt): Python dependencies |
| - [Dockerfile](Dockerfile): Container build (HF Spaces compatible) |
| - [scripts/start.sh](scripts/start.sh): Container startup + background cleanup loop |
| - [scripts/cleanup_runs.py](scripts/cleanup_runs.py): Deletes old generated files |
| - [.github/workflows/deploy-hf-space.yml](.github/workflows/deploy-hf-space.yml): Auto-sync GitHub repo to HF Space |
| - [gait.ipynb](<gait.ipynb>): Original notebook source logic |
|
|
| ## How it works |
|
|
| High-level flow: |
|
|
| 1. Upload `video` + `gender` |
| 2. Extract pose landmarks for each frame |
| 3. Validate video (person detected, front-view check) |
| 4. Build temporal signals (ankles, feet, arm swing, hip center) |
| 5. Smooth + detrend + detect peaks |
| 6. Compute biomarkers (`stride_variability`, `cadence`, `symmetry_ratio`, arm metrics) |
| 7. Create clinical interpretation text |
| 8. Compute weighted gait stability score |
| 9. Generate dashboard image + annotated video |
| 10. Return JSON payload |
|
|
| Main endpoints are declared in [app.py](app.py#L560-L785). |
|
|
| ## API reference |
|
|
| ### `GET /` |
|
|
| Basic API metadata and endpoint hints. |
|
|
| ### `POST /analyze` |
|
|
| Accepts multipart form-data: |
|
|
| - `video`: gait video (`mp4/mov/avi/...`) |
| - `gender`: `male` or `female` |
|
|
| Returns analysis JSON with base64-embedded files (`annotated_video`, `clinical_dashboard`). |
|
|
| Use this when you want everything in one response. |
|
|
| ### `POST /analyze_files` |
| |
| Accepts multipart form-data: |
| |
| - `video`: gait video |
| - `gender`: `male` or `female` |
| |
| Returns analysis JSON with downloadable URLs: |
| |
| - `/download/{session_id}_annotated.mp4` |
| - `/download/{session_id}_dashboard.png` |
| |
| This is generally the better choice for deployment because responses stay smaller than full base64 payloads. |
| |
| ### `GET /download/{filename}` |
| |
| Downloads generated output files from `runs/outputs`. |
| |
| ### `GET /health` |
| |
| Simple health check. |
| |
| |
| ## Local development |
| |
| 1. Create environment and install dependencies |
| |
| ```bash |
| python -m venv .venv |
| source .venv/bin/activate |
| pip install -r requirements.txt |
| ``` |
| |
| 2. Run API |
| |
| ```bash |
| uvicorn app:app --reload --host 0.0.0.0 --port 8000 |
| ``` |
| |
| 3. Open docs |
| |
| - Swagger UI: http://127.0.0.1:8000/docs |
| - ReDoc: http://127.0.0.1:8000/redoc |
| |
| ## Docker usage |
| |
| Build: |
| |
| ```bash |
| docker build -t gait-api:latest . |
| ``` |
| |
| Run: |
| |
| ```bash |
| docker run --rm -p 7860:7860 gait-api:latest |
| ``` |
| |
| Container defaults: |
| |
| - serves on port `7860` |
| - startup script: [scripts/start.sh](scripts/start.sh) |
| - output directory: `/app/runs/outputs` |
| |
| ## Storage cleanup strategy |
| |
| Generated files from `/analyze_files` are stored under `runs/outputs`. |
|
|
| Cleanup is handled by [scripts/cleanup_runs.py](scripts/cleanup_runs.py): |
|
|
| - default retention: 30 minutes |
| - deletes old files under `runs/` |
| - preserves required directory structure |
|
|
| In Docker/HF Spaces, [scripts/start.sh](scripts/start.sh) starts a background cleanup loop automatically. |
|
|
| Configurable environment variables: |
|
|
| - `CLEANUP_INTERVAL_SECONDS` (default: `1800`) |
| - `RUNS_MAX_AGE_MINUTES` (default: `30`) |
|
|
| Optional manual run: |
|
|
| ```bash |
| python scripts/cleanup_runs.py --path ./runs --max-age-minutes 30 --dry-run |
| ``` |
|
|
| ## Hugging Face Spaces deployment (Docker) |
|
|
| This repository is configured for Docker Spaces. |
|
|
| Key points: |
|
|
| - README front matter is required and already included |
| - container uses [Dockerfile](Dockerfile) |
| - app starts via [scripts/start.sh](scripts/start.sh) |
| - `PORT` env is respected (default `7860`) |
|
|
| Recommended endpoint on Spaces: |
|
|
| - Use `/analyze_files` for better response size and reliability |
|
|
| ## GitHub Actions auto-deploy to HF Space |
|
|
| Workflow: [.github/workflows/deploy-hf-space.yml](.github/workflows/deploy-hf-space.yml) |
|
|
| Behavior: |
|
|
| - triggers on push to `main` |
| - sanitizes `HF_TOKEN` |
| - force-pushes repository to `xplorers/GAIT_API` |
|
|
| Required GitHub secret: |
|
|
| - `HF_TOKEN`: Hugging Face token with write access to the target Space |
|
|
