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) intoinput
. 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 filelicense
into this folder aslicensing/license
.
$ROOT
├── input/
├── licensing/
├── log/
└── output/
Run Celantur
- Copy the original images into the
input
folder. You can also copy whole folder structures with subdirectories. The structure in theinput
folder will be replicated in theoutput
folder. - 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). - 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.
-
The application terminates after all images in the
input
folder are processed. -
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 | default, valid for all 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 theoutput
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 pressesCTRL-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) | |
--video | Anonymise video. | |
--person-threshold THRESHOLD | Threshold for whole person detection. | |
--vehicle-threshold THRESHOLD | Threshold for vehicle detection. | |
--face-threshold THRESHOLD | Threshold for face detection. | |
--license-plate-threshold THRESHOLD | 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. |
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.