Add production ALPR models (YOLO detector + CRNN reader + CNN fallback) and model card

README.md

@@ -0,0 +1,117 @@
+---
+license: mit
+language:
+  - fa
+library_name: onnxruntime
+pipeline_tag: image-to-text
+tags:
+  - alpr
+  - license-plate-recognition
+  - ocr
+  - persian
+  - farsi
+  - iranian-license-plate
+  - crnn
+  - ctc
+  - yolo
+  - onnx
+  - object-detection
+---
+
+# ocr-persian — Iranian License-Plate Recognition Models
+
+Production ONNX models for detecting and reading **Iranian vehicle license
+plates**, powering the [**Platrix**](https://github.com/AliAkrami1375/Platrix)
+real-time, self-hosted plate-surveillance system.
+
+The pipeline is **two-stage**: a YOLO **detector** locates the plate in the
+frame, then a segmentation-free **CRNN + CTC reader** reads the whole plate at
+once and returns the standard Iranian layout `DD L DDD DD`
+(two digits · letter · three digits · two-digit region), e.g. `۸۱ و ۶۳۸ ۱۳`.
+
+All models run with **ONNX Runtime** — no PyTorch or TensorFlow needed at
+inference time.
+
+---
+
+## Files
+
+| File | Role | Input | Output |
+|------|------|-------|--------|
+| `plate_yolo.onnx` | **Plate detector** (YOLOv8) | `1×3×H×W` RGB, letterboxed, `/255` | `1×5×N` → `cx,cy,w,h,conf` |
+| `ocr_crnn.onnx` | **Whole-plate reader** (CRNN+CTC) — *recommended* | `1×1×32×128` grayscale, `/255` | `1×T×(C+1)` logits (CTC, blank = last) |
+| `ocr_crnn.labels.json` | Class list for the CRNN (index → character) | — | 32 classes |
+| `ocr_cnn.onnx` | Per-character classifier (lightweight fallback) | `1×1×32×32` grayscale | class logits |
+| `ocr_cnn.labels.json` | Class list for the per-char classifier | — | — |
+
+**Character set (32 classes):** digits `0–9` and the Persian plate letters
+`ا ب ت ث ج ح د ز س ش ص ط ع ق ل م ن ه و پ ژ ی`.
+
+---
+
+## Why a segmentation-free reader?
+
+Splitting a plate into individual characters is fragile on real photos
+(shadows, motion blur, tilt, dirt). The CRNN reads the **entire plate in one
+pass** with a CTC head, which is far more robust. It is trained on **real
+Iranian plate-character shapes**, so look-alike glyphs (e.g. the digit `۴` vs
+`۶`) are read correctly.
+
+A key detail: the **same image-enhancement** (upscale → denoise → CLAHE
+contrast → unsharp) is applied both during training and at serving time, so
+there is no train/serve mismatch — the enhancement genuinely helps accuracy
+instead of shifting the input distribution.
+
+---
+
+## Quick usage
+
+```bash
+pip install onnxruntime opencv-python-headless numpy
+huggingface-cli download Dibachain/ocr-persian \
+    plate_yolo.onnx ocr_crnn.onnx ocr_crnn.labels.json --local-dir models/
+```
+
+```python
+import json, cv2, numpy as np, onnxruntime as ort
+
+# --- Reader (CRNN + CTC) ---
+labels = json.load(open("models/ocr_crnn.labels.json", encoding="utf-8"))
+blank  = len(labels)                       # CTC blank is the last index
+crnn   = ort.InferenceSession("models/ocr_crnn.onnx", providers=["CPUExecutionProvider"])
+
+def read_plate(plate_bgr):
+    g = cv2.cvtColor(plate_bgr, cv2.COLOR_BGR2GRAY)
+    g = cv2.resize(g, (128, 32)).astype(np.float32) / 255.0     # 1x1x32x128
+    logits = crnn.run(None, {"input": g[None, None]})[0][0]      # T x (C+1)
+    ids, out, prev = logits.argmax(1), [], -1
+    for i in ids:                                               # greedy CTC decode
+        if i != blank and i != prev:
+            out.append(labels[i])
+        prev = i
+    return "".join(out)
+```
+
+Run `plate_yolo.onnx` first to crop the plate from a full frame (standard
+YOLOv8 letterbox pre-process + confidence/NMS post-process), then pass the crop
+to `read_plate`. The full, batteries-included pipeline — detection, enhancement,
+grammar-constrained decoding, multi-camera streaming, watchlists and a web
+dashboard — lives in the [Platrix repository](https://github.com/AliAkrami1375/Platrix).
+
+---
+
+## Intended use & limitations
+
+- **Intended for** lawful applications such as parking management, access
+  control, gate automation and traffic analytics.
+- **Optimised for** standard private Iranian plates. Very low-resolution,
+  heavily occluded, or non-standard plates may reduce accuracy.
+- You are responsible for complying with the privacy and surveillance laws that
+  apply to your deployment.
+
+---
+
+## Links
+
+- **Project & full pipeline:** https://github.com/AliAkrami1375/Platrix
+- **License:** MIT

ocr_cnn.labels.json

@@ -0,0 +1,30 @@
+[
+  "0",
+  "1",
+  "2",
+  "3",
+  "4",
+  "5",
+  "6",
+  "7",
+  "8",
+  "9",
+  "ا",
+  "ب",
+  "ت",
+  "ج",
+  "د",
+  "س",
+  "ص",
+  "ط",
+  "ع",
+  "ق",
+  "ل",
+  "م",
+  "ن",
+  "ه",
+  "و",
+  "پ",
+  "ژ",
+  "ی"
+]

ocr_cnn.onnx

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:7d573c51cc855a8e080f1f88597477f4fb5a2b9cafa1bb125bd6038e441f5bca
+size 2226402

ocr_crnn.labels.json

@@ -0,0 +1 @@
+["0", "1", "2", "3", "4", "5", "6", "7", "8", "9", "ا", "ب", "ت", "ث", "ج", "ح", "د", "ز", "س", "ش", "ص", "ط", "ع", "ق", "ل", "م", "ن", "ه", "و", "پ", "ژ", "ی"]

ocr_crnn.onnx

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:45f8c45f29eb1ee91f6274cb8d9c328da1a2050ea7d8596bae61f4a6b9f9fb1e
+size 10452525

plate_yolo.onnx

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:a54e475c402e6036bb5c70f1a6ff75179e76098a5c8039bb5d148c0b6421f5c6
+size 12608775