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

1. Download the following files into the same directory.

   • docker-compose.yaml
   • .env
   • ufilter.properties
   • u-filter.service*

2. Edit the .env file according to your needs. See the comments in the .env file for further information.

3. Call docker-compose up -d --force-recreate in the folder where the files were downloaded.

4. Wait until the container status is Up and healthy. 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.

1. Ask for an Activation key from Ultinous - visit our Support Center or contact sales@ultinous.com.

2. 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.

3. Scroll down to Step 1 and click the Copy to Clipboard button.

4. Visit the Ultinous Licence Provisioning Service page.

5. Click Licence Activation.

6. Fill in the Activation key field with your Activation key.

7. Paste the contents of your clipboard to the Licence data field. Fill in the rest of the form according to your needs.

8. Accept the EULA by ticking its box.

9. Click Submit -> your licence will be downloaded to your computer.

10. 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.

11. 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.