Add professional performance charts and a complete setup guide to the model card

README.md

@@ -32,24 +32,55 @@ real-time, self-hosted plate-surveillance system.
 > 🤗 **This model repo:** https://huggingface.co/Dibachain/Platrix
 
 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. `۸۱ و ۶۳۸ ۱۳`.
+frame, an image-quality **enhancement** step cleans the crop, 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
+## 📊 Performance
+
+Measured on **220 real Iranian surveillance photos** (grayscale gate/road
+cameras — the hard, real-world domain, not staged shots).
+
+<p align="center">
+  <img src="https://huggingface.co/Dibachain/Platrix/resolve/main/assets/benchmark.png" width="88%" />
+</p>
+
+A lightweight **secondary detector** runs only when the primary finds nothing.
+It recovers plates the primary is blind to — trucks, night shots, small/far and
+dim plates — lifting the end-to-end read rate from **95.9% → 97.7%** with **no
+regression** on the easy majority (the fallback fires on only ~2% of frames).
+
+<p align="center">
+  <img src="https://huggingface.co/Dibachain/Platrix/resolve/main/assets/recovery.png" width="70%" />
+</p>
+
+### Training curves
+
+<p align="center">
+  <img src="https://huggingface.co/Dibachain/Platrix/resolve/main/assets/reader_training.png" width="49%" />
+  <img src="https://huggingface.co/Dibachain/Platrix/resolve/main/assets/detector_training.png" width="49%" />
+</p>
+
+The reader reaches ~93% whole-plate accuracy in training and **~98% on real
+photos**; the detector reaches **mAP@0.5 ≈ 0.99** on held-out real frames.
+
+---
+
+## 📁 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` |
-| `plate_yolo_fallback.onnx` | **Secondary detector** — runs only when the primary finds nothing; recovers hard surveillance frames (grayscale / dim / small / truck plates) | `1×3×640×640` | `1×5×N` |
+| `plate_yolo.onnx` | **Plate detector** (YOLOv8, primary) | `1×3×H×W` RGB, letterboxed, `/255` | `1×5×N` → `cx,cy,w,h,conf` |
+| `plate_yolo_fallback.onnx` | **Secondary detector** — runs only when the primary finds nothing; recovers hard surveillance frames | `1×3×640×640` | `1×5×N` |
 | `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.onnx` | Per-character classifier (lightweight fallback reader) | `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
@@ -57,69 +88,82 @@ inference time.
 
 ---
 
-## Why a segmentation-free reader?
+## 🚀 Getting started
 
-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.
+### Option A — Run the full Platrix system (recommended)
 
-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.
+The complete app (web dashboard, multi-camera streaming, watchlists, API) lives
+in the GitHub repo. It downloads these models for you.
 
----
+```bash
+git clone https://github.com/AliAkrami1375/Platrix.git
+cd Platrix
+
+# fetch the models from this repo into ./models
+pip install -U "huggingface_hub[cli]"
+huggingface-cli download Dibachain/Platrix \
+    plate_yolo.onnx plate_yolo_fallback.onnx \
+    ocr_crnn.onnx ocr_crnn.labels.json ocr_cnn.onnx ocr_cnn.labels.json \
+    --local-dir models/
+
+# then either:
+docker compose up --build             # Docker
+# — or —
+python -m venv .venv && source .venv/bin/activate
+pip install -r requirements.txt && pip install -e .
+platrix serve                         # dashboard at http://localhost:8080
+```
 
-## Quick usage
+### Option B — Use the models directly (ONNX Runtime)
 
 ```bash
 pip install onnxruntime opencv-python-headless numpy
 huggingface-cli download Dibachain/Platrix \
-    plate_yolo.onnx ocr_crnn.onnx ocr_crnn.labels.json --local-dir models/
+    plate_yolo.onnx plate_yolo_fallback.onnx ocr_crnn.onnx ocr_crnn.labels.json \
+    --local-dir models/
 ```
 
-A few **real test photos** ship in this repo under [`img-test/`](./tree/main/img-test)
-so you can try recognition right away:
-
-<p align="center">
-  <img src="https://huggingface.co/Dibachain/Platrix/resolve/main/img-test/sample-01.jpg" width="32%" />
-  <img src="https://huggingface.co/Dibachain/Platrix/resolve/main/img-test/sample-02.jpg" width="32%" />
-  <img src="https://huggingface.co/Dibachain/Platrix/resolve/main/img-test/sample-03.jpg" width="32%" />
-  <img src="https://huggingface.co/Dibachain/Platrix/resolve/main/img-test/sample-05.jpg" width="32%" />
-  <img src="https://huggingface.co/Dibachain/Platrix/resolve/main/img-test/sample-06.jpg" width="32%" />
-  <img src="https://huggingface.co/Dibachain/Platrix/resolve/main/img-test/sample-08.jpg" width="32%" />
-</p>
-
 ```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
+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)
+    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
+    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
+**Two-stage flow:** run `plate_yolo.onnx` first (standard YOLOv8 letterbox
+pre-process + confidence/NMS post-process) to crop the plate, then pass the crop
 to `read_plate`. If the primary detector returns nothing, run
-`plate_yolo_fallback.onnx` (at 640×640) as a second pass — it recovers hard
-surveillance frames (grayscale, dim, small or truck-mounted plates) the primary
-is blind to, raising end-to-end read rate on real photos from ~96% to ~98%. 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).
+`plate_yolo_fallback.onnx` at **640×640** as a second pass — it recovers the hard
+surveillance frames the primary is blind to. A few **real test photos** ship
+under [`img-test/`](./tree/main/img-test) so you can try it immediately.
+
+---
+
+## 🧠 How it works
+
+1. **Detect** — YOLOv8 locates the plate; weak/non-plate boxes are ignored.
+2. **Enhance** — the crop is upscaled, denoised, contrast-corrected and sharpened.
+   The *same* enhancement is applied during training, so there is no train/serve
+   mismatch — the enhancement genuinely helps instead of shifting the input.
+3. **Read** — the segmentation-free CRNN reads the whole plate in one pass with a
+   CTC head. It is trained on **real Iranian plate-character shapes**, so
+   look-alike glyphs (e.g. the digit `۴` vs `۶`) are read correctly.
+
+Splitting a plate into individual characters is fragile on real photos (shadows,
+motion blur, tilt, dirt); reading the entire plate at once is far more robust.
 
 ---
 
@@ -128,7 +172,7 @@ dashboard — lives in the [Platrix repository](https://github.com/AliAkrami1375
 - **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.
+  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.