julian
5cedcaefe1
Add a dev CLI (uv run python -m vision_service.cli <image>) that runs a recognizer on an image file and prints the parsed plate(s) + confidence + region — fast feedback with no HTTP. Also a package.json `recognize` script and a vision-recognize entry point. Verified fast-alpr for real: installed the `alpr` extra, downloaded the YOLOv9 + CCT ONNX weights (~11MB, cached offline under ~/.cache), and ran recognition on the project's test image → "5AU5341" at 1.000 confidence, region "Czech Republic", ~40ms on CPU, via both the CLI and POST /analyze. Fixes result parsing against the actual fast-alpr API: ocr.confidence is a LIST of per-character confidences (not a scalar) — reduced to one plate confidence via the MIN (a plate is only as trustworthy as its weakest character); also surface ocr.region. Extracted the per-result mapping into a pure plate_from_alpr_result + _reduce_confidence and unit-tested them (no model weights needed). 7 tests pass; ruff + mypy strict clean; full turbo build/lint/test green. Claude-Session: https://claude.ai/code/session_01Xcm6ikLgGoCxxHrxtjkk5V
3.1 KiB
@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_)
| Var | Default | Meaning |
|---|---|---|
VISION_RECOGNIZER |
stub |
stub (no models) or fast_alpr (real) |
VISION_PORT |
8089 |
listen port |
VISION_DETECTOR_MODEL |
yolo-v9-t-384-license-plate-end2end |
fast-alpr detector |
VISION_OCR_MODEL |
cct-xs-v2-global-model |
fast-alpr OCR |
VISION_MIN_CONFIDENCE |
0.5 |
below this → low_confidence=true |