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
69 lines
3.1 KiB
Markdown
69 lines
3.1 KiB
Markdown
# @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
|
|
|
|
```bash
|
|
# 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)
|
|
|
|
```bash
|
|
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)
|
|
|
|
```bash
|
|
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` |
|