Batch and Stream mode

Celantur Container batch and stream mode allow you to anonymize images and videos stored on the local file system.

How to use Celantur Container video

Preparation

The following folders are necessary:

$ROOT
├── input/
├── licensing/
├── log/
└── output/
  • input: Where the original files are stored (including subfolders)

  • output: Folder for the anonymized images/videos. If a file exists with the same as in input folder, then processing of the file is skipped.

  • log: Folder containing the logs.

  • licensing: Folder containing the license key. Copy the license file license into this folder as licensing/license.

You will be provided the script files mentioned below by the Celantur team.

Starting in Batch mode

Starting the Container in Batch mode triggers a processing of all files in the input folder. After files have been processed, the Container is shut down.

./celantur.sh -a face -a license-plate -f whole

Starting in Stream mode

Stream mode keeps the Container continuously checking the input folder for new files that have to be processed. The delay between checks can be specified in seconds. The Container needs to be shut down manually.

./celantur.sh --stream -a face -a license-plate -f whole

Stream mode does not support video processing yet. This will be part of a later release.

Image and video processing

By default, Celantur Container processes images. Video processing has to be specified by adding the --video parameter.

Images: ./celantur.sh -a face -a license-plate -f whole

Videos: ./celantur.sh --video -a face -a license-plate -f whole

Parameters

You can edit ./celantur.sh <parameters> to modify the behavior of Celantur Container. Experienced Linux user can modify the script celantur.sh

Parameter
Description

--anonymise {face, license-plate, person, vehicle} -a {face, license-plate, person, vehicle}

REQUIRED

Specify objects to be anonymized.

--format FORMAT -f FORMAT

REQUIRED

Specify image format, to control how an image should be processed. Default: whole

Image tiling for improved anonymization results and limiting the anonymization to a specific section of the image can be specified here as well.

See Image Format section for reference or check usage with ./celantur.sh -h.

--help -h

Prints help message with all parameters and exits.

--bbox

Anonymizes objects with bounding boxes

--debug

Enables debug mode. Bounding boxes of detected objects are displayed on images.

--score

Prints the certainty scores of detected objects on images, if debug mode is enabled.

--cpu-mode

Disables GPU utilization. See Using CPU only

--method {blur, pixelate, blacken, detect}

Choose anonymization method (default: blur)

--metrics <filename.json>

File name for metrics (default: metrics.json)

--quality [1..100]

Quality of output (JPEG) image (default: 90)

--overwrite

Overwrite existing files in output folder.

--stream [seconds]

Streaming mode (Wait time in seconds).

--server-array <host:port>

--video

Anonymize videos.

--model segmentatio-omnium

Specifies which models shall be used. `segmentatio-omnium` model is significantly faster than the default model (without --model ... paramter).

--no-object-tracking

Disables object tracking in videos, whic is enabled by default. See Object Tracking

--keep-bit-rate [bool]

Specifies whether the bitrate of the anonymized video should remain very close to the one of the original video.

Enabling keep-bit-rate will ensure a nearly identically file size of the processed video, at the cost of 10% to 20% higher processing time. Default: false

--person-threshold [0..1]

Threshold for whole person detection.

--vehicle-threshold [0..1]

Threshold for vehicle detection.

--face-threshold [0..1]

Threshold for face detection.

--license-plate-threshold [0..1]

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.

--log-level {CRITICAL,ERROR,WARNING,INFO, DETAIL,DEBUG}

Specifies which levels of logs will be printed out.

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

Image format

By specifying image format settings, Celantur Container can achieve improved anonymization results and apply anonymization only to a specific region of an image.

--format '{"number":[nx,ny],"overlap":[ox,oy],"section":[x1,y1,x2,y2]}'

Don't use spaces in the format string. Otherwise Bash has problems interpreting it as one argument.

Custom tiling for improved results

In certain cases, its beneficial to process high-resolution imagery in tiles, instead of the whole image. Small, distant objects are more likely to be detected.

--format '{"number":[nx,ny],"overlap":[ox,oy]}'
Parameter
Description

nx

Number of horizontal tiles

ny

Number of vertical tiles

ox

Horizontal overlap between tiles in pixels

oy

Vertical overlap between tiles in pixels

Limit anonymization to a section of the image

Apply anonymization only to a specified rectangular section of the image. This can result in faster processing time.

--format '{"number":[3,2],"overlap":[ox,oy],"section":[x1,y1,x2,y2]}'

number and overlap attribute are required when specifying the section, as seen in the example above.

Parameter
Description

x1, y1

Top left coordinate of the section

x2, y2

Bottom right coordinate of the section

Predefined formats

Alternatively, you can use the option --format to choose the resolution of the input images, eg. --format pano:8000 for an image resolution of 8000x4000. Use --format whole for all formats not listed below, or if the input images have different resolutions.

Parameter
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

Ensure that the image resolution matches exactly the predefined resolution in the parameter to avoid processing errors.

FAQ

How do I use input/output folders on an external drive?

You can use symbolic links (see ln for reference) for the input and output folders, e.g. in the folder with the celantur.sh script:

# set "input" as a symbolic link to an external drive
ln -s /path/to/external/drive/input-images input

# set "output" as a symbolic link to an external drive
ln -s /path/to/external/drive/output-images output

Can I start multiple container instances on one machine?

Yes, this is possible and can lead to a higher throughput when you process images, by having several container instances working in parallel. Please make sure that your system has enough resources available.

Run the following command as many times as how many container instances you want to start:

celantur.sh --detach

The --detach flag is supported starting from version 22.06.3.

Note that this will start container in the detached mode and you will not be able to observe the text output. To inspect which containers are currently running use docker ps, which will also print the container IDs. To inspect log outputs of a particular container, use docker logs <container_id>. Finally, to stop the container use docker kill <container_id> && docker rm <container_id>

It's highly recommended to assign dedicated input/output folders to each container instance, when using the batch/stream mode.

To do that, either run celantur.sh from the corresponding processing folder, or use export PROCESS_DIR=<processing_directory_for_this_container> before executingcelantur.sh.

"Permission denied" error when writing files

Problem: [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

"Read-only file system" error when writing files

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

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

Will image EXIF, IPTC and XMP metadata be carried over to the anonymized image?

Yes, metadata (e.g. EXIF, IPTC and XMP information, ICC color profile) is retained when creating the anonymized version of an image.

Will video metadata be carried over to the anonymized video?

Celantur Container attempts to copy over all stream/track and container metadata to the anonymized video.

Supported image formats

The following image formats are supported:

  • .jpg / .jpeg

  • .png

  • .tif / .tiff

  • .bmp

  • .jfif

Supported video codecs

Codecs are essential for encoding and decoding audio, video, or other data streams.

Celantur Container provides support, among others, for these codecs:

  • h265

  • h264

  • mjpeg

  • mpeg4

Plese contact us, if you want to know more about our support for other codes.

Are ROS2 MCAP files supported?

Please see Anonymization of ROS2 .mcap files

Can multiple GPUs in one machine be utilized?

Yes, by starting multiple instances/processes of Celantur Container.

To specify the GPU which Celantur Container utilizes, you need to adapt the celantur.sh script. Instead of:

[[ ${PARAMETERS} != *"--cpu-mode"* ]] && GPU="--gpus all"

change it to

[[ ${PARAMETERS} != *"--cpu-mode"* ]] && GPU="--gpus device=<GPU-UUID>" You find the GPU UUID with nvidia-smi -L. Result is GPU-xxxx-xxx-xxx-xxxx-xxxxxxx

Can a Basic/PRO license be used on a multi GPU machine?

Yes, Celantur Container can be used on multi GPU systems. Multiple GPU UUIDs can be specified in a license file.

Why is the file size of a JPEG different after anonymization?

Celantur applies anonymization on the raw pixel data. JPEG compression is applied when saving an anonymized image as a JPEG, resulting in a different file size. The resulting JPEG file size can be influenced by changing the quality parameter (default: 90).

Last updated