parking_solution/apps/vision/README.md

@parking/vision — host-side ANPR / vehicle-verification service

A separate process (Python + FastAPI) the Node backend calls over localhost HTTP with a camera snapshot, returning a licence-plate read (and, later, vehicle-attribute verification — the anti-plate-spoofing witness). Recognition is advisory, never the sole authority to open a barrier: if this service is down or unsure, the host falls back to the ticket path.

Lives inside the Turborepo at apps/vision/ but is not a JS package — Python deps are managed by uv/pyproject.toml; the package.json is a thin shim so turbo run lint/test includes it. See wiki/decisions/vision-service-packaging.md and wiki/entities/opencv-anpr-service.md.

Run

# from apps/vision/ — install the light core (boots in stub mode, no model downloads)
uv sync

# dev server with reload (or: pnpm --filter @parking/vision dev)
uv run uvicorn vision_service.app:app --reload --port 8089

# checks
uv run ruff check .
uv run pytest -q

Enable the real recognizer (fast-alpr)

uv sync --extra alpr                 # installs fast-alpr + onnxruntime (downloads model weights)
VISION_RECOGNIZER=fast_alpr uv run uvicorn vision_service.app:app --port 8089

Model weights (~11 MB: a YOLOv9 detector + CCT OCR) download on first use and cache under ~/.cache/open-image-models + ~/.cache/fast-plate-ocr — offline after that.

Quick test against an image (CLI, no HTTP)

uv run python -m vision_service.cli path/to/car.jpg          # or: pnpm --filter @parking/vision recognize -- car.jpg
uv run python -m vision_service.cli car.jpg --ocr cct-s-v2-global-model   # try another OCR model

Prints the parsed plate(s) + confidence + region as JSON. Confidence is the min of fast-alpr's per-character confidences (a plate is only as trustworthy as its weakest character). Example output on the fast-alpr test image: 5AU5341 (1.000) region "Czech Republic" in ~40 ms on CPU.

fast-alpr is MIT (YOLOv9 detector + CCT OCR on ONNX Runtime). Swap VISION_OCR_MODEL to the 40+ country European model to benchmark Albanian plates. For GPU/NPU, install onnxruntime-gpu / -openvino / -directml instead of onnxruntime.

API

• GET /health → { status, recognizer, ready, model_version, detail? }
• POST /analyze (body = raw image bytes, Content-Type: application/octet-stream) → { plate: {text, confidence, bbox}|null, plates[], vehicle: null, low_confidence, model_version, took_ms }

The Node side POSTs Snapshot.bytes directly (no multipart). vehicle is scaffolded but not yet populated — fast-alpr is plate-only; the vehicle stage (Job 2) is built later on the same runtime.

Config (env, prefix VISION_) — see .env.example

This service's env only. The Node server has its own VISION_* (apps/server/.env: VISION_ENABLED, VISION_URL, VISION_POLL_MS, …) — same prefix, separate process, separate .env. Don't merge them.

Var	Default	Meaning
VISION_RECOGNIZER	stub	stub (no models) or fast_alpr (real)
VISION_HOST	0.0.0.0	bind address — prefer 127.0.0.1 on the appliance (Node is the only caller)
VISION_PORT	8089	listen port (must match the server's VISION_URL)
VISION_DETECTOR_MODEL	yolo-v9-t-384-license-plate-end2end	fast-alpr detector
VISION_OCR_MODEL	cct-xs-v2-global-model	fast-alpr OCR (won the AL benchmark)
VISION_MIN_CONFIDENCE	0.5	below this → low_confidence=true

To use it from the booth: set VISION_ENABLED=1 on the server, run this service, then tick ANPR on a camera in the SetupWizard (the camera must also be bound to a barrier). The booth footer shows a Vision chip when enabled. Full config guide: wiki/entities/opencv-anpr-service.md.