fastALPR

License Plate Recognition

fastALPR runs Automatic License Plate Recognition (ALPR) locally, in-process, using the fast-alpr Python package. Detection and OCR both run as ONNX models on your own hardware (CPU or GPU) - no external server, API key, or internet access is required at inference time, unlike components such as CodeProject.AI or Deepstack.

fastALPR is a post processor and works together with an object detector component (e.g. darknet, yolo, edgetpu). It runs on the bounding boxes of detected vehicles (e.g. car, truck) and looks for a license plate within them.

Configuration

Configuration example

/config/config.yaml
fastalpr:
  license_plate_recognition:
    cameras:
      viseron_CHANGEME_camera:
    labels:
      - car
      - truck
    known_plates:
      - ABC123
    save_plates: true
    min_confidence: 0.6
    detector_model: yolo-v9-t-384-license-plate-end2end
    ocr_model: cct-xs-v2-global-model
    device: auto

fastalprmap required

fast-alpr configuration.

license_plate_recognitionmap (optional)

License plate recognition domain config.

camerasmap required

Camera-specific configuration. All subordinate keys corresponds to the camera_identifier of a configured camera.

<CAMERA_IDENTIFIER>map required

Camera identifier. Valid characters are lowercase a-z, numbers and underscores.

labelslist (optional)

A list of labels that when detected will be sent to the post processor. Applies only to this specific camera.

masklist (optional)

A mask is used to exclude certain areas in the image from post processing.

coordinateslist required

List of X and Y coordinates to form a polygon

Minimum items: 3

xinteger required

X-coordinate (horizontal axis).

yinteger required

Y-coordinate (vertical axis).

labelslist (optional)

A list of labels that when detected will be sent to the post processor. Applies to all cameras defined under cameras.

known_plateslist (optional)

List of known license plates. Each plate will have its own sensor.

save_platesboolean (optional, default: true)

If set to true, detected license plates will be stored in the database, as well as having a snapshot saved.

min_confidencefloat (optional, default: 0.6)

Minimum confidence for a license plate detection.

Lowest value: 0

Highest value: 1

expire_afterfloat (optional, default: 5)

Time in seconds before a plate recognition expires.

Lowest value: 0

detector_modelselect (optional, default: yolo-v9-t-384-license-plate-end2end)

Which license plate detector model to use. See models for more information on this.

Valid values:

yolo-v9-s-608-license-plate-end2end
yolo-v9-t-640-license-plate-end2end
yolo-v9-t-512-license-plate-end2end
yolo-v9-t-416-license-plate-end2end
yolo-v9-t-384-license-plate-end2end
yolo-v9-t-256-license-plate-end2end

detector_confidencefloat (optional, default: 0.4)

Minimum confidence for the detector to consider something a license plate. This is separate from min_confidence, which instead filters the result of the OCR reading.

Lowest value: 0

Highest value: 1

ocr_modelselect (optional, default: cct-xs-v2-global-model)

Which OCR model to use to read the characters of a detected license plate. See models for more information on this.

Valid values:

cct-s-v2-global-model
cct-xs-v2-global-model
cct-s-v1-global-model
cct-xs-v1-global-model
cct-s-relu-v1-global-model
cct-xs-relu-v1-global-model
argentinian-plates-cnn-model
argentinian-plates-cnn-synth-model
european-plates-mobile-vit-v2-model
global-plates-mobile-vit-v2-model

deviceselect (optional, default: auto)

Device used to run inference on.
auto lets ONNX Runtime pick the best available provider. cuda requires an NVIDIA GPU with CUDA/cuDNN available, and is only bundled in the amd64-cuda image. On all other images the CUDA provider is unavailable and inference falls back to the CPU.

Valid values:

auto
cpu
cuda

discard_unrecognized_platesboolean (optional, default: true)

The OCR model can detect a license plate-shaped region but fail to read any characters from it, returning an empty plate text. This can happen even when min_confidence is set high, since the model's confidence in this case does not reflect whether any characters were actually read. If true, these empty results are discarded instead of being reported as a detection.

License plate recognition

License plate recognition runs as a post processor when a specific object is detected.

You can track known license plates by adding them to the known_plates list in the configuration. Known plates will be reported as binary sensors.

There is also a sensor entity that reports all the plates that have been detected. This can be used to trigger actions in other platforms, eg Home Assistant, when an unknown plate is detected.

Models

fastALPR uses two separate ONNX models: a detector model that locates license plates in the image, and an OCR model that reads the characters of a detected plate.

detector_model is a yolo-v9-*-license-plate-end2end model. The number in the name is the input resolution the model runs at, e.g. yolo-v9-t-384 resizes its input to 384x384. Higher resolutions (e.g. yolo-v9-s-608) are more accurate at finding small/distant plates but slower, while lower resolutions (e.g. yolo-v9-t-256) are faster but may miss smaller plates.

ocr_model reads the characters from the plate crop found by the detector. cct-*-global-model and global-plates-mobile-vit-v2-model are trained on plates from many regions/formats. european-plates-mobile-vit-v2-model and argentinian-plates-* are trained on region-specific plate formats and can be more accurate if your plates match one of those regions. xs and relu variants trade some accuracy for faster inference.

Troubleshooting

To enable debug logging for fastalpr, add the following to your config.yaml

/config/config.yaml
logger:
  logs:
    viseron.components.fastalpr: debug

fastALPR

Configuration​

License plate recognition​

Models​

Troubleshooting​

Configuration

License plate recognition

Models

Troubleshooting