LPR improvements (#20129)

* continue to use paddleocr v3 text detection model for large

v5 was not finding text on multi-line plates at all in testing

* implement clustering of plate variants per event

should reduce OCR inconsistencies and improve plate recognition stability by using string similarity to cluster similar variants (10 per event id) and choosing the highest confidence representative as the final plate

* pass camera

* prune number of variants based on detect fps

* implement replacement rules for cleaning up and normalizing plates

* docs

* docs

docs/docs/configuration/license_plate_recognition.md

@@ -67,12 +67,15 @@ Fine-tune the LPR feature using these optional parameters at the global level of
 - **`min_area`**: Defines the minimum area (in pixels) a license plate must be before recognition runs.
   - Default: `1000` pixels. Note: this is intentionally set very low as it is an _area_ measurement (length x width). For reference, 1000 pixels represents a ~32x32 pixel square in your camera image.
   - Depending on the resolution of your camera's `detect` stream, you can increase this value to ignore small or distant plates.
-- **`device`**: Device to use to run license plate detection *and* recognition models.
+- **`device`**: Device to use to run license plate detection _and_ recognition models.
   - Default: `CPU`
-  - This can be `CPU` or one of [onnxruntime's provider options](https://onnxruntime.ai/docs/execution-providers/). For users without a model that detects license plates natively, using a GPU may increase performance of the models, especially the YOLOv9 license plate detector model. See the [Hardware Accelerated Enrichments](/configuration/hardware_acceleration_enrichments.md) documentation.
-- **`model_size`**: The size of the model used to detect text on plates.
+  - This can be `CPU`, `GPU`, or the GPU's device number. For users without a model that detects license plates natively, using a GPU may increase performance of the YOLOv9 license plate detector model. See the [Hardware Accelerated Enrichments](/configuration/hardware_acceleration_enrichments.md) documentation. However, for users who run a model that detects `license_plate` natively, there is little to no performance gain reported with running LPR on GPU compared to the CPU.
+- **`model_size`**: The size of the model used to identify regions of text on plates.
   - Default: `small`
-  - This can be `small` or `large`. The `large` model uses an enhanced text detector and is more accurate at finding text on plates but slower than the `small` model. For most users, the small model is recommended. For users in countries with multiple lines of text on plates, the large model is recommended. Note that using the large model does not improve _text recognition_, but it may improve _text detection_.
+  - This can be `small` or `large`.
+  - The `small` model is fast and identifies groups of Latin and Chinese characters.
+  - The `large` model identifies Latin characters only, but uses an enhanced text detector and is more capable at finding characters on multi-line plates. It is significantly slower than the `small` model. Note that using the `large` model does not improve _text recognition_, but it may improve _text detection_.
+  - For most users, the `small` model is recommended.
 
 ### Recognition
 
@@ -102,6 +105,32 @@ Fine-tune the LPR feature using these optional parameters at the global level of
   - This setting is best adjusted at the camera level if running LPR on multiple cameras.
   - If Frigate is already recognizing plates correctly, leave this setting at the default of `0`. However, if you're experiencing frequent character issues or incomplete plates and you can already easily read the plates yourself, try increasing the value gradually, starting at 5 and adjusting as needed. You should see how different enhancement levels affect your plates. Use the `debug_save_plates` configuration option (see below).
 
+### Normalization Rules
+
+- **`replace_rules`**: List of regex replacement rules to normalize detected plates. These rules are applied sequentially. Each rule must have a `pattern` (which can be a string or a regex, prepended by `r`) and `replacement` (a string, which also supports [backrefs](https://docs.python.org/3/library/re.html#re.sub) like `\1`). These rules are useful for dealing with common OCR issues like noise characters, separators, or confusions (e.g., 'O'→'0').
+
+These rules must be defined at the global level of your `lpr` config.
+
+```yaml
+lpr:
+  replace_rules:
+    - pattern: r'[%#*?]' # Remove noise symbols
+      replacement: ""
+    - pattern: r'[= ]' # Normalize = or space to dash
+      replacement: "-"
+    - pattern: "O" # Swap 'O' to '0' (common OCR error)
+      replacement: "0"
+    - pattern: r'I' # Swap 'I' to '1'
+      replacement: "1"
+    - pattern: r'(\w{3})(\w{3})' # Split 6 chars into groups (e.g., ABC123 → ABC-123)
+      replacement: r'\1-\2'
+```
+
+- Rules fire in order: In the example above: clean noise first, then separators, then swaps, then splits.
+- Backrefs (`\1`, `\2`) allow dynamic replacements (e.g., capture groups).
+- Any changes made by the rules are printed to the LPR debug log.
+- Tip: You can test patterns with tools like regex101.com.
+
 ### Debugging
 
 - **`debug_save_plates`**: Set to `True` to save captured text on plates for debugging. These images are stored in `/media/frigate/clips/lpr`, organized into subdirectories by `<camera>/<event_id>`, and named based on the capture timestamp.
@@ -136,6 +165,9 @@ lpr:
   recognition_threshold: 0.85
   format: "^[A-Z]{2} [A-Z][0-9]{4}$" # Only recognize plates that are two letters, followed by a space, followed by a single letter and 4 numbers
   match_distance: 1 # Allow one character variation in plate matching
+  replace_rules:
+    - pattern: "O"
+      replacement: "0" # Replace the letter O with the number 0 in every plate
   known_plates:
     Delivery Van:
       - "RJ K5678"

docs/docs/configuration/reference.md

@@ -661,6 +661,8 @@ lpr:
   enhancement: 0
   # Optional: Save plate images to /media/frigate/clips/lpr for debugging purposes (default: shown below)
   debug_save_plates: False
+  # Optional: List of regex replacement rules to normalize detected plates (default: shown below)
+  replace_rules: {}
 
 # Optional: Configuration for AI generated tracked object descriptions
 # WARNING: Depending on the provider, this will send thumbnails over the internet