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

Stream mode

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

bash celantur.sh --stream -a face -a license-plate --format whole
  • 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,person,vehicle} Select what you want to anonymise
-f FORMAT --format FORMAT Image format / patches and offset (nx-ny-ox-oy)

Optional arguments

Short Long Description
-h --help Show this help message and exit.
--method {blur,pixelate,blacken} Choose anonymisation method (default: blur)
--debug Debug mode with boundaries (default: False)
--score Print the scores (only if debug mode is enabled). (default: False)
--trace-memory Trace memory usage and print it to logs. (default: False)
--overwrite Overwrite existing files in output folder (default: False)
--opts ... Modify config options using the command-line 'MODEL KEY VALUE' triples. Must be at the end of all parameters!
--bbox Blur whole boxes (default: False)
--quality QUALITY Quality of output (JPEG) image (default: 90)
--metrics METRICS File name for metrics (default: metrics.json)
--video Anonymise video (default: False)

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.