Usage

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

Preparation

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.

$ROOT
├── 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 celantur.sh to run Docker container.

cd $ROOT
bash celantur.sh -a face -a license-plate --format whole

Or, alternatively, run bash celantur.sh $ROOT.

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

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

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

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 celantur.sh --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 celantur.sh --server 0.0.0.0:9999 -a face -a license-plate --format whole

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

bash celantur.sh --server-array 0.0.0.0:9999 -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 celantur.sh --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.

Parametrisation

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

Required arguments

Optional arguments

For more arguments, check ./celantur.sh --help.

Troubleshooting

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.