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, .jfif and dng (read-only, output in JPEG).
  • 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, less than 3000 images are recommended.
  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.

  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 all other formats

Setting the detection thresholds

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 mode

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

Server mode

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

bash celantur.sh --server 9999 -a face -a license-plate --format whole

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

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

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 `./celantur.sh -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)
--opts ... Options to configure the ML models.
--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)
--trace-memory Trace memory usage and print it to logs.
--video Anonymise video.

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.