docs

docs/docs/configuration/license_plate_recognition.md

@@ -3,16 +3,17 @@ id: license_plate_recognition
 title: License Plate Recognition (LPR)
 ---
 
-Frigate can recognize license plates on vehicles and automatically add the detected characters to the `recognized_license_plate` field or a known name as a `sub_label` to objects that are of type `car`. A common use case may be to read the license plates of cars pulling into a driveway or cars passing by on a street.
+Frigate can recognize license plates on vehicles and automatically add the detected characters to the `recognized_license_plate` field or a known name as a `sub_label` to tracked objects of type `car`. A common use case may be to read the license plates of cars pulling into a driveway or cars passing by on a street.
 
 LPR works best when the license plate is clearly visible to the camera. For moving vehicles, Frigate continuously refines the recognition process, keeping the most confident result. However, LPR does not run on stationary vehicles.
 
 When a plate is recognized, the recognized name is:
 
-- Added to the `car` tracked object as a `sub_label` (if known) or the `recognized_license_plate` field (if unknown)
-- Viewable in the Review Item Details pane in Review and the Tracked Object Details pane in Explore.
+- Added as a `sub_label` (if known) or the `recognized_license_plate` field (if unknown) to a tracked object.
+- Viewable in the Review Item Details pane in Review (sub labels).
+- Viewable in the Tracked Object Details pane in Explore (sub labels and recognized license plates).
 - Filterable through the More Filters menu in Explore.
-- Published via the `frigate/events` MQTT topic as a `sub_label` (known) or `recognized_license_plate` (unknown) for the tracked object.
+- Published via the `frigate/events` MQTT topic as a `sub_label` (known) or `recognized_license_plate` (unknown) for the `car` tracked object.
 
 ## Model Requirements
 
@@ -22,7 +23,7 @@ Users without a model that detects license plates can still run LPR. Frigate use
 
 :::note
 
-Frigate needs to first detect a `car` before it can recognize a license plate. If you're using a dedicated LPR camera or have a zoomed-in view, make sure the camera captures enough of the `car` for Frigate to detect it reliably.
+In the default mode, Frigate's LPR needs to first detect a `car` before it can recognize a license plate. If you're using a dedicated LPR camera and have a zoomed-in view where a `car` will not be detected, you can still run LPR, but the configuration parameters will differ from the default mode. See the Dedicated LPR Camera section below.
 
 :::
 
@@ -39,7 +40,17 @@ lpr:
   enabled: True
 ```
 
-Ensure that your camera is configured to detect objects of type `car`, and that a car is actually being detected by Frigate. Otherwise, LPR will not run.
+You can also enable it for specific cameras only at the camera level:
+
+```yaml
+cameras:
+  driveway:
+    ...
+    lpr:
+      enabled: True
+```
+
+For non-dedicated LPR cameras, ensure that your camera is configured to detect objects of type `car`, and that a car is actually being detected by Frigate. Otherwise, LPR will not run.
 
 Like the other real-time processors in Frigate, license plate recognition runs on the camera stream defined by the `detect` role in your config. To ensure optimal performance, select a suitable resolution for this stream in your camera's firmware that fits your specific scene and requirements.
 
@@ -78,6 +89,8 @@ Fine-tune the LPR feature using these optional parameters:
 
 ## Configuration Examples
 
+These configuration parameters are available at the global level of your config. The only optional parameters that should be set at the camera level are `enabled` and `min_area`.
+
 ```yaml
 lpr:
   enabled: True
@@ -110,6 +123,70 @@ lpr:
       - "MN D3163"
 ```
 
+## Dedicated LPR Cameras
+
+Dedicated LPR cameras are single-purpose cameras with powerful optical zoom to capture license plates on distant vehicles, often with fine-tuned settings to capture plates at night.
+
+Users with a dedicated LPR camera can run Frigate's LPR by specifying a camera type of `lpr` in the camera configuration. An example config for a dedicated LPR camera might look like this:
+
+```yaml
+# LPR global configuration
+lpr:
+  enabled: True
+  min_area: 2000
+  match_distance: 1
+
+# Dedicated LPR camera configuration
+cameras:
+  dedicated_lpr_camera:
+    type: "lpr" # required to use dedicated LPR camera mode
+    lpr:
+      enabled: True
+      expire_time: 3 # optional, default
+    ffmpeg: ...
+    detect:
+      enabled: False # optional, disable Frigate's standard object detection pipeline
+      fps: 5
+      width: 1920
+      height: 1080
+    motion:
+      threshold: 30
+      contour_area: 80 # use an increased value here to tune out small motion changes
+      improve_contrast: false
+      mask: 0.704,0.007,0.709,0.052,0.989,0.055,0.993,0.001 # ensure your camera's timestamp is masked
+    record:
+      enabled: True # disable recording if you only want snapshots
+      detections:
+        enabled: True
+        retain:
+          default: 7
+```
+
+The camera-level `type` setting tells Frigate to treat your camera as a dedicated LPR camera. Setting this option bypasses Frigate's standard object detection pipeline so that a `car` does not need to be detected to run LPR. This dedicated LPR pipeline does not utilize defined zones or object masks, and the license plate detector is always run on the full frame whenever motion activity occurs. If a plate is found, a snapshot at the highest scoring moment is saved as a `car` object, visible in Explore and searchable by the recognized plate via Explore's More Filters.
+
+An optional config variable for dedicated LPR cameras only, `expire_time`, can be specified under the `lpr` configuration at the camera level to change the time it takes for Frigate to consider a previously tracked plate as expired.
+
+:::note
+
+When using `type: "lpr"` for a camera, a non-standard object detection pipeline is used. Any detected license plates on dedicated LPR cameras are treated similarly to manual events in Frigate. Note that for `car` objects with license plates:
+
+- Review items will always be classified as a `detection`.
+- Snapshots will always be saved.
+- Tracked objects are retained according to your retain settings for `record` and `snapshots`.
+- Zones and object masks cannot be used.
+- The `frigate/events` MQTT topic will not publish tracked object updates, though `frigate/reviews` will if recordings are enabled.
+
+:::
+
+### Best practices for using Dedicated LPR camera mode
+
+- Tune your motion detection and increase the `contour_area` until you see only larger motion boxes being created as cars pass through the frame (likely somewhere between 50-90 for a 1920x1080 detect stream). Increasing the `contour_area` filters out small areas of motion and will prevent excessive resource use from looking for license plates in frames that don't even have a car passing through it.
+- Disable the `improve_contrast` motion setting, especially if you are running LPR at night and the frame is mostly dark. This will prevent small pixel changes and smaller areas of motion from triggering license plate detection.
+- Ensure your camera's timestamp is covered with a motion mask so that it's not incorrectly detected as a license plate.
+- While not strictly required, it may be beneficial to disable standard object detection on your dedicated LPR camera (`detect` --> `enabled: False`). If you've set the camera type to `"lpr"`, license plate detection will still be performed on the entire frame when motion occurs.
+- If multiple tracked objects are being produced for the same license plate, you can tweak the `expire_time` to prevent plates from being expired from the view as quickly.
+- You may need to change your camera settings for a clearer image or decrease your global `recognition_threshold` config if your plates are not being accurately recognized at night.
+
 ## FAQ
 
 ### Why isn't my license plate being detected and recognized?
@@ -118,14 +195,13 @@ Ensure that:
 
 - Your camera has a clear, human-readable, well-lit view of the plate. If you can't read the plate, Frigate certainly won't be able to. This may require changing video size, quality, or frame rate settings on your camera, depending on your scene and how fast the vehicles are traveling.
 - The plate is large enough in the image (try adjusting `min_area`) or increasing the resolution of your camera's stream.
-- A `car` is detected first, as LPR only runs on recognized vehicles.
 
 If you are using a Frigate+ model or a custom model that detects license plates, ensure that `license_plate` is added to your list of objects to track.
 If you are using the free model that ships with Frigate, you should _not_ add `license_plate` to the list of objects to track.
 
 ### Can I run LPR without detecting `car` objects?
 
-No, Frigate requires a `car` to be detected first before recognizing a license plate.
+In normal LPR mode, Frigate requires a `car` to be detected first before recognizing a license plate. If you have a dedicated LPR camera, you can change the camera `type` to `"lpr"` to use the Dedicated LPR Camera algorithm. This comes with important caveats, though. See the Dedicated LPR Cameras section above.
 
 ### How can I improve detection accuracy?
 
@@ -150,4 +226,4 @@ Use `match_distance` to allow small character mismatches. Alternatively, define
 
 ### Will LPR slow down my system?
 
-LPR runs on the CPU, so performance impact depends on your hardware. Ensure you have at least 4GB RAM and a capable CPU for optimal results.
+LPR runs on the CPU, so performance impact depends on your hardware. Ensure you have at least 4GB RAM and a capable CPU for optimal results. If you are running the Dedicated LPR Camera mode, resource usage will be higher compared to users who run a model that natively detects license plates. Tune your motion detection settings for your dedicated LPR camera so that the license plate detection model runs only when necessary.

docs/docs/configuration/reference.md

@@ -562,6 +562,7 @@ face_recognition:
   blur_confidence_filter: True
 
 # Optional: Configuration for license plate recognition capability
+# NOTE: enabled and min_area can be overridden at the camera level
 lpr:
   # Optional: Enable license plate recognition (default: shown below)
   enabled: False
@@ -656,6 +657,8 @@ cameras:
     # If disabled: config is used but no live stream and no capture etc.
     # Events/Recordings are still viewable.
     enabled: True
+    # Optional: camera type used for some Frigate features (default: shown below)
+    type: "generic"
     # Required: ffmpeg settings for the camera
     ffmpeg:
       # Required: A list of input streams for the camera. See documentation for more information.

frigate/config/classification.py

@@ -130,6 +130,7 @@ class CameraLicensePlateRecognitionConfig(FrigateBaseModel):
     expire_time: int = Field(
         default=3,
         title="Expire plates not seen after number of seconds (for dedicated LPR cameras only).",
+        gt=0,
     )
     min_area: int = Field(
         default=1000,