mftnakrsu/Automatic_Number_Plate_Recognition_YOLO_OCR
mftnakrsu/Automatic_Number_Plate_Recognition_YOLO_OCR has 209 GitHub stars and 45 forks. GitHot measured +1 in 7 days. Last checked 2026-11-18 11:59 UTC. Last push 2026-11-14.
Measured star growth
- in 24h
- Update delayed
- in 7 days
- +1
- in 15 days
- Collecting history
- in 1 month
- Collecting history
Net star changes over overlapping periods, not daily totals. Missing measurements are left blank. Stars measure attention, not software quality.
About
Automatic Number Plate Recognition pipeline — fast-alpr + fast-plate-ocr + FastAPI. Privacy-aware (HMAC + KVKK + GDPR). pip install anpr-pipeline
DataREADME.md
Originalanpr-pipeline — Automatic Number Plate Recognition
End-to-end license plate recognition: plate detection → tracking → OCR → plate format parsing (Türkiye + six EU countries) → temporal voting → privacy-aware persistence, served behind a FastAPI HTTP + WebSocket API.
Documentation: https://anpr.mefby.com (English and Turkish).
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 underlegacy/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
anpr watch rtsp://camera/stream # video file, RTSP stream or camera index
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
| Layer | Implementation |
|---|---|
| Detector | fast-alpr's bundled YOLOv9-t 384 ONNX license-plate model (MIT, 65+ countries) |
| OCR | fast-plate-ocr cct-s-v2-global-model (sub-millisecond GPU, per-character confidences) |
| Tracker | Dependency-free greedy IoU tracker (swap to ByteTrack via the Tracker Protocol) |
| Plate formats | Türkiye (all 81 province codes) by default; Germany, France, Italy, Spain, Belgium and Portugal via ANPR_PLATE_FORMATS |
| Confusion fix | Position-aware OCR fixups (0/O, 1/I/L, 5/S, 8/B, 2/Z, 6/G, 0/D/Q) |
| Temporal voting | Per-character-position majority vote over top-K confidence-weighted reads per track |
| Web | FastAPI 0.115 + uvicorn, REST + WebSocket, dark-theme HTMX UI |
| Storage | SQLModel + aiosqlite default; HMAC-SHA256 plate hashing (no raw plate text ever stored) |
| Watchlist | Plates to look for, kept as hashes; signed webhook call when one is confirmed |
| Observability | structlog + Prometheus /metrics + opt-in OpenTelemetry (otel extras) |
| Packaging | uv + pyproject.toml, ruff (lint + format), pyright, pytest (190 tests) |
API surface
| Endpoint | Method | What |
|---|---|---|
/ |
GET | HTMX UI (upload + live webcam) |
/health |
GET | k8s probe |
/version |
GET | running version |
/metrics |
GET | Prometheus text-format metrics |
/api/v1/infer |
POST (multipart) | single-image inference |
/api/v1/detections |
GET | recent persisted reads (HMAC-hashed) |
/api/v1/watchlist |
GET / POST / DELETE | plates that trigger the webhook (stored as hashes) |
/ws/stream |
WS | binary JPEG frames in → JSON read events out |
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_plate (ANPR_PLATE_FORMATS) │
│ 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.
| Env | Default | Notes |
|---|---|---|
ANPR_PLATE_HMAC_PEPPER |
(generated; warns) | Required in prod. Generate with anpr generate-pepper. Must be ≥ 32 chars. |
ANPR_API_KEY |
(unset = open API) | When set, /api/v1/* and /ws/stream need it (X-API-Key, Authorization: Bearer, or WS subprotocol anpr.key.<key>). Generate with anpr generate-api-key. |
ANPR_DATABASE_URL |
sqlite+aiosqlite:///data/anpr.db |
Switch to postgresql+asyncpg://... for production. |
ANPR_RETENTION_HOURS |
720 (30d) |
Background worker purges rows older than this. |
ANPR_WEBHOOK_URL |
(unset) | Watchlist matches are POSTed here; ANPR_WEBHOOK_SECRET signs them (X-ANPR-Signature). |
ANPR_PLATE_FORMATS |
tr |
Country plate layouts to accept, in order: tr, de, fr, it, es, be, pt. |
ANPR_DETECT_EVERY_N_FRAMES |
3 |
Detect on every Nth frame; track between. |
ANPR_MIN_TRACK_DWELL |
5 |
Frames a track must persist before the voter emits confirmed. |
ANPR_DETECTOR_MODEL |
yolo-v9-t-384-license-plate-end2end |
Pass a path to use a fine-tuned ONNX. |
ANPR_OCR_MODEL |
cct-s-v2-global-model |
fast-plate-ocr model name. |
ANPR_DEVICE |
auto |
auto / cpu / cuda / openvino. |
ANPR_LOG_JSON |
false |
Set to true for structured logs to OTLP / Loki. |
OTEL_EXPORTER_OTLP_ENDPOINT |
(unset) | When set, installs OTel FastAPI instrumentation (requires otel extras). |
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_HOURSautomatically. - 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 (190 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, watchlist
├── detector/ Detector Protocol + fast-alpr adapter
├── ocr/ PlateReader Protocol + fast-plate-ocr adapter
├── postprocess/ formats (per country), turkish, confusion, temporal, dewarp
├── storage/ SQLModel Detection + HMAC + repository + retention
├── tracker/ IoU greedy tracker
├── video.py frame sources for `anpr watch` (files, RTSP, cameras)
├── watchlist.py in-memory watchlist + match alerts
├── webhook.py signed, retried webhook calls
├── 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/ formats, turkish, confusion, temporal, iou_tracker, hashing, imaging, video, webhook, cli_keys (+ hypothesis properties)
└── integration/ pipeline_smoke, api_smoke, api_auth, metrics, storage, infer_response_shape, plate_formats, watchlist, cli_watch, 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:
| 2022 | 2026 |
|---|---|
Vendored YOLOv5 fork (~7900 LOC in utils/ + models/) |
fast-alpr 0.4 → YOLOv9-t-384 ONNX, MIT, ~150 LOC of glue |
| EasyOCR 1.4 + PaddleOCR + Tesseract (mixed/inconsistent) | fast-plate-ocr 1.1 cct-s-v2 (single source of truth) |
| Flask 1.1.2 (CVE) | FastAPI 0.115 + uvicorn |
python main.py (webcam) and python app.py (Flask, parallel + no OCR) |
anpr infer image.jpg, anpr serve |
| No tracking | IoU greedy + temporal majority voting |
| No plate validation | Plate format parsers (Türkiye + six EU countries) + confusion correction |
requirements.txt (broken: tensorrt==0.0.1.dev5, etc.) |
pyproject.toml (installed with uv) |
| No tests, no CI | 190 tests, GitHub Actions matrix (Python 3.11–3.14) |
print() |
structlog + Prometheus + opt-in OTel |
| CSV append, raw plate text | SQLModel + HMAC-SHA256 + retention worker |
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 pipelineankandrew/fast-plate-ocr— fast plate-specialized OCR with thecct-s-v2-global-model- Ultralytics — original YOLOv5 the 2022 pipeline built on
- Astral —
uvandruff