Merge pull request #81 from ankandrew/ankandrew/country-recognition

Region recognition support

Author: ankandrew

.editorconfig

@@ -10,4 +10,4 @@ insert_final_newline = true
 
 [*.py]
 indent_size = 4
-max_line_length = 100
+max_line_length = 120

.gitignore

@@ -176,3 +176,47 @@ Desktop.ini
 
 # Notebooks
 **/.ipynb_checkpoints/
+
+# Trained models
+**/trained_models/
+
+# Model artifacts
+*.keras
+*.h5
+*.hdf5
+*.weights.h5
+
+# TensorFlow ckpts
+checkpoint
+*.ckpt
+*.ckpt.*
+*.index
+*.data-*
+
+# TF SavedModel
+saved_model/
+**/saved_model/
+**/saved_model.pb
+**/variables/
+
+# Training outputs / logs
+logs/
+**/logs/
+runs/
+tb_logs/
+tensorboard/
+
+# ONNX related
+*.onnx
+*.ort
+
+# Other Export formats
+*.tflite
+*.mlmodel
+*.mlpackage
+
+# Accelerator caches/artifacts
+*.engine
+*.plan
+trt_engine_cache/
+tensorrt/

CHANGELOG.md

@@ -5,6 +5,36 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.1.0] - 2026-03-13
+
+### Added
+
+- New `cct-xs-v2-global-model` and `cct-s-v2-global-model` with plate region recognition support for 65+ countries.
+- Optional region-aware training, validation, and inference flow, including `plate_region` dataset support.
+- New region evaluation metrics, including `val_region_macro_f1`, plus per-region evaluation in validation.
+- New CCT v2 model configs, parameterized plate configs, and focal loss support for region classification.
+- Inference now returns `PlatePrediction`, exposing region outputs when available.
+- Export pipeline improvements for multi-output models, plus support for selecting the ONNX opset version.
+- Expanded dataset validation and annotation checks, including region validation and warnings on unexpected columns.
+
+### Changed
+
+- V2 pre-trained models were trained on roughly 3x more data than the v1 generation.
+- V2 training now includes empty plates built from backgrounds, noise, textures, and other padded-plate negatives.
+- Region recognition now includes an `Unknown` class trained mainly with synthetic data.
+- Updated the new CCT v2 models to use `silu` instead of `gelu` to avoid export issues with some library versions.
+- Added the corrected `attention_layout` behavior so split projection dimensions are distributed per head instead of reusing the full `projection_dim`.
+- The shipped v2 `xs` and `s` pre-trained models both exceed `0.99` `val_region_macro_f1` on a held-out validation split with more than `114_000` samples.
+- Transformer blocks and training defaults are more configurable, including projection validation, loss weighting, and milder augmentations.
+- Inference now removes the pad character by default from decoded output.
+- TFLite export now uses LiteRT via `ai-edge-litert` following TensorFlow deprecation changes.
+
+### Fixed
+
+- Fixed region recognition mismatches during validation.
+- Fixed `EarlyStopping` metric selection when training single-head models.
+- Fixed learning-rate decay step calculation to account for warmup steps.
+
 ## [1.0.2] - 2025-09-03
 
 ### Added
@@ -62,4 +92,5 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Add option to visualize only predictions which have low char prob.
 - Add onnxsim for simplifying ONNX model when exporting.
 
+[1.1.0]: https://github.com/ankandrew/fast-plate-ocr/compare/v1.0.2...v1.1.0
 [0.1.6]: https://github.com/ankandrew/fast-plate-ocr/compare/v0.1.5...v0.1.6

README.md

@@ -13,7 +13,7 @@
 [![Documentation Status](https://img.shields.io/badge/docs-latest-brightgreen.svg)](https://ankandrew.github.io/fast-plate-ocr/)
 [![image](https://img.shields.io/pypi/l/fast-plate-ocr.svg)](https://pypi.python.org/pypi/fast-plate-ocr)
 
-![Intro](https://raw.githubusercontent.com/ankandrew/fast-plate-ocr/4a7dd34c9803caada0dc50a33b59487b63dd4754/extra/demo.gif)
+![Intro](https://github.com/ankandrew/fast-plate-ocr/releases/download/arg-plates/readme_demo.gif)
 
 ---
 
@@ -27,10 +27,10 @@ The idea is to use this after a plate object detector, since the OCR expects the
 ## Features
 
 - **Keras 3 Backend Support**: Train seamlessly using **[TensorFlow](https://www.tensorflow.org/)**, **[JAX](https://github.com/google/jax)**, or **[PyTorch](https://pytorch.org/)** backends 🧠
-- **Augmentation Variety**: Diverse **training-time augmentations** via **[Albumentations](https://albumentations.ai/)** library 🖼️
 - **Efficient Execution**: **Lightweight** models that are cheap to run 💰
 - **ONNX Runtime Inference**: **Fast** and **optimized** inference with **[ONNX runtime](https://onnxruntime.ai/)** ⚡
 - **User-Friendly CLI**: Simplified **CLI** for **training** and **validating** OCR models 🛠️
+- **Region Recognition (Optional)**: Predict **region/country** of the license plate 🌍
 - **Model HUB**: Access to a collection of **pre-trained models** ready for inference 🌟
 - **Train**/**Fine-tune**: Easily train or **fine-tune** your own models 🔧
 - **Export-Friendly**: Export easily to **CoreML**, **TFLite**, or **ONNX** formats 📦
@@ -39,10 +39,12 @@ The idea is to use this after a plate object detector, since the OCR expects the
 
 Optimized, ready to use models with config files for inference or fine-tuning.
 
-| Model Name               | Size | Arch                                                                                                                      | b=1 Avg. Latency (ms) | Plates/sec (PPS) | Model Config                                                                                                                     | Plate Config                                                                                                                     | Val Results                                                                                                           |
-|--------------------------|------|---------------------------------------------------------------------------------------------------------------------------|-----------------------|------------------|----------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------|
-| `cct-s-v1-global-model`  | S    | [CCT](https://ankandrew.github.io/fast-plate-ocr/1.0/training/config/model_config/#compact-convolutional-transformer-cct) | **0.5877**            | **1701.63**      | [model_config.yaml](https://github.com/ankandrew/fast-plate-ocr/releases/download/arg-plates/cct_s_v1_global_model_config.yaml)  | [plate_config.yaml](https://github.com/ankandrew/fast-plate-ocr/releases/download/arg-plates/cct_s_v1_global_plate_config.yaml)  | [results](https://github.com/ankandrew/fast-plate-ocr/releases/download/arg-plates/cct_s_v1_global_val_results.json)  |
-| `cct-xs-v1-global-model` | XS   | [CCT](https://ankandrew.github.io/fast-plate-ocr/1.0/training/config/model_config/#compact-convolutional-transformer-cct) | **0.3232**            | **3094.21**      | [model_config.yaml](https://github.com/ankandrew/fast-plate-ocr/releases/download/arg-plates/cct_xs_v1_global_model_config.yaml) | [plate_config.yaml](https://github.com/ankandrew/fast-plate-ocr/releases/download/arg-plates/cct_xs_v1_global_plate_config.yaml) | [results](https://github.com/ankandrew/fast-plate-ocr/releases/download/arg-plates/cct_xs_v1_global_val_results.json) |
+| Model Name               | Size | Arch                                                                                                                         | b=1 Avg. Latency (ms) | Plates/sec (PPS) | Model Config                                                                                                                     | Plate Config                                                                                                                     | Val Results                                                                                                           |
+|--------------------------|------|------------------------------------------------------------------------------------------------------------------------------|-----------------------|------------------|----------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------|
+| `cct-s-v2-global-model`  | S    | [CCT](https://ankandrew.github.io/fast-plate-ocr/latest/training/config/model_config/#compact-convolutional-transformer-cct) | **0.6758**            | **1479.61**      | [model_config.yaml](https://github.com/ankandrew/fast-plate-ocr/releases/download/arg-plates/cct_s_v2_global_model_config.yaml)  | [plate_config.yaml](https://github.com/ankandrew/fast-plate-ocr/releases/download/arg-plates/cct_s_v2_global_plate_config.yaml)  | [results](https://github.com/ankandrew/fast-plate-ocr/releases/download/arg-plates/cct_s_v2_global_val_results.json)  |
+| `cct-xs-v2-global-model` | XS   | [CCT](https://ankandrew.github.io/fast-plate-ocr/latest/training/config/model_config/#compact-convolutional-transformer-cct) | **0.4664**            | **2144.14**      | [model_config.yaml](https://github.com/ankandrew/fast-plate-ocr/releases/download/arg-plates/cct_xs_v2_global_model_config.yaml) | [plate_config.yaml](https://github.com/ankandrew/fast-plate-ocr/releases/download/arg-plates/cct_xs_v2_global_plate_config.yaml) | [results](https://github.com/ankandrew/fast-plate-ocr/releases/download/arg-plates/cct_xs_v2_global_val_results.json) |
+| `cct-s-v1-global-model`  | S    | [CCT](https://ankandrew.github.io/fast-plate-ocr/latest/training/config/model_config/#compact-convolutional-transformer-cct) | **0.5877**            | **1701.63**      | [model_config.yaml](https://github.com/ankandrew/fast-plate-ocr/releases/download/arg-plates/cct_s_v1_global_model_config.yaml)  | [plate_config.yaml](https://github.com/ankandrew/fast-plate-ocr/releases/download/arg-plates/cct_s_v1_global_plate_config.yaml)  | [results](https://github.com/ankandrew/fast-plate-ocr/releases/download/arg-plates/cct_s_v1_global_val_results.json)  |
+| `cct-xs-v1-global-model` | XS   | [CCT](https://ankandrew.github.io/fast-plate-ocr/latest/training/config/model_config/#compact-convolutional-transformer-cct) | **0.3232**            | **3094.21**      | [model_config.yaml](https://github.com/ankandrew/fast-plate-ocr/releases/download/arg-plates/cct_xs_v1_global_model_config.yaml) | [plate_config.yaml](https://github.com/ankandrew/fast-plate-ocr/releases/download/arg-plates/cct_xs_v1_global_plate_config.yaml) | [results](https://github.com/ankandrew/fast-plate-ocr/releases/download/arg-plates/cct_xs_v1_global_val_results.json) |
 
 > [!TIP]
 > 🚀 Try the above models in [Hugging Spaces](https://huggingface.co/spaces/ankandrew/fast-alpr).
@@ -84,32 +86,33 @@ To predict from disk image:
 ```python
 from fast_plate_ocr import LicensePlateRecognizer
 
-m = LicensePlateRecognizer('cct-xs-v1-global-model')
+m = LicensePlateRecognizer('cct-s-v2-global-model')
 print(m.run('test_plate.png'))
 ```
 
-<details>
-  <summary>Run demo</summary>
+If your model includes a **region head** (and `plate_regions` is defined in the plate config), predictions
+also include `region`. The `region_prob` field is populated when `return_confidence=True`:
 
-![Run demo](https://github.com/ankandrew/fast-plate-ocr/blob/ac3d110c58f62b79072e3a7af15720bb52a45e4e/extra/inference_demo.gif?raw=true)
+```python
+from fast_plate_ocr import LicensePlateRecognizer
 
-</details>
+m = LicensePlateRecognizer('cct-s-v2-global-model')
+pred = m.run('test_plate.png', return_confidence=True)[0]
+print(pred.region, pred.region_prob)
+```
 
-To run model benchmark:
+To run a model benchmark:
 
 ```python
 from fast_plate_ocr import LicensePlateRecognizer
 
-m = LicensePlateRecognizer('cct-xs-v1-global-model')
+m = LicensePlateRecognizer('cct-s-v2-global-model')
 m.benchmark()
 ```
 
-<details>
-  <summary>Benchmark demo</summary>
-
-![Benchmark demo](https://github.com/ankandrew/fast-plate-ocr/blob/ac3d110c58f62b79072e3a7af15720bb52a45e4e/extra/benchmark_demo.gif?raw=true)
-
-</details>
+For more examples and the full API, see the
+[Inference Guide](https://ankandrew.github.io/fast-plate-ocr/latest/inference/running_inference/) and
+[Reference](https://ankandrew.github.io/fast-plate-ocr/latest/reference/).
 
 ## Training
 
@@ -130,6 +133,8 @@ preparing your dataset to training and exporting the model.
 For full details on data preparation, model configs, fine-tuning, and training commands, check out the
 [docs](https://ankandrew.github.io/fast-plate-ocr/1.0/training/intro/).
 
+For **region recognition** and export-friendly activations, use the v2 models.
+
 ## Contributing
 
 Contributions to the repo are greatly appreciated. Whether it's bug fixes, feature enhancements, or new models,

config/latin_plate_config_v2.yaml

@@ -0,0 +1,27 @@
+# Config for Latin-alphabet plates
+
+# Max number of plate slots supported. This represents the number of model classification heads.
+max_plate_slots: 10
+# All the possible character set for the model output.
+alphabet: '0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ_'
+# Padding character for plates which length is smaller than MAX_PLATE_SLOTS. It should still be present in the alphabet.
+pad_char: '_'
+# Image height which is fed to the model.
+img_height: 64
+# Image width which is fed to the model.
+img_width: 128
+# Keep the aspect ratio of the input image.
+keep_aspect_ratio: false
+# Interpolation method used for resizing the input image.
+interpolation: linear
+# Input image color mode. Use 'grayscale' for single-channel input or 'rgb' for 3-channel input.
+image_color_mode: rgb
+plate_regions: [ 'Albania', 'Andorra', 'Argentina', 'Armenia', 'Australia', 'Austria', 'Azerbaijan', 'Bahrain',
+                 'Belarus', 'Belgium', 'Bosnia and Herzegovina', 'Brazil', 'Bulgaria', 'Cambodia', 'Canada', 'Croatia',
+                 'Cyprus', 'Czech Republic', 'Denmark', 'Estonia', 'Finland', 'France', 'Georgia', 'Germany',
+                 'Gibraltar', 'Greece', 'Guernsey', 'Hungary', 'Iceland', 'Indonesia', 'Ireland', 'Israel', 'Italy',
+                 'Latvia', 'Liechtenstein', 'Lithuania', 'Luxembourg', 'Malaysia', 'Malta', 'Mexico', 'Moldova',
+                 'Monaco', 'Montenegro', 'Netherlands', 'New Zealand', 'North Macedonia', 'Norway', 'Poland',
+                 'Portugal', 'Qatar', 'Romania', 'San Marino', 'Serbia', 'Singapore', 'Slovakia', 'Slovenia', 'Spain',
+                 'Sweden', 'Switzerland', 'Thailand', 'Turkey', 'United States', 'Ukraine', 'United Kingdom', 'Vietnam',
+                 'Unknown' ]

docs/index.md

@@ -1,6 +1,6 @@
 # Fast & Lightweight License Plate OCR
 
-![Intro](https://raw.githubusercontent.com/ankandrew/fast-plate-ocr/4a7dd34c9803caada0dc50a33b59487b63dd4754/extra/demo.gif)
+![Intro](https://github.com/ankandrew/fast-plate-ocr/releases/download/arg-plates/readme_demo.gif)
 
 `fast-plate-ocr` is a **lightweight** and **fast** OCR framework for **license plate text recognition**. You can train
 models from scratch or use the trained models for inference.
@@ -15,10 +15,10 @@ The idea is to use this after a plate object detector, since the OCR expects the
 ### Features
 
 - **Keras 3 Backend Support**: Train seamlessly using **[TensorFlow](https://www.tensorflow.org/)**, **[JAX](https://github.com/google/jax)**, or **[PyTorch](https://pytorch.org/)** backends 🧠
-- **Augmentation Variety**: Diverse **training-time augmentations** via **[Albumentations](https://albumentations.ai/)** library 🖼️
 - **Efficient Execution**: **Lightweight** models that are cheap to run 💰
 - **ONNX Runtime Inference**: **Fast** and **optimized** inference with **[ONNX runtime](https://onnxruntime.ai/)** ⚡
 - **User-Friendly CLI**: Simplified **CLI** for **training** and **validating** OCR models 🛠️
+- **Region Recognition (Optional)**: Predict **region/country** of the license plate 🌍
 - **Model HUB**: Access to a collection of **pre-trained models** ready for inference 🌟
 - **Train**/**Fine-tune**: Easily train or **fine-tune** your own models 🔧
 - **Export-Friendly**: Export easily to **CoreML**, **TFLite**, or **ONNX** formats 📦
@@ -46,12 +46,15 @@ Run **OCR** on a **cropped** license plate image using [`LicensePlateRecognizer`
 ```python
 from fast_plate_ocr import LicensePlateRecognizer
 
-m = LicensePlateRecognizer("cct-xs-v1-global-model")
+m = LicensePlateRecognizer("cct-s-v2-global-model")
 print(m.run("test_plate.png"))
 ```
 
 For **more examples** and input formats (NumPy arrays, batches, etc.), see the [**Inference Guide**](inference/running_inference.md).
 
+If your model includes a **region head** and `plate_regions` is defined, predictions include `region`.
+The `region_prob` field is populated when `return_confidence=True`.
+
 ### Use it with FastALPR
 
 If you prefer not to use `fast-plate-ocr` directly on **cropped plates**, you can easily leverage it through **FastALPR**,