U-Filter Detector Server installation and setup
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.
The U-Filter service can be run on NVIDIA Jetson NX (ADLINK DLAP-211-JNX) platform, or on PCs with NVIDIA GPUs.
|NVIDIA Jetson Xavier NX||8 GB||NVIDIA Jetson Xavier NX||14|
|Intel Xeon CPU E5-1620, 8 cores||32 GB||NVIDIA GeForce GTX TITAN X||27|
|Intel Xeon CPU E5-1650, 12 cores||32 GB||NVIDIA GeForce GTX 1080 Ti||40|
|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).
How to install the U-Filter service
- 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.
.envfile according to your needs. See the comments in the
.envfile for further information.
docker-compose up -d --force-recreatein the folder where the files were downloaded.
Wait until the container status is
healthy. Getting it up and running for the first time might take 5-30 minutes.
* optional, see Log management for details.
Follow the steps below to activate your U-Filter license.
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 Activation key field with your
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.
The following endpoints are available on the port set in the
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
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 field is an array of strings.
To reload the service configuration, send a POST request to the
To shut down the service, send a POST request to the
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.
|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|
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.
|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.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|
To prevent the U-Filter container logs from filling up your drive, you might want to configure the docker logging driver.
You might want to use systemd to start the U-Filter container after (re)boot - in this case, use our example systemd unit file.
WorkingDirectory=/opt/u-filter to your preferred configuration directory, then copy the
u-filter.service file to
To start the service, run
systemctl start u-filter.service.
To enable the service during boot, run
systemctl enable u-filter.service.