Documentation

Getting Started
Celantur On-premise
Celantur Cloud
Architecture

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 (in .jpg, .jpeg or .png) into input. Images in subfolders are ignored.
  • 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 images should all have the same format / resolution. There is no upper limit to the number of images in the input folder, 1000 to 2000 images are recommended.
  2. 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.

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