LowellDouluri/helmet-detection-backend

This microservice powers helmet detection with YOLO (rider + head coverage), TrOCR-based number-plate recognition, and a flask-socketio channel that keeps the Flutter live view in sync. The repo already includes the YOLO weight (models/best.pt) and the tracker helper.

Environment

• —HOST (default 0.0.0.0): address the server binds to so the HTTP + WebSocket listeners are reachable from Spaces.
• —PORT (default 7860): injected by Hugging Face Spaces; app.py will read it automatically.
• —YOLO_MODEL_PATH: override the path to the YOLO weights if you need to swap custom .pt files.
• —TROCR_MODEL_NAME: transformer checkpoints (default microsoft/trocr-small-printed); keep this on Spaces to avoid re-downloading during startup.
• —TROCR_LOCAL_ONLY: set to 1 on Spaces once the model cache is populated to force local loading (0 is the default for local development).
• —SOCKET_IO_ASYNC_MODE: the asynchronous engine for flask_socketio; eventlet is the only supported value in Spaces’ container environment.
• —DEBUG_SAVE_IMAGES: when 0 (recommended), debug screenshots are not saved. Turn 1 locally if you need to inspect intermediate crops.
• —FORCE_CPU: set to 1 on GPU-constrained Spaces tiers to keep inference on CPU; default is 0.
• —TEMP_UPLOAD_DIR: custom path for temporary uploads/merged videos (defaults to temp_uploads/).

Create a .env file (see .env.example) to override any of the defaults above before running locally. On Spaces, configure the same variables using the web UI or huggingface-cli so the container matches the production environment. The Dockerfile already installs opencv, Pillow, and the GPU/CPU compatible dependencies listed in requirements.txt.

Local development

1. 1.Clone the repo and create a virtual environment: python -m venv .venv && .venv/Scripts/activate.
2. 2.Install pinned dependencies: pip install -r requirements.txt.
3. 3.Copy .env.example to .env, adjust values as needed (the defaults already match Spaces expectations), and ensure the models/ directory is available locally.
4. 4.Run python app.py. The server preloads YOLO + TrOCR (protected by init_models()), listens on HOST/PORT, and exposes /health, /process, /process_video, /upload_chunk, /merge_chunks, /process/status/<job_id>, and the /frame WebSocket event.
5. 5.Use curl http://localhost:<PORT>/health to confirm readiness before pointing your Flutter app to the backend.

API behavior

• —POST /process (async) – Accepts the base64 image payload, schedules inference in the background, and immediately returns jobId/status. Poll /process/status/<job_id> until the job reaches completed or failed. Results are retained for ~1 hour (JOB_TTL_SECONDS) before being evicted.
• —GET /process/status/<job_id> – Returns the latest job status, timestamps, final response, or error if the worker crashed.
• —POST /predict (sync) – Mirrors the previous endpoint behavior; useful only when you can tolerate the ~45-second Hugging Face timeout (e.g., locally or from other clients that can handle the delay). Spaces’s 45-second window is why the async /process//status workflow is the default for Flutter.

Hugging Face Spaces deployment

1. 1.Push the folder’s contents (including models/ and requirements.txt) into a Hugging Face Space that uses the docker SDK; the included Dockerfile is already tuned for Spaces’ port bindings and installs the same system dependencies used locally.
2. 2.Set the Space’s environment variables (via UI or huggingface-cli repo push) to match production needs, for example TROCR_LOCAL_ONLY=1 and SOCKET_IO_ASYNC_MODE=eventlet. The Space will always provide PORT, so leave that unset locally if you rely on the defaults.
3. 3.Monitor the Space’s build logs; once the container starts it executes python app.py, which binds to 0.0.0.0 and accepts both HTTP and SocketIO connections on the injected port.
4. 4.Test /health and /process through the Space URL; adjust DEBUG_SAVE_IMAGES only temporarily since those artifacts can be large.

Deployment Steps

1. 1.Prepare the repo – keep app.py, tracker.py, models/, .env.example, requirements.txt, Dockerfile, and README.md committed; remove unneeded assets (debug images) until you know you need them.
2. 2.Create/verify `.env` locally (copy from .env.example), set DEBUG_SAVE_IMAGES=0, FORCE_CPU=0, and confirm HOST=0.0.0.0.
3. 3.Push to a Hugging Face Space (create with huggingface-cli repo create <space-name> --space-type docker or use the UI) by git adding/pushing the backend directory.
4. 4.Configure required env vars on the Space (e.g., TROCR_LOCAL_ONLY=1, SOCKET_IO_ASYNC_MODE=eventlet, optionally override the model paths).
5. 5.Validate the deployment by curling the Space URL’s /health endpoint and triggering /process; use the Flutter app’s WebSocket to ensure live updates arrive.