Celantur on-premise is a Dockerised application with a simple command-line interface to anonymise images.


The following folders are necessary:

  • input: Put the original images (including subfolders) into input. Following formats are supported: .jpg / .jpeg, .png, .tif / .tiff, .bmp, and .jfif.
  • output: Folder for the anonymised images. If a file exists with the same as in input folder, then processing of the file is skipped.
  • log: Folder containing the logs.
  • licencing: Folder containing the license key. Copy the license file license into this folder as licensing/license.
├── input/
├── licensing/
├── log/
└── output/

Run Celantur

  1. Copy the original images into the input folder. You can also copy whole folder structures with subdirectories. The structure in the input folder will be replicated in the output folder.
  2. The images should all have the same format / resolution. There is no upper limit to the number of images in the input folder. Please pay attention to the overall capacity of the file system and the size of the output (similar to the size of the input).
  3. Use to run Docker container.
cd $ROOT
bash -a face -a license-plate --format whole

Or, alternatively, run bash $ROOT.

The images in the input folder are processed in arbitrary order.

  1. The application terminates after all images in the input folder are processed.

  2. You find the anonymised images in the output folder.

Choosing the right image format (resolution)

Our algorithms are optimised to work on different image resolutions.
You can use the option --format to choose the resolution of the input images, eg. --format pano:8000 for image resolution of 8000x4000.
Use --format whole for all formats not listed below, or if the input images have different resolutions.

Paramter Resolution
pano:4096 4096x2048
pano:5400 5400x2700
pano:5640 5640x2816
pano:7060 7060x3530
pano:7680 7680x3840
pano:8000 8000x4000
pano:7680 7680x3840
pano:8000 8000x4000
pano:8192 8192x4096
pano:11000 11000x5500
whole default, valid for all resolutions

Setting the detection thresholds

Use person-threshold, vehicle-threshold, face-threshold and license-plate-threshold to set detection thresholds for persons, vehicles, faces, and license-plates, respectively.

For older version (before v22.08.1)

You can use the option --opts to set the detection thresholds:

  • For license plates: license-plate MODEL.ROI_HEADS.SCORE_THRESH_TEST 0.5
  • For bodies and vehicles: segmentation MODEL.ROI_HEADS.SCORE_THRESH_TEST 0.5
  • For faces: keypoint MODEL.ROI_HEADS.SCORE_THRESH_TEST 0.5

Use the flag --opts only once! E.g. --opts license-plate MODEL.ROI_HEADS.SCORE_THRESH_TEST 0.2 keypoint MODEL.ROI_HEADS.SCORE_THRESH_TEST 0.1 to set the thresholds for license plate detector to 0.2 and for face detector to 0.1.

Define areas left unanonymised

[version 21.11.1] You can define areas in an image that you do not want to anonymise, using a JSON file with the same file name as the image file, e.g. image-file-1.jpeg and image-file-1.json. The content of the JSON file is:

  "ignores": [
    "topLeftX": "int", 
    "topLeftY": "int", 
    "width": "int",
    "height": "int"

CPU only

By default, our on-premise solution runs on NVIDIA GPU to offer the best performance. You can run it on CPU only using the flag --cpu-mode, e.g.

bash --cpu-mode -a face -a license-plate --format whole

REST API server mode

You can run Celantur on-premise as a HTTP server with a REST API. Check out the API documentation and example calls.

TCP server mode

You can run Celantur on-premise in server (TCP) mode with

bash --server -a face -a license-plate --format whole

where you can exchange the images in JPEG format (Python client code sample), or with

bash --server-array -a face -a license-plate --format whole

where you exchange the images as NumPy arrays (Python client code sample).

Stream mode

You can run Celantur on-premise in the "streaming" mode, adding the --stream WAIT_TIME parameter, e.g.

bash --stream 0.2 -a face -a license-plate --format whole

The WAIT_TIME in seconds is the time the software pauses between every scan if the input folder is empty.

  • Once on-premise starts, it scans the input folder for images.
  • It processes the images in the input folder and writes the blurred images in the output folder.
  • It removes the images from the input folder, once they are processed.
  • It waits for new images in the input folder, or until the user presses CTRL-C.


You can run ./ <options> to modify the behaviour of Celantur on-premise. (Experienced Linux user can modify the script or)

Required arguments

Short Long Description
-a {face, license-plate, person, vehicle} --anonymise {face, license-plate,p erson, vehicle} Select what you want to anonymise
-f FORMAT --format FORMAT Image format. For normal camera images, use `whole`. For other formats, check usage with `./ -h`.

Optional arguments

Short Long Description
-h --help Show this help message and exit.
--bbox Blur whole boxes.
--debug Debug mode with boundaries.
--cpu-mode Disable GPU support.
--method {blur, pixelate, blacken} Choose anonymisation method (default: blur)
--metrics METRICS File name for metrics (default: metrics.json)
--quality QUALITY Quality of output (JPEG) image (default: 90)
--overwrite Overwrite existing files in output folder.
--score Print the scores (only if --debug mode is enabled).
--stream WAIT_TIME Streaming mode (Wait time in seconds).
--server SERVER Server mode (host:port)
--server-array SERVER_ARRAY Server mode (host:port)
--video Anonymise video.
--person-threshold THRESHOLD Threshold for whole person detection.
--vehicle-threshold THRESHOLD Threshold for vehicle detection.
--face-threshold THRESHOLD Threshold for face detection.
--license-plate-threshold THRESHOLD Threshold for license plate detection.
--save-mask {all, instance, binary} Generate binary and instance segmentation mask files per processed images. See Segmentation Masks.
--mask-scale {0-100} Scales binary and instance segmentation mask files down by the specified ratio. See Segmentation Masks.

For more arguments, check ./ --help.


Error writing files

Error Permission denied

[Errno 13] Permission denied: '/path/to/file'

In Docker, if you mount a directory to Docker that does not exist, Docker creates the folder as root. Inside Docker container, the user (with UID 1000) cannot write in the directory.

Solution: Create the folders output and log before you mount them and ensure that the file owner has UID 1000.

mkdir log output
sudo chown 1000:1000 log output  

Alternatively, give everyone write permission to log and output:

mkdir log output
chmod 777 log output

Error Read-only file system

[Errno 30] Read-only file system: '/path/to/file'

The folder is mounted in Docker as read-only. Remove the appendix :ro from the -v parameter.