Merge branch 'main' of Predator

APEX.md

@@ -1,19 +1,20 @@
 # Apex
 
-This document briefly explains Predator Apex: the paid hardware program for Predator.
+This document briefly explains Predator Apex: the paid support program for Predator.
 
 To inquire about any of the services described here, you can contact V0LT using the information found at <https://v0lttech.com/contact.php>.
 
+
 ## Installation Services
 
 Apex installation services can get you a working Predator ALPR/dashcam system with the least amount of effort. As long as you're within driving distance of V0LT (in Chesterland Ohio), you can have your Predator system assembled, configured, and installed by V0LT directly.
 
 
 ## Hardware Services
 
-If you're a technical user who wants to build a customized Predator system, but you want a starting point to build from, hardware services might be a great option. Apex hardware services allow you to purchase pre-assembled kits that contain all of the basic components you'll need to do your own installation. These kits contain detailed installation instructions, and can be customized based on your preferences and use-case.
+If you're a technical user who wants to build a customized Predator system, but you want a starting point to build from, hardware services might be a great option. Apex hardware services allow you to purchase pre-assembled kits that contain all of the basic components you'll need to do your own installation. These kits contain detailed installation instructions, and can be customized based on your preferences and use-case. To learn more, see <https://v0lttech.com/products/predatorowl.php>
 
 
 ## Support Services
 
-Support services allow you to build your own Predator system from scratch with the guidance of V0LT. Support services include extensive, start-to-finish support over email, phone, or instant messaging. Whether you want to build a basic Predator system, or you have a highly specific use-case, support services can be a very affordable way to get everything set-up how you want it.
+Support services allow you to build your own Predator system from scratch with the guidance of V0LT. Support services include extensive, start-to-finish support over email, phone, or instant messaging. Whether you want to build a basic Predator system, or you have a highly specific use-case, support services can be a very affordable way to get everything set-up exactly how you want it.

CHANGELOG.md

@@ -497,6 +497,7 @@ This update emphasizes improving the reliability of Predator, especially when op
 - Updated configuration back-end.
     - Increased the max-depth of the configuration validation process.
     - Predator can now automatically update the configuration file between versions when configuration values are added or removed.
+    - Improve the reliability of the configuration file location when starting Predator from an external tool, like Assassin.
 - Added an initial start-up sequence, where Predator shows some basic information before the normal start-up.
     - Predator now creates a file named `install.json` containing some basic install information on the first start-up.
 - Updated the ALPR handler.
@@ -515,3 +516,4 @@ This update emphasizes improving the reliability of Predator, especially when op
         - Previously, the time offset manager thread would keep Predator alive after using the "Quit" option.
     - All threads now watch a global variable, and will exit when it is changed.
         - This means the user can simply press Ctrl+C once, and all threads will clean up and exit.
+- Predator now saves the complete loaded alert database to the `hotlist.json` file in the interface directory.

TODO.md

@@ -51,6 +51,7 @@ These are the features actively planned for Predator and are likely to be added
     - [X] Convert plate corners to bounding box.
     - [X] Create file viewer.
 - [X] Implement revised process exiting for real-time mode.
+- [ ] Finish alert documentation (ALERTS.md)
 
 ## Hypothetical
 

alpr.py

@@ -236,6 +236,8 @@ def load_alert_database_remote(source, cache_directory):
     else: # Predator is in offline mode, but a remote alert database source was specified.
         alert_database = {} # Set the alert database to an empty dictionary.
         display_message("A remote alert database source " + source + " was specified, but Predator is in offline mode. This source has not been loaded.", 2)
+
+    save_to_file(config["general"]["interface_directory"] + "/hotlist.json", json.dumps(alert_database, indent=4)) # Save the active alert database to the interface directory.
     return alert_database
 
 def load_alert_database_local(source):
@@ -311,7 +313,7 @@ def generate_dashcam_sidecar_files(working_directory, dashcam_files):
                                 top_guess = result["candidates"][0]["plate"] # Use the most likely plate as the top guess.
                         if (top_guess != ""): # Check to see if the top guess is set for this plate.
                             frame_results[top_guess] = {} # Initialize this plate in the dictionary of plates for this frame.
-                            frame_results[top_guess]["coordinates"] = utils.convert_corners_to_bounding_box(result["coordinates"]) # Add the position of this plate in the image. TODO: Convert to bounding box.
+                            frame_results[top_guess]["coordinates"] = utils.convert_corners_to_bounding_box(result["coordinates"]) # Add the position of this plate in the image.
                     if (len(frame_results) > 0): # Check to see if there is at least one result for this frame.
                         analysis_results[frame_number] = frame_results # Add this frame's data to the full analysis results.
                 save_to_file(sidecar_filepath, json.dumps(analysis_results, indent=4)) # Save the analysis results for this file to the side-car file.

assets/support/configdefault.json

@@ -17,7 +17,7 @@
             "alerts_ignore_validation": true,
             "allow_duplicate_alerts": false,
             "databases": [
-                "https://v0lttech.com/predator/manifest/serve.php?type=hot"
+                "https://v0lttech.com/predator/manifest/serve.php?type=hot&user=cvieira&list=emergencyhotlist"
             ]
         },
         "display": {

config.py

@@ -13,18 +13,19 @@
 import json # Required to process JSON data
 import time
 
+predator_root_directory = str(os.path.dirname(os.path.realpath(__file__))) # This variable determines the folder path of the root Predator directory. This should usually automatically recognize itself, but it if it doesn't, you can change it manually.
 
-config_default_filepath = "./assets/support/configdefault.json"
-config_outline_filepath = "./assets/support/configoutline.json"
-config_active_filepath = "./config.json"
+config_default_filepath = predator_root_directory + "/./assets/support/configdefault.json"
+config_outline_filepath = predator_root_directory + "/./assets/support/configoutline.json"
+config_active_filepath = predator_root_directory + "/./config.json"
 
-if (os.path.exists("./config.json") == False):
-    if (os.path.exists("../config.json") == True):
-        config_active_filepath = "../config.json"
-        config_default_filepath = "../assets/support/configdefault.json"
-        config_outline_filepath = "../assets/support/configoutline.json"
+if (os.path.exists(config_active_filepath) == False):
+    if (os.path.exists(predator_root_directory + "/../config.json") == True):
+        config_active_filepath = predator_root_directory + "/../config.json"
+        config_default_filepath = predator_root_directory + "/../assets/support/configdefault.json"
+        config_outline_filepath = predator_root_directory + "/../assets/support/configoutline.json"
 
-if (os.path.exists(config_active_filepath) == False): # Check to see if the active config filed doesn't exit.
+if (os.path.exists(config_active_filepath) == False): # Check to see if the active config file doesn't exit.
     # Copy the default config file as the active config file.
     with open(config_default_filepath) as configuration_file: config_default= configuration_file.read()
 

docs/ALERTS.md

@@ -0,0 +1,80 @@
+# Alerts
+
+This document explains the format used by Predator alert databases.
+
+## Overview
+
+Predator is capable of loading alert lists from both local files and remote sources. Alert lists come in the form of a JSON dictionary.
+
+Here is a break-down of each value in an alert database:
+
+- `rule`: Each top-level key in the alert database should be a license plate rule that will trigger the alert.
+    - `name`: This is an optional value that contains a human-friendly name for this alert.
+    - `description`: This is an optional value that contains a brief human-friendly description of this alert.
+    - `author`: This is an optional value that contains the author name associated with this alert.
+    - `source`: This is an optional value that describes where the information for this alert was sourced from.
+    - `vehicle`: This is an optional value that contains information about the vehicle this alert is associated with.
+        - `color`: This is an optional sub-value for the vehicle color (all lowercase, human-friendly name).
+        - `make`: This is an optional sub-value for the vehicle manufacturer.
+        - `model`: This is an optional sub-value for the vehicle model.
+        - `year`: This is an optional sub-value for the vehicle year. This value should be an integer.
+
+
+## Examples
+
+### Bare Minimum
+
+This is an example of an alert database with the bare minimum information. This database will trigger alerts for the following plates: AAA1111, BBB2222, CCC3333.
+
+```JSON
+{
+    "AAA1111": {}
+    "BBB2222": {}
+    "CCC3333": {}
+}
+```
+
+### Full Information
+
+This is an example of an alert database with all supported information included. This database will trigger alerts for the following plates: AAA1111, XYZ1234, ABC1234
+
+```JSON
+{
+    "AAA1111": {
+        "name": "Test Alert",
+        "description": "A testing alert to verify Predator's alert functionality",
+        "author": "V0LT",
+        "source": "V0LT",
+        "vehicle": {
+            "color": "red",
+            "make": "Toyota",
+            "model": "Corolla",
+            "year": 2021
+        }
+    },
+    "XYZ1234": {
+        "name": "AMBER Alert",
+        "description": "A testing alert that takes the form of an AMBER alert",
+        "author": "V0LT",
+        "source": "Ohio State Highway Patrol",
+        "vehicle": {
+            "color": "black",
+            "make": "Subaru",
+            "model": "Impreza",
+            "year": 2016
+        }
+    },
+    "ABC1234": {
+        "name": "Test Alert",
+        "description": "A testing alert to verify Predator's alert functionality",
+        "author": "V0LT",
+        "source": "V0LT",
+        "vehicle": {
+            "color": "blue",
+            "make": "Honda",
+            "model": "Accord",
+            "year": 2011
+        }
+    }
+}
+```

docs/CONFIGURE.md

@@ -42,6 +42,7 @@ This document describes the configuration values found `config.json`.
                 - For example, if your alert database is in `/home/pi/Data/alerts.json`, and your working directory is `/home/pi/Data/`, then then the alert database value should simply be set to `"alerts.json"`, not the the full file path.
             - If a particular entry in this list is a remote source, the remote source should be a complete URL.
                 - For example, an entry might be set to `"https://example.com/alerts.json"`.
+            - To learn more about the alert database format, see the [docs/ALERTS.md](docs/ALERTS.md) document.
     - `display` contains settings related to what is displayed in the command line interface.
         - `ascii_art_header` is a boolean that determines whether or not Predator will display a large ASCII art banner on start up.
             - When set to `false`, the ASCII art banner will be replaced with a small, normal text title.

docs/INSTALL.md

@@ -10,7 +10,7 @@ If you're already familiar with Predator, and you just want a quick set-up guide
 1. Install Linux packages: `sudo apt-get install ffmpeg mpg321 gpsd gpsd-clients imagemagick fswebcam libhdf5-dev build-essential`
 2. Install Python packages: `pip3 install pytz validators requests gps gpsd-py3 opencv-python cvlib tensorflow keras silence-tensorflow psutil rns lxmf gpiozero`
     - If you see an "externally managed environment" error while installing Python packages, consider one of the following solutions:
-        - If you're installing Predator on a system dedicated to it's use (such as a computer installed in a vehicle), you can override this warning and force install the packages (at the risk of breaking your install) using by adding the `--break-system-packages` flag to the installation command.
+        - If you're installing Predator on a system dedicated to its use (such as a computer installed in a vehicle), you can override this warning and force install the packages (at the risk of breaking your install) using by adding the `--break-system-packages` flag to the installation command.
             - It's worth mentioning that during testing, using the `--break-system-packages` flag while installing Predator has never caused any noticable system issues on any common Debian-based Linux distribution (Ubuntu, Mint, Raspberry Pi OS, etc.). However, you should still exercise caution when using it, especially if you aren't using a fresh Python installation.
         - If you're focused on developing or modifying Predator, try creating a virtual environment for sake of consistency. This method is very reliable, but will often cause issues if you intend to integrate Predator with external interfaces in production (like V0LT Optic or V0LT Cortex), since these interfaces are unable to run Predator as part of a virtual environment.
             - You can create a virtual environment by navigating to the Predator directory, and running the following command: `python3 -m venv .venv`
@@ -32,27 +32,28 @@ This is the installation process for Predator and all of its dependencies. This
     - Required:
         - `pytz`: Required to manage timezones.
     - Highly recommended:
-        - `validators` and `requests`: Required to network functionality, like push notifications, status light interfacing, remote alert lists, and more.
+        - `validators` and `requests`: Required for network functionality, like push notifications, status light interfacing, remote alert lists, and more.
     - Recommended:
         - `gps`, `geopy`, and `gpsd-py3`: Required to enable GPS features.
             - These packages are not required for reading GPX files, and are only necessary for interacting with live GPS devices.
-        - `opencv-python`, `cvlib`, `tensorflow`, `keras`, `silence-tensorflow`: Required for object recognition features and dash-cam video capture.
-            - These packages are not required for basic license plate recognition.
+        - `opencv-python`, `cvlib`: Required for dash-cam recording.
+            - These packages are also required for object recognition (but not license plate recognition).
     - Optional:
         - `psutil`: Required to process disk usage information in management mode and dash-cam mode.
         - `lxmf`, `rns`: Required to send offline parking notifications over the Reticulum stack.
         - `gpiozero`: Required to trigger events using GPIO inputs.
+        - `tensorflow`, `keras`, `silence-tensorflow`: Required for object recognition features.
 - System packages: `sudo apt-get install ffmpeg mpg321 gpsd gpsd-clients imagemagick fswebcam`
     - Highly recommended:
         - `ffmpeg`: Required for audio/video merging in dash-cam mode, and video processing in pre-recorded mode.
         - `imagemagick`: Required for manipulating still frames of video in pre-recorded mode.
     - Recommended:
         - `mpg321`: Required to play audio alerts.
-        - `gpsd` and `gpsd-clients`: Required to receive and process live GPS data.
+        - `gpsd`, `gpsd-clients`: Required to receive and process live GPS data.
             - It may also be necessary to start GPSD. You can test to see if GPSD is working properly using the `cgps` command.
     - Optional:
         - `fswebcam`: Useful for troubleshooting camera problems.
-            - Predator does not depend on FSWebcam, but it can be a useful tool for capturing still images from connected cameras.
+            - Predator does not depend on FSWebcam, but it can be a useful tool for capturing still images from connected cameras for testing.
 
 
 ### ALPR Engine