fast-plate-ocr

Region recognition is automatically enabled if your training CSV contains a plate_region column and your plate configuration defines plate_regions.

You can tune the region recognition performance using the following flags:

• --region-loss: The loss function for region recognition.
• --region-loss-weight: The weight applied to the region loss.
• --region-focal-alpha: Alpha parameter for focal loss.
• --region-focal-gamma: Gamma parameter for focal loss.

The CCT architecture is a supported model structure that combines convolutional and transformer components:

1. Convolutional Tokenizer: Extracts patch representations from the input image using a sequence of layers (e.g., Conv2D, MaxBlurPooling2D).
2. Transformer Encoder: Processes the resulting sequence of patches using multi-head attention and MLP layers.

When configuring the transformer_encoder, you can control the attention_layout to determine how projection_dim is distributed:

• split_projection (recommended): Splits projection_dim across heads (each head uses projection_dim / num_heads).
• legacy_per_head: Each head uses the full projection_dim (used for backward compatibility).

model: cct

tokenizer:
  patch_size: 2
  positional_emb: true

transformer_encoder:
  heads: 1
  projection_dim: 64
  attention_layout: split_projection

To train the model to predict both the plate text and the geographic region/country, include the plate_region column in your CSV.

Requirements:

1. The plate_region column must be present in the CSV.
2. Your plate configuration must define plate_regions.

When these conditions are met, the training process will automatically enable the region head, allowing the model to learn region predictions alongside the plate text.

image_path,plate_text,plate_region
images/00001.jpg,KNN505,Argentina
images/00002.jpg,J00NCW,Argentina

When passing in-memory NumPy arrays instead of file paths, you must adhere to the following conventions to ensure correct inference:

• Dtype: Use uint8. The library casts inputs to uint8; it does not perform normalization on floating-point arrays.
• Layout: Use channels_last layout.
  • Single image: (H, W, C)
  • Batch: (N, H, W, C)
• Color Channels:
  • Grayscale models: Pass arrays with shape (H, W) or (H, W, 1).
  • RGB models: Pass arrays with shape (H, W, 3). If using OpenCV (cv2.imread), you must convert BGR to RGB before passing the array to the recognizer.
• Batching: For batch processing in memory, use a 4D array with shape (N, H, W, C).

Region recognition (and export-friendly activations) is supported using v2 model configurations. To enable region recognition, ensure both of the following conditions are met:

1. Your annotations include a plate_region column.
2. Your plate configuration defines plate_regions.

To use models with GPU acceleration (e.g., via TensorRT or CUDA), install the project with the onnx-gpu extra:

pip install fast-plate-ocr[onnx-gpu]

The model_config.yaml file defines the architecture of the OCR model used during training. It allows you to customize components like convolutional tokenizers, patching strategies, and attention settings without modifying the source code. All configurations are validated using Pydantic to ensure parameters and layers are correctly specified.

Note: While plate_config.yaml is used for both inference and training, model_config.yaml is used exclusively for training to define the model structure being built.

model: cct

rescaling:
  scale: 0.00392156862745098
  offset: 0.0

tokenizer:
  blocks:
    - { layer: Conv2D, filters: 32, kernel_size: 3, strides: 1 }
  # ... other tokenizer settings

transformer_encoder:
  layers: 4
  heads: 1
  projection_dim: 64

To export a model for Apple platforms (CoreML and Xcode), use the coreml format. This produces a .mlpackage file.

fast-plate-ocr export \
  --model trained_models/best.keras \
  --plate-config-file config/latin_plates.yaml \
  --format coreml

The plate configuration file (typically a YAML file) defines how license plate images and text are preprocessed for both OCR model training and inference. This configuration is parsed and validated using the PlateOCRConfig class via Pydantic.

Key considerations:

• The alphabet string must contain every possible character the model can output, and it must include the pad_char.
• If keep_aspect_ratio is set to true, the padding_color field determines the color used to fill the empty space created by preserving the image's original proportions.

max_plate_slots: 9
alphabet: "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ_"
pad_char: "_"
img_height: 64
img_width: 160
keep_aspect_ratio: true
interpolation: linear
image_color_mode: grayscale
padding_color: 114
plate_regions: ["USA", "Germany", "Unknown"]