README.md

metadata

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, and the production API implementation is in 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.

Project structure

• app.py: Main API + gait analysis pipeline
• requirements.txt: Python dependencies
• Dockerfile: Container build (HF Spaces compatible)
• scripts/start.sh: Container startup + background cleanup loop
• scripts/cleanup_runs.py: Deletes old generated files
• .github/workflows/deploy-hf-space.yml: Auto-sync GitHub repo to HF Space
• 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.

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

python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

2. Run API

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:

docker build -t gait-api:latest .

Run:

docker run --rm -p 7860:7860 gait-api:latest

Container defaults:

• serves on port 7860
• startup script: 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:

• default retention: 30 minutes
• deletes old files under runs/
• preserves required directory structure

In Docker/HF Spaces, 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:

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
• app starts via 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

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