Overhauled real-time ALPR

CHANGELOG.md

@@ -302,7 +302,7 @@ This update refines Predator's functionality, and focuses its purpose back on li
 
 ## Version 9.0
 
-### Name To Be Determined 
+### Performance Update
 
 *Release date to be determined*
 
@@ -327,6 +327,16 @@ This update refines Predator's functionality, and focuses its purpose back on li
 - Improved dashcam recording.
     - Fixed an issue where dashcam recording would cause a crash when displaying the process start message.
     - Added support for OpenCV recording.
-- Entries are now only added to the license plate history log file if one or more license plates were detected.
 - Added support for multiple license plate validation formats.
-- Fixed an issue where Predator would reference a non-existent configuration value when object recognition was enabled in real-time mode.
+- Overhauled real-time mode.
+    - Entries are now only added to the license plate history log file if one or more license plates were detected.
+    - Real-time mode now streams constant video from the configured camera, rather than capturing discrete still frames.
+        - This dramatically improves the likelihood of plate detection, especially under challenging conditions.
+    - Removed several features to accomodate constant ALPR video streaming.
+        - Removed image post-processing.
+        - Removed image saving.
+        - Removed real-time object recognition.
+    - Refined the real-time mode interface to better accomodate multiple plates being displayed at once.
+- Simplified the configuration.
+    - Removed the `detected_plate_count` configuration value from the real-time display section.
+        - The number of plates detected is now always displayed in the console output.

CONFIGURATION.md

@@ -17,19 +17,24 @@ This section of configuration values will effect Predator's general operation.
 - `alpr` contains settings related to license plate recognition.
     - `engine` is a string that determines what ALPR engine Predator will use.
         - This can be set to either `"openalpr"` or `"phantom"`.
-    - `guesses` is an integer that determines how many guesses the ALPR engine will make when analyzing a plate.
-        - The higher this number is, the more likely Predator is to guess a plate incorrectly. The lower this number is, the less likely Predator will be to find a valid guess at all.
-    - `license_plate_format` is a list of strings that provide Predator with examples of how license plates in your region should be formatted.
-        - For example, license plates in the state of Ohio generally follow the pattern of 3 letters followed by 4 numbers. In Ohio, this preference might contain `"AAA0000"` to filter out plate guesses that don't match the most common formatting pattern.
-        - This preference only considers the type of each character, not the character itself.
-            - In other words, `AAA0000` and `ABC1234` will function identically.
-            - This also means you can simply enter any given plate from a car located in the region you're scanning in to have a reasonably good chance at matching your region's formatting guidelines for license plates.
-        - Leaving this as an empty list disable license plate format validation.
+    - `validation` contains settings for validating license plate candidates/guesses.
+        - `guesses` is an integer that determines how many guesses the ALPR engine will make when analyzing a plate.
+            - The higher this number is, the more likely Predator is to guess a plate incorrectly. The lower this number is, the less likely Predator will be to find a valid guess at all.
+        - `license_plate_format` is a list of strings that provide Predator with examples of how license plates in your region should be formatted.
+            - For example, license plates in the state of Ohio generally follow the pattern of 3 letters followed by 4 numbers. In Ohio, this preference might contain `"AAA0000"` to filter out plate guesses that don't match the most common formatting pattern.
+            - This preference only considers the type of each character, not the character itself.
+                - In other words, `AAA0000` and `ABC1234` will function identically.
+                - This also means you can simply enter any given plate from a car located in the region you're scanning in to have a reasonably good chance at matching your region's formatting guidelines for license plates.
+            - Leaving this as an empty list disable license plate format validation.
+        - `best_effort` is a boolean that determines whether Predator will accept the most confident guess when none of the guesses match the license plate validation format(s).
+            - When set to `true`, Predator will not completely discard license plate detections that don't have any guesses aligning with the license plate validation format(s), and will instead simply accept the best guess for plates that would otherwise be considered invalid.
+            - When set to `false`, Predator will discard plates that don't have any valid guesses, based on the validation format(s).
+            - This setting does not override `general>alerts>alerts_ignore_validation`, and can be set to `false` without interferring with license plate hotlist alerts.
 - `alerts` contains settings related to license plate alerting.
-    - `alerts_ignore_validation` is a boolean determines whether alerts will respect or ignore the plate validation format.
+    - `alerts_ignore_validation` is a boolean that determines whether alerts will respect or ignore the plate validation format.
         - When this is set to `true`, if a plate fails the validation test, but matches an alert database plate, the alert will be displayed anyway.
         - When set to `false`, only plates that have passed the validation test will be checked against the alert database.
-    - `allow_duplicate_alerts` is a boolean determines whether a single license plate can trigger multiple alert rules.
+    - `allow_duplicate_alerts` is a boolean that determines whether a single license plate can trigger multiple alert rules.
         - Setting this to `true` will cause Predator to check all guesses against all alert rules. This can lead to situations where alert rules with wildcards cause a single license plate to alert repeatedly, for each of its guesses.
     - `databases` is a list that contains strings, with each string pointing to either a local or remote license plate hot-list.
         - If a particular entry in this list is a file, the file path should be relative to the working directory.
@@ -44,6 +49,9 @@ This section of configuration values will effect Predator's general operation.
     - `silence_file_saving` is a boolean that determines whether or not Predator will display informational messages when saving files.
     - `debugging_output` is a boolean that determines whether or not Predator will display debugging messages through-out normal operation.
         - When this is set to `true`, console clearing is automatically disabled.
+- `object_recognition` contains settings related to Predator's object recogntion capabilities.
+    - `enabled` is a boolean that determines whether or not object recognition is enabled globally.
+        - Setting this to `false` removes Predator's dependency on Tensorflow and OpenCV.
 - `modes` contains settings related to Predator's operating modes.
     - `auto_start` is a string that determines which mode (if any) Predator will automatically load into upon start-up.
         - There are 4 possible values this can be set to, not including being left blank.
@@ -91,8 +99,8 @@ Configuration values in this section are settings specific to real-time mode.
 
 - `interface` contains settings related to the command line interface.
     - `display` contains settings related to what information is displayed.
-        - `show_invalid_plates` is a boolean that determines whether or not Predator will print every guess it makes as to the contents of a license plates, even if those guesses are invalidated by the license plate format sample.
-        - `detected_plate_count` is a boolean that determines whether or not Predator will show how many plates were detected each frame while operating in real-time mode.
+        - `show_validation` is a boolean that determines whether or not Predator will print every guess it makes as to the contents of a license plates, even if those guesses are invalidated by the license plate format sample.
+            - This setting doesn't change anything practically, but makes it easier to understand how Predator is filtering invalid license plate guesses.
         - `shape_alerts` is a boolean that determines whether or not large ASCII shapes will be printed to the console to indicate certain important events at a glance.
         - `output_level` is an integer that determines how verbose Predator's console output will be.
             - This setting only has 3 different options.
@@ -118,24 +126,8 @@ Configuration values in this section are settings specific to real-time mode.
     - `alpr_location_tagging` is a boolean that determines whether or not the current GPS location will be saved to the log file each time a plate is logged.
 - `image` contains settings related to image handling.
     - `camera` contains settings related to image capture.
-        - `resoultion` determines the maximum resolution that images will be captured with, and is a string that takes the format of `[width]x[height]`.
-            - Example: `"1920x1080"`
         - `device` specifies the camera device that will be used to capture images.
             - Example: `"/dev/video0"`
-        - `arguments` specifies custom command line arguments that will be added to the FSWebcam command. This setting is entirely optional.
-            - Example: `"--set brightness=100% -F 15 -S 5"`
-        - `file_name` is a string that specifies the file name that will be assigned to the captured image, not including the extension.
-            - Example: `"realtime_image"`
-    - `processing` contains settings related to image processing.
-        - `cropping` contains settings regarding image cropping.
-            - `enabled` determines whether image cropping is enabled in real-time mode.
-            - `left_margin` determines how many pixels will be cropped off of the left side of the frame.
-            - `right_margin` determines how many pixels will be cropped off of the right side of the frame.
-            - `bottom_margin` determines how many pixels will be cropped off of the bottom of the frame.
-            - `top_margin` determines how many pixels will be cropped off of the top of the frame.
-        - `rotation` contains settings regarding image cropping.
-            - `enabled` determines whether image rotation is enabled in real-time mode.
-            - `angle` determines the number of degrees clockwise that the image will be rotated.
 - `sounds` contains the sound effects that Predator can play when certain events occur.
     - Each entry in this section has 3 attributes.
         - The `path` value should be set to the file path of the audio file you want to play.
@@ -155,11 +147,6 @@ Configuration values in this section are settings specific to real-time mode.
         - This file is created in the working directory.
         - When this value is left as a blank string, license plate logging will be disabled.
         - Example: `"plate_history.json"`
-    - `object_recognition` is a string that determines the JSON file name will use to save the objects it detects in real-time mode.
-        - This file is created in the working directory.
-        - When this value is left as a blank string, object recognition logging will be disabled. However, this does not disable object recognition in itself, and detected objects will still be displayed in the console.
-        - Example: `"object_history.json"`
-    - `images` is a boolean that determines whether or not Predator will save every image it captures, instead of repeatedly overwriting a single image.
 - `push_notifications`
     - `enabled`
         - This setting determines whether or not Predator will attempt to send push notifications using a Gotify server.

DOCUMENTATION.md

@@ -38,33 +38,29 @@ This is the installation process for Predator and all of it's dependencies. This
     - Predator uses FFMPEG to process videos.
     - If you don't install FFMPEG, Predator will encounter errors while operating in modes that require video processing.
     - You can install FFMPEG using the following command on a Debian based Linux machine: `sudo apt-get install ffmpeg`
-4. Optionally, install FSWebcam (Highly Recommended)
-    - Predator uses FSWebcam to access connected cameras.
-    - If you don't install FSWebcam, Predator will encounter errors while operating in modes that require accessing USB cameras.
-    - You can install FSWebcam using the following command on a Debian based Linux machine: `sudo apt-get install fswebcam`
-5. Optionally, install ImageMagick (Highly Recommended)
+4. Optionally, install ImageMagick (Highly Recommended)
     - Predator uses ImageMagick to manipulate still frames of video.
     - If you don't install ImageMagick, Predator will encounter errors while operating in modes that require image processing.
     - You can learn about the ImageMagick installation process at <https://imagemagick.org/script/download.php>
-6. Optionally, install MPG321 (Recommended)
+5. Optionally, install MPG321 (Recommended)
     - Predator requires MPG321 in order to play audio effects for alerts.
     - If you don't install MPG321, Predator will encounter errors when audio alerts are enabled in the configuration.
     - You can install MPG321 using the following command on a Debian based Linux machine: `sudo apt-get install mpg321`
-7. Optionally, install GPSD (Recommended)
+6. Optionally, install GPSD (Recommended)
     - GPSD is required for Predator to receive GPS data.
     - If you don't install GPSD, Predator will encounter errors when GPS features are enabled in the configuration.
     - You can install GPSD using this command on a Debian based Linux machine: `sudo apt-get install gpsd gpsd-clients`
     - It may also be necessary to start GPSD. You can test to see if GPSD is working properly using the `cgps` command.
-8. Optionally, install remote access software.
+7. Optionally, install remote access software.
     - If you're installing Predator on a Raspberry Pi, you may find it useful to install a program like [RaspAP](https://github.com/RaspAP/raspap-webgui) (or similar program) in order to remotely manage your Predator instance, and eliminate the need for a full keyboard and display.
     - Predator works entirely via command line, meaning any set up that enables SSH access to the host will allow for remote management of Predator.
     - If you already have an access point installed in the same area as Predator, you can simply connect Predator to it, and use SSH on a separate device to access the instance remotely.
-9. Download Predator.
-    - Predator can be downloaded either from the V0LT website, or from it's GitHub page. The download straight from the V0LT website is recommended for sake of stability and completeness, but you're free to use GitHub as well if you're OK with using a less stable version of Predator.
+8. Download Predator.
+    - Predator can be downloaded either from the V0LT website, or from it's GitHub page. The download straight from the V0LT website is recommended for sake of stability and completeness, but you're free to use GitHub as well if you're OK with using an unstable and potentially broken version of Predator.
     - V0LT website: <https://v0lttech.com/predator.php>
     - GitHub page: <https://github.com/connervieira/Predator>
         - `git clone https://github.com/connervieira/Predator`
-10. Extract Predator
+9. Extract Predator
     - After downloading Predator, regardless of where you get it from, extract it from the compressed archive (if necessary), and place it somewhere on your filesystem.
 
 
@@ -112,7 +108,7 @@ After configuring Predator, you can try it out for the first time!
             - You can use this mode to analyze dash-cam video, whether it be from a generic dash-cam or from Predator running in dash-cam mode.
         - Real-time mode (Mode 2)
             - In this mode, Predator will use a connected camera to detect license plates in real-time.
-            - In real-time mode, Predator will repeatedly take still frames to analyze, and will not record video.
+            - In real-time mode, Predator will stream video from a connected camera directly.
         - Dash-cam mode (Mode 3)
             - In this mode, Predator will operate like a dash-cam, and simply record video without analyzing it.
             - This mode can be used to record video to be used analyzed with pre-recorded mode later.
@@ -168,13 +164,10 @@ After configuring Predator, you can try it out for the first time!
         - Real-time mode
             - While in real-time mode, Predator will run in an endless loop until quit by holding `Ctrl + C` for a few seconds.
                 - Since Predator launches some of it's processes in different threads, pressing `Ctrl + C` a single time might not kill the entire Predator system.
-            - When a license plate is detected, Predator will display it on screen.
-                - Depending on the preferences, Predator might also display a large ASCII shape to make it easier to see important information at a glance.
-                - Depending on the preferences, Predator might play an audio sound indicating the type of plate detected.
-                - Depending on the preferences, Predator might submit the license plate detected to a push notification service.
-                - Depending on the preferences for the session, Predator might also save images taken and the license plates detected.
-                    - Images taken will be saved as `realtime_imageN.jpg` in the working directory. If saving images is turned on, 'N' with the sequential image number. Otherwise, the N will be removed.
-                    - Detected license plates will be saved to disk in the working directory, provided license plate saving is enabled in the configuration.
+            - When one or more license plates are detected, Predator will display it on screen, provided that it is configured to do so.
+                - Depending on the configuration, Predator might also display a large ASCII shape to make it easier to see important information at a glance.
+                - Depending on the configuration, Predator might play an audio sound indicating the type of plate detected.
+                - Depending on the configuration, Predator might submit the license plate detected to a push notification service.
                 - If a plate detected is in the alert database specified during the preferences stage earlier, it will show a prominent alert message in the console output.
         - Dash-cam mode
             - In dash-cam mode, Predator will record video indefinitely until disk space runs out, the return key is pressed, or the Predator process is terminated.

TODO.md

@@ -63,11 +63,4 @@ These are the features actively planned for Predator and are likely to be added
 - [X] Add configuration value for the number of guesses the ALPR engine should make in pre-recorded mode.
 - [X] Organize configuration.
 - [X] Add support for multiple license plate formats.
-- [ ] Test updated license plate validation in real-time mode.
-
-
-# Hypothetical
-
-These are features that may require more in-depth changes, and are purely hypothetical.
-
-- [ ] A GUI front-end in addition to the existing command line interface.
+- [X] Test updated license plate validation in real-time mode.