Improve lpr and speed zone docs

docs/docs/configuration/license_plate_recognition.md

@@ -3,13 +3,27 @@ id: license_plate_recognition
 title: License Plate Recognition (LPR)
 ---
 
-Frigate can recognize license plates on vehicles and automatically add the detected characters 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 with a dedicated LPR camera.
+Frigate can recognize license plates on vehicles and automatically add the detected characters or recognized 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.
+
+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 detected characters or recognized name is:
+
+- Added as a `sub_label` to the `car` tracked object.
+- Viewable in the Tracked Object Details pane and filterable through the More Filters menu in Explore
+- Published via the `frigate/events` MQTT topic as a `sub_label` for the tracked object.
+
+## Model Requirements
 
 Users running a Frigate+ model (or any custom model that natively detects license plates) should ensure that `license_plate` is added to the [list of objects to track](https://docs.frigate.video/plus/#available-label-types) either globally or for a specific camera. This will improve the accuracy and performance of the LPR model.
 
-Users without a model that detects license plates can still run LPR. A small, CPU inference, YOLOv9 license plate detection model will be used instead. You should _not_ define `license_plate` in your list of objects to track.
+Users without a model that detects license plates can still run LPR. Frigate uses a lightweight YOLOv9 license plate detection model that runs on your CPU. In this case, you should _not_ define `license_plate` in your list of objects to track.
 
-LPR is most effective when the vehicle’s license plate is fully visible to the camera. For moving vehicles, Frigate will attempt to read the plate continuously, refining recognition and keeping the most confident result. LPR will not run on stationary vehicles.
+:::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.
+
+:::
 
 ## Minimum System Requirements
 
@@ -24,6 +38,8 @@ 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.
+
 ## Advanced Configuration
 
 Fine-tune the LPR feature using these optional parameters:
@@ -41,21 +57,22 @@ Fine-tune the LPR feature using these optional parameters:
 
 - **`recognition_threshold`**: Recognition confidence score required to add the plate to the object as a sub label.
   - Default: `0.9`.
-- **`min_plate_length`**: Specifies the minimum number of characters a detected license plate must have to be added as a sub-label to an object.
+- **`min_plate_length`**: Specifies the minimum number of characters a detected license plate must have to be added as a sub label to an object.
   - Use this to filter out short, incomplete, or incorrect detections.
 - **`format`**: A regular expression defining the expected format of detected plates. Plates that do not match this format will be discarded.
   - `"^[A-Z]{1,3} [A-Z]{1,2} [0-9]{1,4}$"` matches plates like "B AB 1234" or "M X 7"
   - `"^[A-Z]{2}[0-9]{2} [A-Z]{3}$"` matches plates like "AB12 XYZ" or "XY68 ABC"
+  - Websites like https://regex101.com/ can help test regular expressions for your plates.
 
 ### Matching
 
 - **`known_plates`**: List of strings or regular expressions that assign custom a `sub_label` to `car` objects when a recognized plate matches a known value.
   - These labels appear in the UI, filters, and notifications.
 - **`match_distance`**: Allows for minor variations (missing/incorrect characters) when matching a detected plate to a known plate.
   - For example, setting `match_distance: 1` allows a plate `ABCDE` to match `ABCBE` or `ABCD`.
-  - This parameter will not operate on known plates that are defined as regular expressions. You should define the full string of your plate in `known_plates` in order to use `match_distance`.
+  - This parameter will _not_ operate on known plates that are defined as regular expressions. You should define the full string of your plate in `known_plates` in order to use `match_distance`.
 
-### Examples
+## Configuration Examples
 
 ```yaml
 lpr:
@@ -69,20 +86,64 @@ lpr:
     Johnny:
       - "J*N-*234" # Matches JHN-1234 and JMN-I234, but also note that "*" matches any number of characters
     Sally:
-      - "[S5]LL-1234" # Matches both SLL-1234 and 5LL-1234
+      - "[S5]LL 1234" # Matches both SLL 1234 and 5LL 1234
+    Work Trucks:
+      - "EMP-[0-9]{3}[A-Z]" # Matches plates like EMP-123A, EMP-456Z
 ```
 
 ```yaml
 lpr:
   enabled: True
   min_area: 4000 # Run recognition on larger plates only
   recognition_threshold: 0.85
-  format: "^[A-Z]{3}-[0-9]{4}$" # Only recognize plates that are three letters, followed by a dash, followed by 4 numbers
+  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
   known_plates:
     Delivery Van:
-      - "RJK-5678"
-      - "UPS-1234"
-    Employee Parking:
-      - "EMP-[0-9]{3}[A-Z]" # Matches plates like EMP-123A, EMP-456Z
+      - "RJ K5678"
+      - "UP A1234"
+    Supervisor:
+      - "MN D3163"
 ```
+
+## FAQ
+
+### Why isn't my license plate being detected and recognized?
+
+Ensure that:
+
+- Your camera has a clear, well-lit view of the plate.
+- The plate is large enough in the image (try adjusting `min_area`).
+- 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.
+
+### How can I improve detection accuracy?
+
+- Use high-quality cameras with good resolution.
+- Adjust `detection_threshold` and `recognition_threshold` values.
+- Define a `format` regex to filter out invalid detections.
+
+### Does LPR work at night?
+
+Yes, but performance depends on camera quality, lighting, and infrared capabilities. Make sure your camera can capture clear images of plates at night.
+
+### How can I match known plates with minor variations?
+
+Use `match_distance` to allow small character mismatches. Alternatively, define multiple variations in `known_plates`.
+
+### How do I debug LPR issues?
+
+- View MQTT messages for `frigate/events` to verify detected plates.
+- Adjust `detection_threshold` and `recognition_threshold` settings.
+- If you are using a Frigate+ model or a model that detects license plates, watch the debug view (Settings --> Debug) to ensure that `license_plate` is being detected with a `car`.
+- Enable debug logs for LPR by adding `frigate.data_processing.real_time.license_plate_processor: debug` to your `logger` configuration. These logs are _very_ verbose, so only enable this when necessary.
+
+### 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.

docs/docs/configuration/zones.md

@@ -140,20 +140,22 @@ cameras:
     zones:
       street:
         coordinates: 0.033,0.306,0.324,0.138,0.439,0.185,0.042,0.428
-        distances: 10,12,11,13.5
+        distances: 10,12,11,13.5 # in meters or feet
 ```
 
 Each number in the `distance` field represents the real-world distance between the points in the `coordinates` list. So in the example above, the distance between the first two points ([0.033,0.306] and [0.324,0.138]) is 10. The distance between the second and third set of points ([0.324,0.138] and [0.439,0.185]) is 12, and so on. The fastest and most accurate way to configure this is through the Zone Editor in the Frigate UI.
 
-The `distance` values are measured in meters or feet, depending on how `unit_system` is configured in your `ui` config:
+The `distance` values are measured in meters (metric) or feet (imperial), depending on how `unit_system` is configured in your `ui` config:
 
 ```yaml
 ui:
   # can be "metric" or "imperial", default is metric
   unit_system: metric
 ```
 
-The average speed of your object as it moved through your zone is saved in Frigate's database and can be seen in the UI in the Tracked Object Details pane in Explore. Current estimated speed can also be seen on the debug view as the third value in the object label (see the caveats below). Current estimated speed, average estimated speed, and velocity angle (the angle of the direction the object is moving relative to the frame) of tracked objects is also sent through the `events` MQTT topic. See the [MQTT docs](../integrations/mqtt.md#frigateevents). These speed values are output as a number in miles per hour (mph) or kilometers per hour (kph), depending on how `unit_system` is configured in your `ui` config.
+The average speed of your object as it moved through your zone is saved in Frigate's database and can be seen in the UI in the Tracked Object Details pane in Explore. Current estimated speed can also be seen on the debug view as the third value in the object label (see the caveats below). Current estimated speed, average estimated speed, and velocity angle (the angle of the direction the object is moving relative to the frame) of tracked objects is also sent through the `events` MQTT topic. See the [MQTT docs](../integrations/mqtt.md#frigateevents).
+
+These speed values are output as a number in miles per hour (mph) or kilometers per hour (kph). For miles per hour, set `unit_system` to `imperial`. For kilometers per hour, set `unit_system` to `metric`.
 
 #### Best practices and caveats