anpr-pipeline — Automatic Number Plate Recognition

End-to-end license plate recognition: plate detection → tracking → OCR → Turkish format parsing → temporal voting → privacy-aware persistence, served behind a FastAPI HTTP + WebSocket API.

Originally written in 2022 with a YOLOv5 fork + EasyOCR + Flask 1.1. Rewritten in 2026 on top of fast-alpr + fast-plate-ocr + FastAPI + uv. The original code is preserved verbatim under legacy/ for reference.

Quickstart

Via PyPI

pip install anpr-pipeline
export ANPR_PLATE_HMAC_PEPPER="$(python -c 'import secrets; print(secrets.token_hex(32))')"
anpr serve                          # FastAPI on http://localhost:8000
anpr infer path/to/plate.jpg        # one-shot CLI

Docker

export ANPR_PLATE_HMAC_PEPPER="$(python -c 'import secrets; print(secrets.token_hex(32))')"
docker compose up --build

Open http://localhost:8000.

From source, via uv

git clone https://github.com/mftnakrsu/Automatic_Number_Plate_Recognition_YOLO_OCR.git
cd Automatic_Number_Plate_Recognition_YOLO_OCR
uv sync --all-extras --group dev
cp .env.example .env
# Generate a pepper and paste it into .env
uv run anpr generate-pepper
uv run anpr serve            # FastAPI on http://localhost:8000
# or: single-image inference
uv run anpr infer tests/fixtures/sample_plate.jpg

What's in the box

API surface

Full OpenAPI at http://localhost:8000/docs.

Architecture

┌──────────────────────┐       ┌─────────────────────┐
│  Webcam / Upload     │──────►│  FastAPI            │
└──────────────────────┘       │   /infer  /ws/stream │
                               └──────────┬──────────┘
                                          ▼
┌──────────────────────────────────────────────────────┐
│  Pipeline (async, frame-skip + drop-on-full queue)   │
│                                                       │
│   Detector ──► IoUTracker ──► dewarp ──► PlateReader  │
│    fast-alpr      greedy        cv2       fast-plate  │
│      ONNX                                    ONNX     │
│                       │                               │
│                       ▼                               │
│              parse_turkish_plate                      │
│              correct_confusions                       │
│              TemporalVoter (majority)                 │
└──────────────────────────────────────────────────────┘
                                          │
                                          ▼
┌──────────────────────┐       ┌─────────────────────┐
│  SQLite / Postgres   │◄──────│  HMAC-SHA256(plate)  │
│  (only hashes)       │       │  KVKK + GDPR safe    │
└──────────────────────┘       └─────────────────────┘

Configuration

All settings live under the ANPR_ env prefix and can be overridden via .env. See .env.example for the full reference.

Privacy — KVKK & GDPR

License plates are personal data under both Türkiye's KVKK (Law 6698, art. 3(d)) and the EU GDPR (Reg. 2016/679 art. 4(1)). This project is privacy-aware by default:

• Plates are never stored as plaintext. The database holds only HMAC-SHA256 of the normalized plate string, salted with a per-deployment pepper. Hashes are deterministic for matching but not reversible without the pepper.
• A retention worker purges rows older than ANPR_RETENTION_HOURS automatically.
• The web UI (templates/index.html) shows the human-readable plate live in the browser but does not persist the raw text.

If you deploy this for an organization, you'll likely need to publish a KVKK Aydınlatma Metni / GDPR Article 13 notice. A starter template is in KVKK_AYDINLATMA_METNI.md — adapt it to your actual processing context, this is not legal advice.

Development

uv sync --all-extras --group dev
make lint       # ruff check + format check
make type       # pyright
make test       # pytest (60+ tests)
make serve      # uvicorn --reload

Run the end-to-end test against real bundled models (downloads ~30MB on first run):

ANPR_RUN_REAL=1 uv run pytest tests/integration/test_pipeline_real.py

Project structure

src/anpr/
├── api/                 FastAPI app, routes, templates, static
│   ├── app.py
│   ├── deps.py          lifespan-loaded singletons
│   ├── middleware.py    request_id + Prometheus middleware
│   └── routes/          health, infer, stream (WS), detections
├── detector/            Detector Protocol + fast-alpr adapter
├── ocr/                 PlateReader Protocol + fast-plate-ocr adapter
├── postprocess/         turkish, confusion, temporal, dewarp
├── storage/             SQLModel Detection + HMAC + repository + retention
├── tracker/             IoU greedy tracker
├── observability.py     Prometheus metrics + optional OTel
├── config.py            pydantic-settings
├── logging.py           structlog
├── cli.py               typer
└── pipeline.py          sync infer_image + async Pipeline
tests/
├── unit/                turkish, confusion, temporal, iou_tracker, hashing (+ hypothesis properties)
└── integration/         pipeline_smoke, api_smoke, metrics, storage, infer_response_shape, pipeline_real
legacy/                  2022 codebase preserved verbatim

Migration from the 2022 pipeline

The 2022 code is not removed — it sits intact under legacy/. What changed:

If you depended on the old import paths or the model/best.pt checkpoint, pin to the pre-merge tag and follow legacy/README.md (yet to be written) for context.

Acknowledgments

This rewrite stands on the work of:

• ankandrew/fast-alpr — turn-key MIT-licensed ANPR pipeline
• ankandrew/fast-plate-ocr — fast plate-specialized OCR with the cct-s-v2-global-model
• Ultralytics — original YOLOv5 the 2022 pipeline built on
• Astral — uv and ruff

License

MIT