OpenALPR Watchman

Watchman software runs on your hardware/application and enables automatic license plate recognition from any IP camera. You don’t need to spend $10,000 on a proprietary “LPR camera,” nor do you need to use complicated and costly video management software. The software can be used for general surveillance purposes or as an engine to add LPR capabilities to other applications.

The Watchman Agent recognizes license plates and the Watchman webserver (either cloud or on-premise) displays searchable results. Other options for retreiving results from the Agent are discussed in the Application Integration section.

Sign-up for Watchman today on https://cloud.openalpr.com/

Watchman Agent

System Requirements

The Watchman Agent scales to make use of as many CPU resources as you can provide. For example, OpenALPR can utilize up to 100 percent of the processing power on both low-power devices (such as a Raspberry Pi) and high-end devices (such as an Intel 32 CPU-core Xeon server). High-end devices are capable of processing significantly more video frames per second.

Memory and disk requirements are relatively constant. Once OpenALPR initializes, the process uses roughly 500MB per analysis thread (CPU core), and that memory usage will not increase. The agent records JPEG images to a disk as plates are recognized. However, Disk IO is usually not a bottleneck.

The minimum system requirements for Watchman Agents are a function of:

  • The speed/angle of vehicles with respect to the camera (i.e., how long a legible license plate is in-frame)
  • The resolution of the input video
  • The number of camera streams analyzed by the agent
  • Other CPU load
  • The volume of vehicles (i.e., whether vehicles are seen constantly or sporadically)

OpenALPR maintains a list of benchmarked processors (both cloud and physical) at VGA, 720p, 1080p, and 4k resolution. Each Watchman release version has its own tab in the spreadsheet. If your CPU or GPU model is on the list, write down the “System Total FPS” numbers for the resolution(s) you are interested in. If you cannot find your CPU/GPU model in our list, the source code and instructions for running the speed benchmarks are available on Github.

Please note that all benchmarks in our spreadsheet were conducted with Ubuntu as the operating system. If you plan to install on Windows, you should decrease the FPS values by 16-22%.

To estimate the number of cameras for a given system total FPS value, use the following per-camera rules of thumb

  • Low Speed (under 25 mph): 5-10 fps
  • Medium Speed (25-45 mph): 10-15 fps
  • High Speed (over 45 mph): 15-30 fps

Installation

Follow the appropriate directions for your operating system below. After completing installation, you can can choose between four data destination options Depending on how you wish to use the Watchman Agent

Windows Agent Configuration
  1. OpenALPR Cloud — Data is sent to https://cloud.openalpr.com (requires an active OpenALPR Cloud Account).
  2. Watchman Webserver — You have installed an on-premise webserver on a Linux machine and wish to point the Agent data to that server.
  3. Generic HTTP Url — You wish to integrate OpenALPR with your own application. You can point the data to your own HTTP endpoint.
  4. Local Queue — You want the OpenALPR data to be stored on a local beanstalkd queue. Your application will programmatically drain the queue to process results.

If you intend to use the agent for surveillance purposes, you will most likely select “OpenALPR Cloud” or “Watchman Webserver.” Options 3 and 4 are useful if you are an developer integrating OpenALPR data into your own application.

Windows

  • Download the OpenALPR Windows Installer
  • Right click the .exe file, run as administrator, and follow the install wizard
  • Start the Configure OpenALPR program and go to Configure > Data Destination

Linux

  1. Download the Ubuntu 18.04 64-bit install DVD image and burn it to a DVD.
  2. Follow this installation guide to install Ubuntu 18.04 64-bit.
  3. Ensure you have curl installed by running the following command from the terminal:
sudo apt-get update && sudo apt-get install -y curl
  1. Run the following command from the terminal:
bash <(curl -s https://deb.openalpr.com/install)
  1. Choose “install_agent” and select yes/no when prompted to connect the Agent to your cloud account.
  2. If you are using a GUI, you can configure the agent using the alprdconfig utility by running the following command:
sudo alprdconfig
  1. If your server does not have a GUI and you wish to connect your software to a Watchman webserver, run the following commands: - Type the command alprlink-register -w https://[ip_address_of_web_server] . - Type in the e-mail address and password for your OpenALPR Cloud account, or the one you used when installing the on-premise webserver.

Docker

  1. Run the command docker pull openalpr/commercial-agent to pull the latest OpenALPR docker commercial agent.
  2. Run the following command to register the agent with the service:
docker run -P -v openalpr-vol1-config:/etc/openalpr/ -v openalpr-vol1-images:/var/lib/openalpr/ -it openalpr/commercial-agent alprlink-register
  1. Start the docker container with the following command:
docker run --restart always -d --cap-add SYS_NICE -P -v openalpr-vol1-config:/etc/openalpr/ -v openalpr-vol1-images:/var/lib/openalpr/ -it openalpr/commercial-agent

Axis Cameras

Install the Watchman Agent as an app on Axis cameras which sends video to the cloud for processing. The following prerequisites are required:

  • A professional account with cloud.openalpr.com (on-premise webservers are not supported)
  • A supported Axis camera
  • An SD Card with at least 2GB storage space
  • Internet Connectivity (minimum 2Mbps upload speed)
  • Accurate date/time. We recommend configuring NTP (See Setup | Date & Time)
  • DNS Configuration (See Setup | Advanced TCP/IP Settings)
  • The latest Axis firmware (minimum is 5.60.1.1)

After checking the prequisites, follow these steps for installation:

  • Download the latest Watchman Axis camera Agent
  • Login to your Axis Camera
  • Click Setup in the top right corner
  • Click Applications
  • Click the Choose File button and select the OpenALPR_Cloud_latest_mipsisa32r2el.eap file (downloaded above), then click the Upload Package button
  • Click OpenALPR Cloud and then Start (you will be prompted for your cloud.openalpr.com credentials)

As vehicles move past the camera, the video will be sent to OpenALPR for archiving and processing. You can view video recorded in the past 60 days using the “Video” link on the left. As license plates are detected, they will appear on our cloud account dashboard.

NVIDIA GPU Acceleration

Watchman Agent performance can also be drastically accelerated by Nvidia GPU hardware. OpenALPR maintains binaries for CUDA 10.0 using CuDNN 7 on 64-bit Ubuntu Linux 18.04. The OpenALPR software has been compiled for CUDA hardware versions 5.2 5.3 6.0 6.1 6.2 7.0 7.2 7.5. You can verify your CUDA version here: https://developer.nvidia.com/cuda-gpus

Ubuntu 18.04

First setup the Nvidia repos:

wget https://developer.download.nvidia.com/compute/cuda/repos/ubuntu1804/x86_64/cuda-repo-ubuntu1804_10.0.130-1_amd64.deb -O /tmp/cuda-repo-ubuntu1804_10.0.130-1_amd64.deb
sudo dpkg -i /tmp/cuda-repo-ubuntu1804_10.0.130-1_amd64.deb
sudo apt-key adv --fetch-keys https://developer.download.nvidia.com/compute/cuda/repos/ubuntu1804/x86_64/7fa2af80.pub

If you have not already installed Nvidia drivers, you must do this first:

sudo apt-get update
sudo apt-get install -y nvidia-driver-410
sudo reboot

Now you may install the OpenALPR GPU acceleration package:

bash <(curl https://deb.openalpr.com/install)

Select OpenALPR software and the install_nvidia option

Ubuntu 16.04

To enable GPU acceleration, first install Nvidia packages:

wget https://developer.download.nvidia.com/compute/cuda/repos/ubuntu1604/x86_64/cuda-repo-ubuntu1604_8.0.61-1_amd64.deb -O /tmp/cuda-repo-ubuntu1604_8.0.61-1_amd64.deb
sudo dpkg -i /tmp/cuda-repo-ubuntu1604_8.0.61-1_amd64.deb

Next install the OpenALPR Nvidia acceleration. Choose “install_nvidia” from the menu:

bash <(curl https://deb.openalpr.com/install)

The following properties will be set automatically in /etc/openalpr/openalpr.conf:

hardware_acceleration = 1
gpu_id = 0
gpu_batch_size = 10

The batch size controls how many images are simultaneously processed by the GPU. The default value is usually the best balance of performance and GPU memory usage.

OpenALPR also maintains special builds for Jetson TX-1/TX-2 hardware on Jetpack v3.1. To install, follow the standard Linux install instructions. The defaults are configured such that the GPU will automatically be installed, enabled, and configured with a default batch size of 5.

Windows 10

Prerequisites:

Windows 10 64-bit
Nvidia GPU driver >= 417.22

Install:

If running the agent, edit the Watchman Agent config file (c:\openalpr\agent\etc\openalpr\alprd.conf) and add the following line:

hardware_acceleration = 1

Restart the Watchman Agent Service

Configuration

Agent Properties

You can configure each Watchman Agent manually (by editing the agent configuration files) or through the OpenALPR web server. This section discusses manual configuration. Configuring the agent through the OpenALPR web server is described in the web server section of the documentation.

The primary configuration file for the Watchman Agent is located in the /etc/openalpr/alprd.conf file. For your reference, you can find a default configuration file containing every default setting for the agent in /usr/share/openalpr/config/alprd.defaults.conf. Any value you change in alprd.conf will take precedence over the default configuration.

The following configuration options can be modified if you edit the alprd.conf file. After adding or changing values in the configuration file, you must restart the Watchman Agent process.

Image Storage Configuration

The commercial daemon maintains a maximum disk quota and automatically cleans up after itself. Images stored to the disk are removed on a FIFO-basis. These parameters control the location, image quality, and maximum size of local image storage.

store_plates = 1
store_plates_jpeg_quality = 85
store_plates_location = /var/lib/openalpr/plateimages/
store_plates_maxsize_mb = 8000
Upload Configuration

You may enable or disable uploading. When the agent is running, all plate results will first be placed onto a local beanstalkd queue. If the upload_data parameter is set to “1” for enabled, the agent will pull results from the queue and send them to the configured “upload_address” endpoint as an HTTP POST. The upload_threads parameter will specifies the number of simultaneous data uploads. Generally, the number of threads only needs to be increased if the web server is slow to respond or network latency is exceptionally high.

upload_data = 1
upload_address = https://cloud.openalpr.com/push/
upload_threads = 2
Company ID (required)

The company_id value is sent in the JSON payload for all results. If you connect to an OpenALPR web server, this value is configured for you automatically. However, if you configure the agent manually, the value is not used, but it is still required. Any alphanumeric string will suffice.

company_id = abc-123
Motion Detection

Motion detection improves efficiency and draws more plate reads from available processors. The ALPR processing only analyzes frames with movement, ignoring areas of the image that have not changed. This parameter controls whether motion detection is enabled (1) or disabled (0).

motion_detection = 1
Parallel Processing

The ALPR processing occurs in parallel; each thread consumes an entire CPU core. Allocating more CPUs for ALPR processing will linearly increase the number of plate reads per second. If you wish to maximize the ALPR processing on your hardware, this number should map the number of CPU cores available on the system.

analysis_threads = 2
Back-Buffer Processing

With motion detection enabled, you are able to buffer moving images and analyze them as CPU becomes available. For example, if a car moves past the camera over 10 frames but the CPU can only analyze 3 of those frames in that period, the buffer allows you to analyze all 10 frames. When activity ceases, the ALPR process drains the buffer, looking for license plates during the period of movement. Increasing the buffer_size increases the duration of this period but will also consume more memory. The camera_buffer_size unit is the number of image frames.

camera_buffer_size = 60
Plate Grouping

The agent groups similar plate numbers together and sends a JSON post containing the UUIDs of every plate image in the group. These configuration files control the behavior of the plate grouping algorithm:

  • plate_groups_span_cameras – A single agent may have multiple cameras. Depending on how the cameras are positioned, they may view the same vehicles or different ones. If plate_groups_span_cameras is set to “enabled,” the grouping algorithm combines plate events that are seen by different cameras. Otherwise, they are never combined.
  • plate_groups_min_plates_to_group – A plate group must have at least this number of individual plate reads to form a group.
  • plate_groups_min_confidence – The plate read must have at least this confidence to be considered for grouping.
  • plate_groups_max_plates_to_group – At some point, if a plate is seen more than this number of times, it is wrapped into a group and sent even if the plate is still in the frame.
  • plate_groups_time_delta_ms – The plate group waits this long for another plate to be identified with a similar license plate. If a matching plate is seen, this timer is reset.
  • plate_groups_max_delay_to_send – Wait at least this long before sending a plate group event. This function is primarily intended to ensure that any back-log of processing is complete before the group event is finished. Depending on the value for camera_buffer_size, you may want to increase or decrease this value.
plate_groups_enabled = 1
plate_groups_span_cameras = 0
plate_groups_time_delta_ms = 4500
plate_groups_min_plates_to_group = 2
plate_groups_min_confidence = 80.0
plate_groups_max_plates_to_group = 500
plate_groups_max_delay_to_send = 7500
Image Retrieval

The agent may also host a local web server for retreiving images via HTTP GET requests. This web server is turned off, but you may enable it by changing the web_server_enabled parameter to 1.

web_server_enabled = 0
web_server_port = 8355
Vehicle Make/Model Classification

OpenALPR automatically classifies vehicle make/model, color, and body type for each license plate group it detects. If you are not using or do not need this feature, you can disable it to save CPU processing time.

classify_vehicles = 1

Camera Streams

The agent must be configured to connect to one or more camera streams to process license plates. OpenALPR expects to receive a URL specifying the HTTP or RTSP stream location on the IP camera. You should be able to find this URL by consulting your camera’s user manual, or with the help of an ONVIF-capable discovery tool. Once you have found the URL, you can test the stream with a video player such as VLC

To add a camera stream:

  1. Create a new unique file in /etc/openalpr/stream.d/ with the extension “.conf”. For example, create a file named “my_new_camera.conf”.
  2. Add a line to the file with the following format: - stream = [Camera HTTP/RTSP stream URL]
  3. Restart the Watchman Agent.

Once restarted, you should see the agent successfully connecting to the camera in the log file (/var/log/alpr.log)

Each camera configuration file may optionally be configured with the following settings:

  • prewarp - A series of numbers that adjusts the rotation/angle of the camera image before processing. The exact value can be obtained through the OpenALPR configuration utility
  • detection_mask_image - The path to a black and white image file that creates a mask over the video stream before processing. Black areas are ignored, white areas are scanned for plates.
Custom GStreamer Pipeline

In some cases, you may require more control over the process that grabs video from your device and makes it available to OpenALPR. The Watchman Agent and AlprStream SDK both allow you to configure a custom GStreamer Pipeline which can handle pulling video from your camera. GStreamer is open source and supports user plug-ins which allow you to write your own C code in case you need to utilize 3rd party device drivers to pull the data.

To get started, you should first familiarize yourself with GStreamer pipelines. The following are a few examples of pulling video from various sources. gst-launch-1.0 is a command line program that will execute the pipeline and display the output.

Webcam

gst-launch-1.0 v4l2src device=/dev/video0 ! video/x-raw,framerate=30/1,width=1280,height=720 ! decodebin ! videoconvert ! video/x-raw,format=BGR ! videoconvert ! autovideosink

Video File

gst-launch-1.0 filesrc location=/tmp/video.mp4 ! decodebin ! videoconvert ! video/x-raw,format=BGR ! videoconvert ! autovideosink

RTSP/H264 Camera

gst-launch-1.0 rtspsrc location=rtsp://192.168.0.100/video user-id=testuser user-pw=test drop-on-latency=1 latency=1000 ! queue max-size-buffers=0 max-size-time=0 max-size-bytes=0 min-threshold-time=10 ! rtph264depay ! h264parse ! decodebin ! videoconvert ! video/x-raw,format=BGR ! videoconvert ! autovideosink

Once you have experimented with GStreamer to display video, you can now integrate it with OpenALPR. Our software will see the video exactly as the gst-launch-1.0 command displays it. If using the agent, you can add your custom gstreamer format as follows:

  1. Edit /etc/openalpr/stream.d/[cameraname].conf
  2. Add gstreamer_format = [your custom gstreamer pipeline]
  3. Remove the “autovideosink” and replace it with “appsink name=sink max-buffers=5”
  4. Make sure you do not include the “gst-launch-1.0” command at the beginning.

If you are using the AlprStream SDK, you will apply the pipeline to the API function “connect_video_stream_url” by passing it a string for “gstreamer_pipeline_format”

Restarting the Agent

The Watchman Agent must be restarted for any configuration changes to take effect.

To restart the Watchman Agent:
  • On Windows, use the OpenALPR configuration utility or manually restart the “Watchman Agent” Windows service.
  • On Linux, run: sudo systemctl restart openalpr-daemon.
  • On Docker, restart the container.

Watchman Webserver

The Watchman webserver is a web-based interface that collects, manages, and presents license plate data that has been produced by one or more Watchman Agents. The webserver does not process license plate videos; that function is performed by the Agent. Data sent from the Agent to the webserver is relatively low-bandwidth because it contains text metadata describing the license plates.

Cloud

OpenALPR hosts a cloud version of the Watchman webserver at https://cloud.openalpr.com that your Agent(s) can send results to. This requires minimal setup (no installation beyond the Watchman Agent), and is sufficient for most users. The cloud webserver may also be preferable for new users looking to create a quick proof of concept. If you decide to use the cloud webserver, you can ignore the on-premise installation instructions below and continue to Configuring Agents.

On-Premise

Users that prefer an on-premise webserver can follow the instructions below to install the Watchman webserver locally. On-premise installations of the Watchman webserver store metadata from each license plate read in a local MySQL database. Full images of the plate captures remain in a rolling buffer on the hard drive where the Agent is installed.

Requirements

When sizing a server for the Watchman on-premises webserver, make sure to select a sufficiently fast hard drive. For web servers supporting up to 200 Agents, a single SSD should be sufficient. For larger installations, the server will likely need multiple hard drives configured as a RAID.

Minimum system requirements:

  • Ubuntu Linux 18.04 64-bit
  • 4GB RAM
  • 250GB SSD hard drive
  • Dual-core or greater CPU

Installation

Download the Ubuntu 18.04 64-bit install DVD image and burn it to a DVD:

Follow this installation guide to install Ubuntu 18.04 64-bit:

Run the following command from the terminal and choose “install_webserver”:

bash <(curl -s https://deb.openalpr.com/install)
OpenALPR VM installation step 4

Configuring Agents

The Watchman webserver may have any number of agents connected to it who send license plate data. Configuration for these agents is managed centrally from the webserver:

  • Log in to your Watchman webserver (cloud or on-premises).
  • Select Configuration > Agents from the menu on the left-hand side of the page.
  • You should see all Agents managed by the webserver on this screen.

Agent names should be unique and can be changed by clicking on them. Choose a sensible name related to the Agent’s location (e.g., headquarters, dallas-branch, or warehouse3). By clicking the Configure button next to an Agent, you can:

  • Add a new camera stream for the Agent to manage

    • Select Add Stream
    OpenALPR VM installation step 4
    • Select the model of IP camera you wish to connect to. Fill in the IP address. If the camera requires credentials, check the box and enter your camera’s username and password.
    • Click Test. After a few seconds, you will see a window indicating whether or not the connection was successful. If it was successful, click Save Camera. If not, try another option (such as H264 Alt1 or MJPEG) and click Test again until you succeed.
    OpenALPR VM installation step 4
  • Modify Agent Parameters

    • Choose the Country in which the camera is located. US will recognize North American-style plates (12 inches x 6 inches). EU will recognize European-style plates. Other countries whose plates have different dimensions are also be supported.
    • Set the number of Processing Cores to control how much CPU will be allocated to the LPR process. The more processing cores you provide (up to the number of CPU cores on the system), the more frames per second (fps) you will be able to process. Higher fps will generally increase accuracy and allow plates on faster-moving vehicles to be detected.
    • Adjust the Disk Quota to control how much space is reserved for storing vehicle and license plate images. It will operate as a rolling buffer, so when it runs out of space, the oldest images will be removed.
    • For Europe, Pattern is the country in which the camera is located. For the USA, OpenALPR uses a high-accuracy state detection algorithm to detect the state of origin, so it is better to leave the pattern set to “None” for recognition in the USA.
    • Click Update to save your changes.
    OpenALPR VM installation step 4
  • View the Agent’s logs live

    • You should now see Video FPS and other information indicating that the video is being pulled from the camera and license plates are being recognized.
    • Once the Agent is configured and connected to a camera stream, it will continue collecting data from the configured video streams. If the Agent’s computer is rebooted, it will automatically start. If the camera goes down or the network becomes temporarily inoperative, the Agent will retry until connectivity is restored. All results will be queued, so no data will be lost in an outage.
    OpenALPR VM installation step 4

You can also configure Watchman Agents manually by modifying their /etc/openalpr/alprd.conf file. This advanced option may be useful in the management of dozens or hundreds of agents. The default values with descriptions can be found in /usr/share/openalpr/config/alprd.defaults.conf. You may add any value into the alprd.conf file, and then restart the Agent to apply changes.

Additional documentation on these configuration options is located in the Axis Cameras.

To restart services, run the following command:

sudo systemctl restart openalpr-daemon

To watch the OpenALPR logs, run the following command:

tail -f /var/log/alpr.log

Application Integration

You can integrate OpenALPR with your application in two ways:

  • Use the OpenALPR SDK to compile OpenALPR code libraries into your application and process individual image frames or video streams.
  • Run the Watchman agent to directly pull video feeds and send the plate results and images to your application.

Integrating With the Agent

The Watchman agent runs as either a Windows service (on Windows) or a daemon (on Linux). The process runs constantly in the background, watching the configured video streams for license plates. When a license plate is found, it immediately places JSON data onto a local beanstalkd queue for uploading or processing.

Decide whether your application should receive data from OpenALPR (sent via HTTP POST) or pull data from a queue on demand. Both approaches are equally valid; your choice simply depends on the most appropriate integration method based on your application architecture.

Receiving HTTP POSTs

The Watchman agent can be configured to send HTTP POSTs to your HTTP server. To enable this option, set the following parameters in /etc/openalpr/alprd.conf:

upload_data = 1
upload_address = [your HTTP server endpoint]
websockets_enabled = 0
web_server_enabled = 1

In addition, you must add a valid on-premises license to /etc/openalpr/license.conf

Once updated, restart the Watchman agent service to allow the settings to take effect. As plates are recognized, the JSON data described in this section will be sent to your HTTP server as an HTTP POST.

Pulling From the Queue

OpenALPR maintains a local Beanstalkd queue. All JSON results are placed onto this queue. Your application can grab and process the latest plate results from this queue .

Beanstalkd maintains client libraries in many popular programming languages. For a complete list, visit: https://github.com/kr/beanstalkd/wiki/Client-Libraries

To configure OpenALPR to make the results available via the local queue, set the following parameters in /etc/openalpr/alprd.conf:

upload_data = 0
websockets_enabled = 0
web_server_enabled = 1

In addition, you must add a valid on-premises license to /etc/openalpr/license.conf

Once updated, restart the Watchman agent service to allow the settings to take effect.

Below is a sample Python script that pulls results from the local Beanstalkd queue:

#!/usr/bin/python

import beanstalkc
import json
from pprint import pprint

beanstalk = beanstalkc.Connection(host='localhost', port=11300)

TUBE_NAME='alprd'

# For diagnostics, print out a list of all the tubes available in Beanstalk.
print beanstalk.tubes()

# For diagnostics, print the number of items on the current alprd queue.
try:
    pprint(beanstalk.stats_tube(TUBE_NAME))
except beanstalkc.CommandFailed:
    print "Tube doesn't exist"

# Watch the "alprd" tube; this is where the plate data is.
beanstalk.watch(TUBE_NAME)

# Loop forever
while True:

    # Wait for a second to get a job. If there is a job, process it and delete it from the queue.
    # If not, return to sleep.
    job = beanstalk.reserve(timeout=1.0)

    if job is None:
        print "No plates available right now, waiting..."

    else:
        print "Found a plate!"
        plates_info = json.loads(job.body)

        # Print all the info about this plate to the console.
        pprint(plates_info)

        # Do something with this data (e.g., match a list, open a gate, etc.).
        if 'data_type' not in plates_info:
            print "This shouldn't be here... all OpenALPR data should have a data_type"
        elif plates_info['data_type'] == 'alpr_results':
            print "This is a plate result"
        elif plates_info['data_type'] == 'alpr_group':
            print "This is a group result"
        elif plates_info['data_type'] == 'heartbeat':
            print "This is a heartbeat"

        # Delete the job from the queue when it is processed.
        job.delete()

JSON Plate Results

OpenALPR generates an “alpr_results” JSON value for every frame of video in which a license plate is recognized. This value will be sent multiple times for a single vehicle. For example, as a vehicle drives past the camera over the course of three seconds, OpenALPR may recognize the same license plate fifty times. All fifty recognition results will be recorded as alpr_results JSON values.

The number of recognition results largely depends on the processing speed and number of cameras being processed. A faster processor will produce more of these per vehicle because it is able to process video frames at a faster rate.

Individual plate results are best suited for applications that need to operate on plate data in real time.

JSON Plate results are sent in the following format:

{
   "processing_time_ms" : 105.850112915039,
   "data_type" : "alpr_results",
   "uuid" : "YYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYY-1234-1562681608425",
   "version" : 2,
   "camera_id" : 1234,
   "results" : [
      {
         "plate_index" : 0,
         "coordinates" : [
            {
               "x" : 3257,
               "y" : 188
            },
            {
               "x" : 3467,
               "y" : 194
            },
            {
               "x" : 3460,
               "y" : 307
            },
            {
               "y" : 302,
               "x" : 3247
            }
         ],
         "processing_time_ms" : 47.0029602050781,
         "plate_crop_jpeg" : "... base 64 image data ...",
         "plate" : "D2651BF",
         "vehicle_region" : {
            "y" : 0,
            "x" : 3042,
            "height" : 630,
            "width" : 630
         },
         "region" : "us-mo",
         "confidence" : 92.9419174194336,
         "matches_template" : 0,
         "requested_topn" : 10,
         "candidates" : [
            {
               "plate" : "D2651BF",
               "confidence" : 92.9419174194336,
               "matches_template" : 0
            },
            {
               "plate" : "D2651F",
               "matches_template" : 0,
               "confidence" : 80.8129653930664
            },
            {
               "matches_template" : 0,
               "confidence" : 80.0941772460938,
               "plate" : "D265BF"
            },
            {
               "plate" : "D251BF",
               "matches_template" : 0,
               "confidence" : 79.946403503418
            }
         ],
         "region_confidence" : 40
      },
      {
         "requested_topn" : 10,
         "candidates" : [
            {
               "matches_template" : 1,
               "confidence" : 94.7376327514648,
               "plate" : "CG3L5Y"
            },
            {
               "confidence" : 79.4123077392578,
               "matches_template" : 0,
               "plate" : "CGL5Y"
            },
            {
               "plate" : "CG3L5",
               "confidence" : 79.0777206420898,
               "matches_template" : 0
            }
         ],
         "region_confidence" : 99,
         "confidence" : 94.7376327514648,
         "region" : "us-mo",
         "matches_template" : 1,
         "plate_crop_jpeg" : "... base64 image data ...",
         "plate" : "CG3L5Y",
         "vehicle_region" : {
            "x" : 821,
            "height" : 1512,
            "y" : 0,
            "width" : 1512
         },
         "plate_index" : 1,
         "coordinates" : [
            {
               "y" : 882,
               "x" : 1419
            },
            {
               "x" : 1744,
               "y" : 893
            },
            {
               "y" : 1055,
               "x" : 1736
            },
            {
               "y" : 1044,
               "x" : 1409
            }
         ],
         "processing_time_ms" : 47.0029602050781
      }
   ],
   "agent_version" : "2.7.101",
   "error" : false,
   "company_id" : "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
   "epoch_time" : 1562681608425,
   "agent_uid" : "YYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYY",
   "img_width" : 4096,
   "regions_of_interest" : [
      {
         "x" : 0,
         "height" : 2160,
         "y" : 0,
         "width" : 4096
      }
   ],
   "agent_type" : "alprd",
   "img_height" : 2160
}

JSON Group Results

OpenALPR generates an “alpr_group” JSON value for a collection of similar license plates, generally delegating a single plate group per vehicle. When the plate is not seen for a number of seconds, the plate_group result is sent with a reference (by UUID) to all the individual plate results that make up the group. The group also includes a best estimate for the license plate number based on a weighted score from all the frames included in the group.

Additionally, each plate group includes a detection value for the make/model, color, and vehicle body type.

Group results are most suitable for surveillance-type purposes. When these values are used, results may be delayed up to ten seconds after the vehicle has passed, so it is important that the application is not sensitive to this delay. If more real-time results are needed, it is recommended that you ignore the plate_group value and use only the individual plate results.

ALPR group results are sent in the following JSON format:

{
   "epoch_end" : 1562681124479,
   "best_image_height" : 2160,
   "best_image_width" : 4096,
   "best_region_confidence" : 57.2820510864258,
   "is_parked" : false,
   "agent_type" : "alprd",
   "data_type" : "alpr_group",
   "gps_latitude" : 37.635986328125,
   "frame_start" : 0,
   "best_region" : "us-mo",
   "agent_uid" : "YYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYY",
   "agent_version" : "2.7.101",
   "country" : "us",
   "uuids" : [
      "YYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYY-1234-1562681121543",
      "YYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYY-1234-1562681121504",
      "YYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYY-1234-1562681121576"
   ],
   "plate_indexes" : [
      0,
      0,
      0
   ],
   "frame_end" : 72,
   "epoch_start" : 1562681121504,
   "vehicle_crop_jpeg" : "...base64 jpeg data...",
   "version" : 2,
   "candidates" : [
      {
         "matches_template" : 0,
         "plate" : "D2651BF",
         "confidence" : 93.877067565918
      },
      {
         "plate" : "D2651F",
         "matches_template" : 0,
         "confidence" : 74.8114395141602
      },
      {
         "confidence" : 73.527099609375,
         "plate" : "D265BF",
         "matches_template" : 0
      }
   ],
   "best_uuid" : "YYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYY-1234-1562681122676",
   "gps_longitude" : -79.2059326171875,
   "vehicle" : {
      "orientation" : [
         {
            "name" : "270",
            "confidence" : 48.2063217163086
         },
         {
            "confidence" : 41.217414855957,
            "name" : "90"
         }
      ],
      "color" : [
         {
            "name" : "black",
            "confidence" : 27.3192367553711
         },
         {
            "confidence" : 26.2272186279297,
            "name" : "silver-gray"
         }
      ],
      "make_model" : [
         {
            "confidence" : 3.64025783538818,
            "name" : "ford_focus"
         },
         {
            "name" : "chevrolet_cruze",
            "confidence" : 2.92206859588623
         }
      ],
      "make" : [
         {
            "confidence" : 18.9258556365967,
            "name" : "ford"
         },
         {
            "confidence" : 6.7553653717041,
            "name" : "chevrolet"
         },
         {
            "confidence" : 6.33295917510986,
            "name" : "toyota"
         }
      ],
      "year" : [
         {
            "name" : "2010-2014",
            "confidence" : 54.3283767700195
         },
         {
            "confidence" : 27.7071475982666,
            "name" : "2015-2019"
         }
      ],
      "body_type" : [
         {
            "name" : "sedan-standard",
            "confidence" : 51.1733474731445
         },
         {
            "name" : "sedan-compact",
            "confidence" : 14.3800678253174
         }
      ]
   },
   "best_confidence" : 93.877067565918,
   "best_plate_number" : "D2651BF",
   "company_id" : "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
   "matches_template" : false,
   "travel_direction" : 85.5532836914062,
   "camera_id" : 1234,
   "best_plate" : {
      "matches_template" : 0,
      "plate_index" : 0,
      "region_confidence" : 62,
      "plate" : "D2651BF",
      "plate_crop_jpeg" : "...base64 jpeg data...",
      "confidence" : 93.877067565918,
      "coordinates" : [
         {
            "y" : 187,
            "x" : 3274
         },
         {
            "x" : 3485,
            "y" : 192
         },
         {
            "y" : 306,
            "x" : 3480
         },
         {
            "y" : 301,
            "x" : 3266
         }
      ],
      "region" : "us-mo",
      "processing_time_ms" : 52.1168479919434,
      "candidates" : [
         {
            "plate" : "D2651BF",
            "matches_template" : 0,
            "confidence" : 93.877067565918
         },
         {
            "plate" : "D2651F",
            "matches_template" : 0,
            "confidence" : 81.3600769042969
         },
         {
            "plate" : "D265BF",
            "matches_template" : 0,
            "confidence" : 80.9256439208984
         }
      ],
      "vehicle_region" : {
         "x" : 3060,
         "height" : 630,
         "y" : 0,
         "width" : 630
      },
      "requested_topn" : 10
   }
}

JSON Heartbeat

Every minute, the Watchman agent adds one heartbeat message to the queue. The heartbeat provides general health and status information. The format is as follows:

{
   "disk_quota_earliest_result" : 0,
   "processing_threads_configured" : 6,
   "processing_threads_active" : 6,
   "license_key" : "licensekeyvalue",
   "memory_swaptotal_bytes" : 0,
   "cpu_usage_percent" : 0,
   "disk_quota_total_bytes" : 1073741824,
   "memory_total_bytes" : 0,
   "video_streams" : [
      {
         "url" : "rtsp://192.168.0.1/stream",
         "fps" : 0,
         "camera_id" : 1234,
         "gps_longitude" : -79.2059326171875,
         "last_update" : 1562681904001,
         "is_streaming" : true,
         "camera_name" : "test",
         "gps_latitude" : 37.635986328125
      }
   ],
   "system_uptime_seconds" : 0,
   "memory_last_update" : 0,
   "recording_enabled" : true,
   "license_valid" : true,
   "daemon_uptime_seconds" : 0,
   "data_type" : "heartbeat",
   "disk_quota_consumed_bytes" : 0,
   "agent_version" : "2.7.101",
   "company_id" : "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
   "disk_drive_free_bytes" : 8031714103340852224,
   "os" : "linux",
   "agent_type" : "alprd",
   "beanstalk_queue_size" : -1,
   "openalpr_version" : "2.7.101",
   "disk_drive_total_bytes" : 491323654144,
   "agent_uid" : "YYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYY",
   "memory_swapused_bytes" : 0,
   "memory_consumed_bytes" : 0,
   "agent_hostname" : "hostnameforthismachine",
   "timestamp" : 1562681904008,
   "license_systemid" : "12341234123412341234",
   "cpu_cores" : 8,
   "cpu_last_update" : 0
}

Local Image Retrieval

The Watchman agent exposes a simple web service for retrieving license plate images. Each image is referenced by a UUID that is sent along with the JSON metadata.

By default, this web server is disabled on the agent, but you can turn it on by adding “web_server_enabled = 1” to the alprd.conf file.

Assuming that the daemon port is set to the default (8355), the full image is referenced with the following URL:

  • http://[Agent_IP]:8355/img/[plate_event_uuid].jpg

In some cases, you may prefer to retrieve a cropped image of just the license plate. This requires significantly less bandwidth than downloading the entire source image. The X and Y coordinates can be computed from the JSON metadata x/y coordinates of the license plate. The x1/y1 coordinates reference the top left of the license plate crop region, and the x2/y2 coordinates reference the bottom right. For example, assuming the crop is located at (477,258), (632,297):

  • http://[Agent_IP]:8355/crop/[plate_event_uuid]?x1=477&y1=258&x2=632&y2=297

In addition, the web server exposes a web service API for searching license plates and groups. Detailed documentation is available in the web server section

REST API

The Web Services API can be used to programmatically query any Watchman webserver (both cloud and on-premises).