U-Filter Detector Server installation and setup
Introduction
U-Filter is a web service for analysing images for intrusion and object detection purposes. The service analyses the pictures it receives and returns a list of bounding boxes for objects found.
Hardware requirements
The U-Filter service can be run on NVIDIA Jetson NX (ADLINK DLAP-211-JNX) platform, or on PCs with NVIDIA GPUs.
Performance examples:
CPU | Memory | GPU | Requests/Sec |
---|---|---|---|
NVIDIA Jetson Xavier NX | 8 GB | NVIDIA Jetson Xavier NX | 14 |
Intel Xeon CPU E5-1620, 8 cores | 16 GB | NVIDIA T1000 | 15* |
Intel Xeon Gold 5315Y, 16 cores | 32 GB | NVIDIA RTX A2000 | 80 |
Intel Xeon Gold 5315Y, 16 cores | 32 GB | NVIDIA RTX A4000 | 160 |
Note: It is recommended that the number of channels does not exceed the number of requests/sec times 5 (e.g. in the case of NVIDIA Jetson Xavier NX, the maximum recommended number of channels is 70).
Note: The above specifications are valid only for the U-Filter detector server. For end-to-end hardware recommendations, check the main page of the product documentation.
* Values are approximate.
How to install the U-Filter service
Prerequisites
- NVIDIA video driver is installed.
- Docker is installed.
- docker-compose is installed.
- A cache directory is created for the service.
- A folder is created for storing the licence files.
- As images are sent using the REST API of the service, the machine running Milestone XProtect must be able to connect to the host machine using this port (the port must be open on the host machine).
Steps to start the container
Download the following files into the same directory.
Edit the
.env
file according to your needs. See the comments in the.env
file for further information.Call
docker-compose up -d --force-recreate
in the folder where the files were downloaded.Wait until the container status is
Up
andhealthy
. Getting it up and running for the first time might take 5-30 minutes.
* optional, see Log management for details.
License
Follow the steps below to activate your U-Filter license.
Ask for an
Activation key
from Ultinous - visit our Support Center or contact sales@ultinous.com.Open the License page of U-Filter in a browser: it is located on the host on which the U-Filter backend is running, on port 6006.
Scroll down to Step 1 and click the Copy to Clipboard button.
Visit the Ultinous Licence Provisioning Service page.
Click Licence Activation.
Fill in the Activation key field with your
Activation key
.Paste the contents of your clipboard to the Licence data field. Fill in the rest of the form according to your needs.
Accept the EULA by ticking its box.
Click Submit -> your licence will be downloaded to your computer.
Open the License page of U-Filter. Scroll down to Step 2 -> upload your licence file created above by clicking the Upload file button. Select the licence file from your computer.
Click Activate to validate your uploaded licence.
Monitoring
The following endpoints are available on the port set in the ultinous.service.event.washer.monitoring.port
property.
Log level endpoint
The log level currently set can be queried by sending a GET request to the /logLevel
endpoint. Log level can also be modified. To set the log level, send a POST request with the desired log level in the request body (e.g. debug) to the /logLevel
endpoint.
Health check endpoint
Service health can be checked by sending a GET request to the /healthCheck
endpoint. The service returns its health information formatted as .json
. For example:
{"value":{"problems":[],"started":true,"ok":true}}
The value.problems
field is an array of strings.
Reload endpoint
To reload the service configuration, send a POST request to the /reload
endpoint.
Shutdown endpoint
To shut down the service, send a POST request to the /shutdown
endpoint.
Error handling
The v2/jpg
and v2/jpeg_sequence
endpoints will respond with status code 503 if they have no resources to process the image or if the license has expired. The server will respond with status code 400 if the input width or height provided is bigger than the one set in the config. A message is also sent in the response body specifying the error. These errors will also be visible in the Milestone XProtect Smart Client interface.
Error | Status code |
---|---|
No resources are available to process the request | 503 |
License has expired | 503 |
Provided input is higher or wider than maximum size set in config | 400 |
Invalid file is received as input (e.g. a video is received by the jpeg endpoint) | 400 |
Advanced configuration
The configuration file path has to be provided in the EVENT_WASHER_MS_PROPERTY_FILE_PATHS environment variable inside the docker container (If you are using the docker-compose file provided by us, it's already done.)
The server has some advanced configuration options: The following table presents them with their default values.
To modify one, add the property to the ufilter.properties
file with the value of your choice.
Property | Description | Default value |
---|---|---|
ultinous.service.event.washer.analyzer.model.cache.dir | Path to the directory for the optimized engine file. | /ultinous_app/cache |
ultinous.service.event.washer.licensing.text.file | Path to the licence txt file. | /ultinous_app/licence/licence.txt |
ultinous.service.event.washer.licensing.key.file | Path to the licence key file. | /ultinous_app/licence/licence.key |
ultinous.service.event.washer.log.level | Log level. Values trace, debug, info, warning, error, fatal | info |
ultinous.service.event.washer.rest.port | Rest server port to accept jpeg request. | 6006 |
ultinous.service.event.washer.monitoring.port | Monitoring server port. | 6007 |
ultinous.service.event.washer.monitoring.threads | ultinous.service.event.washer.monitoring.threads | 1 |
ultinous.service.event.washer.analyzer.input.max.width | Maximum accepted image width. (The analysis resolution does not depend on this.) | 3840 |
ultinous.service.event.washer.analyzer.input.max.height | Maximum accepted image height. (The analysis resolution does not depend on this.) | 2160 |
ultinous.service.event.washer.analyzer.object.max.width | Maximum width of the object in pixels on the original image. | 1000 |
ultinous.service.event.washer.analyzer.object.max.height | Maximum height of the object in pixels on the original image. | 1000 |
ultinous.service.event.washer.listener.number | Number of listening threads for the rest server. Must be greater then analyzer.jobs. | 300 |
ultinous.service.event.washer.analyzer.decoding.workers | Number of workers for decoding. | Number of virtual processors. |
ultinous.service.event.washer.analyzer.jobs | Max number of jobs permitted in the queue. Must be lower than listener.number | 15 |
ultinous.service.event.washer.analyzer.pool.size | Pool size of the GPUEngine. | 3 |
ultinous.service.event.washer.analyzer.gpu.id | GPU device id, default is 0. | 0 |
Operation notes
Log management
To prevent the U-Filter container logs from filling up your drive, you might want to configure the docker logging driver.
Systemd unit
You might want to use systemd to start the U-Filter container after (re)boot - in this case, use our example systemd unit file.
Replace the WorkingDirectory=/opt/u-filter
to your preferred configuration directory, then copy the u-filter.service
file to /etc/systemd/system/multi-user.target.wants
. Run systemctl daemon-reload
.
To start the service, run systemctl start u-filter.service
.
To enable the service during boot, run systemctl enable u-filter.service.