julian
6933406ae3
Skeleton of the host-side vision service per the packaging decision: a Python/FastAPI app at apps/vision/, uv-managed, wired into the Turbo graph via a thin package.json shim (dev/lint/test/build → uv/uvicorn/ruff/pytest). A per-package turbo.json sets build outputs [] so the no-op build is warning-free. Endpoints: GET /health (readiness + model version) and POST /analyze (raw octet-stream body, so Node POSTs Snapshot.bytes directly; empty→400, oversize→413, recognizer-not-ready→503). The recognizer is a Protocol with a StubRecognizer (no models, boots/tests offline — the dev/CI default) and a FastAlprRecognizer (the real MIT YOLOv9+CCT/ONNX stack, lazily imported; missing models ⇒ ready=False, not a crash) — the device-adapter pattern applied to the model. fast-alpr + onnxruntime are an optional `alpr` extra, so `uv sync` needs no model download. Verified: turbo run lint|test|build includes @parking/vision and stays green; uv run mypy strict-clean; uvicorn boots and serves /health + /analyze live; pnpm workspace 6→7. Not built yet: the Node VisionClient adapter, a Dockerfile + model fetch, and Job 2 (vehicle verification). Updates the packaging decision (As-scaffolded) + log. Claude-Session: https://claude.ai/code/session_01Xcm6ikLgGoCxxHrxtjkk5V
55 lines
2.4 KiB
Markdown
55 lines
2.4 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
|
|
```
|
|
|
|
`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` |
|