Configuration

The first time you start Shipping Container Live, a container-video-config.ini is created in the directory you have specified. Please note that anytime you change the contents of container-video-config.ini, you will need to restart the Docker container .

container-video-config.ini
# List of TZ names on https://en.wikipedia.org/wiki/List_of_tz_database_time_zones
timezone = UTC

[cameras]

  # Image file name, you can use any format codes
  # from https://docs.python.org/3/library/datetime.html#strftime-and-strptime-format-codes
  image_format = $(camera)_screenshots/%y-%m-%d/%H-%M-%S.%f.jpg

  [[camera-1]]
    active = yes
    url = rtsp://your-camera.com:8554/demo
    webhook-target = webhook-1
    sample = 5

    # Save to CSV file. The corresponding frame is stored as an image in the same directory.
    # See more formats on https://guides.platerecognizer.com/docs/other-apps/shipping-container-live/configuration#output-formats
    csv_file = $(camera)_%y-%m-%d.csv

[webhooks]

  [[webhook-1]]
    url = http://my-webhook-1.site
    image = texts, original

Hierarchical Configuration

File container-video-config.ini defines parameters that will be used by all cameras or just one.

When parameters are defined at the [cameras] level, they apply to all cameras. When they are defined at the [[camera-id]] level, they apply to a single camera.

container-video-config.ini
[cameras]
  # Parameters for all cameras
  sample = 5
  image_format = $(camera)_screenshots/%y-%m-%d/%H-%M-%S.%f.jpg
  csv_file = $(camera)_%y-%m-%d.csv

  [[camera-1]]
    # Parameters set only for camera-1
    active = yes
    url = rtsp://192.168.0.108:8080/video/camera-1
    sample = 3 # sample = 3 is only applied for camera-1

  [[camera-2]]
    # Parameters set only for camera-2
    active = yes
    url = rtsp://192.168.0.108:8080/video/camera-2
    # sample = 5 defined in [cameras]

info

Some parameters are disabled by default, they are marked with the character # at the beginning of the line. To activate the parameter, it is necessary to remove this mark, save the file and restart the Docker container.

Parameters

All parameters are optional except url.

active

Shipping Container Live processes all the cameras defined in the config file if active is set to yes. See example above.

max_prediction_delay

Set the time delay (in seconds) for the container info prediction. A higher value lets us capture more frames and can result in higher prediction accuracy.

The default value is 6 seconds. So by default, Shipping Container Live waits at most 6 seconds before it sends the info output via Webhooks or saves the texts output in the CSV file.
You can decrease this parameter to say 3 seconds to speed up the time it takes to send the available information.
In situations where the camera cannot see the text very well (say due to some obstruction or because it's a lower res camera), then increasing max_prediction_delay will give Shipping Container Live a bit more time without rushing to find the best frame for the best OCR results.

memory_decay

Set the time between when Shipping Container Live will detect the same container again for a specific camera. This can be useful in situations where the same container stays in front of Shipping Container Live camera for a long time. After memory_decay Shipping Container Live will be able to recognize and decode that same container again.

The minimum value would be 0.1 seconds. However, for clarity, it is not recommended to set it so low because if the camera still sees that container again (say 0.2 seconds later), then Shipping Container Live will report it again. There is no maximum value.
If this parameter is omitted, Shipping Container Live will use the default value, which is 300 seconds (5 minutes).
This parameter has no effect if a container is seen by multiple cameras.

sample

Set Shipping Container Live to skip frames of a particular camera or video file.
By default, sample = 2, so Shipping Container Live processes every other frame.
Set sample = 3 if you want to process every third frame.
This parameter lets you skip frames in situations where you have limited hardware and/or do not need to process all the frames of the video or camera feed.

timezone

You can set the timezone for the timestamp in the CSV and also Webhooks output.
If you omit this field, then the default timezone output will be UTC.
See list of supported time zones.
Plate Recognizer automatically adjusts for time changes (e.g. daylight savings, standard time) for each timezone. Examples: a) For Silicon Valley, use timezone = America/Los_Angeles b) For Budapest, use timezone = Europe/Budapest. You can also use timezone = Europe/Berlin.

The timestamp field is the time the container was captured by the camera. We are using the operating system clock and we apply the timezone from container-video-config.ini.

url

To run Shipping Container Live on a RTSP camera feed, just specify the URL to point to the RTSP source. For example:

url = rtsp://192.168.0.108:8080/video/h264

url = rtsp://admin:[email protected]:8080/video/h264
# where admin is the username and 12345 is the password

For additional help with RTSP, please go to https://www.getscw.com/decoding/rtsp
You can also process video files.

max_reconnection_delay

When Shipping Container Live cannot reach specified camera url it will repeatedly try to reconnect after a short delay. With every failed attempt the delay will increase exponentially until it reaches the value of max_reconnection_delay = 600 seconds (default). You may set this parameter to lower value if you want Shipping Container Live to try reconnecting more often.

Output Formats

csv_file

Indicate the filename of the CSV output you’d like to save.
The name can be dynamic. Refer to the field image_format for details. For example:

csv_file = $(camera)_%y-%m-%d.csv

jsonlines_file

Save the prediction results to a JSON file. For example:

jsonlines_file = my_camera_results.jsonl
jsonlines_file = $(camera)_%y-%m-%d.jsonl

We are using the JSON Lines format. Refer to the field image_format for details.

image_format

Save images in a particular folder with a specific filename. In the example above, images are saved in the directory <camera_id>_screenshots (one per camera) with the filename <timestamp>.jpg. Images are saved when csv_file or jsonlines_file is used. If webhooks are used, images may temporarily be saved to disk.

Filename customization:
- If $(camera) is used, it is replaced with the camera's name. For example, camera-1.
- If the current date is 2020-06-03 20:54:35. %y-%m-%d/%H-%M-%S.jpg is replaced by 20-06-03/20-54-35.jpg. Letters starting with the percent sign are converted according to those rules https://strftime.org/
- For example, to put images from all cameras into the same folder: image_format = screenshots/$(camera)_%y-%m-%d_%H-%M-%S.%f.jpg
If you don't need to save images, you can leave it empty: image_format =.

caution

If you have a webhook with images, image_format should NOT be empty.

video_format

Save video clips of detected container in a particular folder with a specific filename. Same as image_format. After a video file has been sent out to a webhook, it gets removed from disk. Otherwise, it is kept forever.
Example: video_format = $(camera)_videos/%y-%m-%d/%H-%M-%S.%f.mp4
If you don't need to save videos, you can leave it empty: video_format =

note

Currently only .mp4 output format is supported. We may add more formats in the future.

danger

Enabling the feature to save video clips not only substantially increases CPU usage but also consumes significant storage space. Prior to enabling this feature, ensure you have spare processing capacity and sufficient available storage.

video_before

When video clip is saved, Shipping Container Live records a few seconds before the container was detected. This time is controlled by video_before parameter. The default value is 5 seconds.

video_after

When video clip is saved, Shipping Container Live records a few seconds after the container was detected. This time is controlled by video_after parameter. The default value is 5 seconds.

note

Total video duration could differ slightly from values specified in video_before and video_after due to encoding and frame rate differences.

video_fps

There are two options for video clips frame rate: video_fps = native (default) records frames at the rate Shipping Container Live is reading them from source; video_fps = sample records frames at reduced rate specified by sample parameter.

video_overlay

It is possible to add information overlay to video clips, to gain insight into App's operation and simplify troubleshooting or config tuning. This parameter can be set to one or several (separated by comma) of the available options:

all: turns all available overlays on;
boxes: draws bounding boxes for container and info texts, each container in its own unique color;
trace: draws a container trajectory;
vehicle_type: adds a container type on top of the container bounding box;
dscores: adds detections scores on top of the bounding boxes;
confirmed: adds rolling text box with recognition event information in the same color as the container's bounding box; note that it is displayed when Shipping Container Live is reporting this information, which is usually after the container has left the frame (see max_prediction_delay), so adjust video_after appropriately;
health_score: adds Health Score number to the frame;
timestamp: adds time in the specified timezone to the frame and to the confirmed overlay, identifying the moment of recognition event;
position_sec: adds internal video second counter useful for video files, similar to timestamp.

note

Shipping Container Live can only add overlays to sample frames, so setting video_fps = sample is recommended when using video_overlay.

video_codec

There two options for video clips codec: video_codec = mp4v (default) encodes video clips with MPEG-4 part 2 codec; video_codec = h264 encodes video clips with H.264 codec.

danger

H.264 encoding requires significantly more CPU and memory resources, which may not yield real-time processing and could lead to abrupt crashes. If crashes occur with video_codec = h264, increase your Docker or WSL resource limits, as these crashes are likely due to RAM limitations in Docker or WSL.

report_static

By default Shipping Container Live reports static (non-moving) containers as well. If report_static = no is set, Shipping Container Live will ignore them.

Webhook Parameters

Shipping Container Live can automatically send a notification to an URL, when a container information is confirmed within the video stream. You can use Webhooks as well as save images and CSV files in a folder. By default, no Webhooks are sent.

How Webhook are Sent

If the target cannot be reached (HTTP errors or timeout), the request is retried 3 times.
If it is still failing, the data is saved to disk. That can be turned off using caching webhook parameter.
- When a webhook fails, all new webhook data will be directly saved to disk.
- Every 2 minutes, there is an attempt to send the cached webhooks. If a send is successful, we will also process the data saved to disk if there is any.
- When webhooks are saved to disk, we remove the oldest data when the free disk space is low.

Format and Fields

Description of the webhook data format.

webhook_targets

To send data to webhooks, you must list them in webhook_targets camera property of the container-video-config.ini.
The recognition data and image are encoded in multipart/form-data.
To ensure that your webhook_targets endpoint is correct, please test it out at www.webhook.site.

You can send to multiple targets by simply listing all the targets. Each target has its own set of parameters: url, image, image_type (deprecated), request_timeout, caching, header, video.

webhook_targets = my-webhook-1, my-webhook-2

webhook descriptors

Each webhook you are planning to use should be described in [webhooks] section of the container-video-config.ini file. This section also uses Hierarchical Configuration structure:

container-video-config.ini
# Webhook targets and their parameters
[webhooks]
  [[my-webhook-1]]
    url = http://my-webhook-1.site
    image = texts

  [[my-webhook-2]]
    url = http://my-webhook-2.site
    image = no

url (webhook)

Specifies the URL to send the webhook data to. For example:

url = http://my-webhook-1.site

image

This field can be set to either:
```
image = yes
image = no
```
When image = no is set, it will send only the recognition data but the image data will not be sent to the target URL. This lets your system receive the information faster.

note

Starting from version 0.2.0, it is possible, and preferred, to specify the image type(s) directly in the image field, as in:

image = original
image = texts
image = original, texts

Please see below for more information about the image types.

If you don't want image data to be sent, you can specify image = no as usual.

image_type

This field can be set to either:
```
image_type = original
image_type = texts
```
When set to original, the webhook will receive the full-size original image from the camera.
When set to texts, the webhook will receive the image of the container ID texts in the request.
If necessary, it is possible to combine image_type options. Any combination is valid:

 image_type = texts
 image_type = original, texts

Deprecated in version 0.2.0.

video

This field can be set to either:
```
video = file
video = url
video = no
```
When video = file is set (default), the video clip with timestamp, texts and other container information will be sent to the target URL.
When video = url is set, Shipping Container Live will send only the video file information but the video file itself will not be sent to the target URL. This option is reserved for future use.
When video = no is set, no video information will be sent to a webhook.

note

Video information is sent separately from recognition data, when video file becomes available. See Get Results for webhook json format details.

caching

If a webhook fails, it is by default cached to disk and retried later. To turn this off, use caching = no.

request_timeout

A webhook request will timeout after request_timeout seconds. The default value is 30 seconds.

The webhook request can have a custom header. To set it, use header = Name: example. By default no custom header is used.

Other Parameters

Sending Additional Information (GPS)

You can set arbitrary user data in the webhook (for example, a GPS coordinate). It can be updated at any time via a POST request.

Start Shipping Container Live with docker run ... -p 8001:8001 ...
Send a post request with the user data: curl -d "id=camera-1&data=example" http://localhost:8001/user-data/
- In this example, we set the data for camera-1. It should match the id used in container-video-config.ini.
- The user data is set to example.
When a webhook is sent, it will have a new field user_data with the value set in the previous command. JSONL output will also include this field.

The new data will be included only when there is a new detection. For example,

at 12:00, you set the user data to some GPS coordinates.
At 12:05, there is a new detection and it will include the new coordinates.

Detection Zone

Detection Zones exclude trees, street signs or other objects. For more info, read our blog on Detection Zones.

To start, go to our Detection Zone in your Plate Rec Account Page and upload a capture from the camera set up on the Shipping Container Live.
Add the camera_id parameter, it is between [[]] in your container-video-config.ini configuration file, make sure they are identical. The image below represents an example whose camera_id is 'camera_1". After these steps click "Add Zone".

container-video-config.ini
  [cameras]
    # Global cameras parameters here
    [[camera_1]]
      active = yes
      url = rtsp://<rtsp_user>:<rtsp_password>@<rtsp_url>:<rtsp_port>/<rtsp_camera_path>
      # More camera parameters below
      # ...

The system will load the added image and a page similar to the image below will display it, then you can use the mouse as a marker over the image to determine the area that will be ignored in the detection. Once you are done, click "Save Zone".
Make sure to restart the Docker container and that machine has internet access at the time of the restart to see the effects. When you open your Shipping Container Live folder, you will now see one file per zone.

Editing Zone Files

To edit a detection zone, Click Edit on Detection Zone then follow step (3). After this, remove the file zone_camera-id.png from the Shipping Container Live folder then follow step (4). When you open your Shipping Container Live folder, you will now see the new file zone_camera-id.png.

Removing Zone Files

To remove a detection zone, click Remove on Detection Zone. Then remove the file zone_camera-id.png from the Shipping Container Live folder.

Detection Zone Files

After following the steps above, you will have new files in your Shipping Container Live folder. For example, if you create a detection zone for camera1, you will have an image at /path/to/Shipping Container Live/zone_camera1.png.

You can also manually create a detection zone mask. Here are the requirements.

Create a PNG image in your Shipping Container Live folder. Check the file permissions; it should be readable by your Docker user.
Name the file zone_camera-id.png (replace camera-id with the ID of your camera).
Use only two colors: black for masked areas and white for everything else.
The image resolution should match the resolution used by the camera.

Configuration

Hierarchical Configuration​

Parameters​

active​

max_prediction_delay​

memory_decay​

sample​

timezone​

url​

max_reconnection_delay​

Output Formats​

csv_file​

jsonlines_file​

image_format​

video_format​

video_before​

video_after​

video_fps​

video_overlay​

video_codec​

report_static​

Webhook Parameters​

How Webhook are Sent​

Format and Fields​

webhook_targets​

webhook descriptors​

url (webhook)​

image​

image_type​

video​

caching​

request_timeout​

header​

Other Parameters​

Sending Additional Information (GPS)​

Detection Zone​

Editing Zone Files​

Removing Zone Files​

Detection Zone Files​

Hierarchical Configuration

Parameters

active

max_prediction_delay

memory_decay

sample

timezone

url

max_reconnection_delay

Output Formats

csv_file

jsonlines_file

image_format

video_format

video_before

video_after

video_fps

video_overlay

video_codec

report_static

Webhook Parameters

How Webhook are Sent

Format and Fields

webhook_targets

webhook descriptors

url (webhook)

image

image_type

video

caching

request_timeout

header

Other Parameters

Sending Additional Information (GPS)

Detection Zone

Editing Zone Files

Removing Zone Files

Detection Zone Files