Package: anonfaces
anonfaces: Video anonymization by face detectionanonfacesis a simple command-line tool for automatic anonymization of faces in videos or photos.
It works by first detecting all human faces in each video frame and then applying an anonymization filter (blurring or black boxes) on each detected face region.
All audio tracks are discarded as well.Original frameanonfacesoutput (using default options)Installationanonfacessupports all commonly used operating systems (Linux, Windows, MacOS), but it requires using a command-line shell such as bash. There are currently no plans of creating a graphical user interface.The recommended way of installinganonfacesis via thepippackage manager. This requires that you have Python 3.6 or later installed on your system. It is recommended to set up and activate a newvirtual environmentfirst. Then you can install the latest release ofanonfacesand all necessary dependencies by running:$ python3 -m pip install anonfacesAlternatively, if you want to use the latest (unreleased) revision directly from GitHub, you can run:$ python3 -m pip install 'git+https://github.com/StealUrKill/anonfaces'This will only install the dependencies that are strictly required for running the tool. If you want to speed up processing by enabling hardware acceleration, you will need to manually install additional packages, seeHardware accelerationUsageQuick startIf you want to try out anonymizing a video using the default settings, you just need to supply the path to it. For example, if the path to your test video ismyvideos/vid1.mp4, run:$ anonfaces myvideos/vid1.mp4This will write the the output to the new video filemyvideos/vid1_anonymized.mp4.Live capture demoIf you have a camera (webcam) attached to your computer, you can runanonfaceson the live video input by calling it with thecamargument instead of an input path:$ anonfaces camThis is a shortcut for$ anonfaces --preview '<video0>', where'<video0>'(literal) is a  camera device identifier. If you have multiple cameras installed, you can try'<videoN>', whereNis the index of the camera (seeimageio-ffmpeg docs).CLI usage and options summaryTo get an overview of usage and available options, run:$ anonfaces -hThe output may vary depending on your installed version, but it should look similar to this:usage: anonfaces [--output O] [--thresh T] [--scale WxH] [--preview] [--boxes]
              [--draw-scores] [--mask-scale M]
              [--replacewith {blur,solid,none,img}] [--replaceimg REPLACEIMG]
              [--ffmpeg-config FFMPEG_CONFIG] [--backend {auto,onnxrt,opencv}]
              [--version] [--help]
              [input ...]

Video anonymization by face detection

positional arguments:
  input                 File path(s) or camera device name. It is possible to
                        pass multiple paths by separating them by spaces or by
                        using shell expansion (e.g. `$ anonfaces vids/*.mp4`).
                        Alternatively, you can pass a directory as an input,
                        in which case all files in the directory will be used
                        as inputs. If a camera is installed, a live webcam
                        demo can be started by running `$ anonfaces cam` (which
                        is a shortcut for `$ anonfaces -p '<video0>'`.

optional arguments:
  --output O, -o O      Output file name. Defaults to input path + postfix
                        "_anonymized".
  --thresh T, -t T      Detection threshold (tune this to trade off between
                        false positive and false negative rate). Default: 0.2.
  --scale WxH, -s WxH   Downscale images for network inference to this size
                        (format: WxH, example: --scale 640x360).
  --preview, -p         Enable live preview GUI (can decrease performance).
  --boxes               Use boxes instead of ellipse masks.
  --draw-scores         Draw detection scores onto outputs.
  --mask-scale M        Scale factor for face masks, to make sure that masks
                        cover the complete face. Default: 1.3.
  --replacewith {blur,solid,none,img}
                        Anonymization filter mode for face regions. "blur"
                        applies a strong gaussian blurring, "solid" draws a
                        solid black box, "none" does leaves the input
                        unchanged and "img" replaces the face with a custom
                        image. Default: "blur".
  --replaceimg REPLACEIMG
                        Anonymization image for face regions. Requires
                        --replacewith img option.
  --ffmpeg-config FFMPEG_CONFIG
                        FFMPEG config arguments for encoding output videos.
                        This argument is expected in JSON notation. For a list
                        of possible options, refer to the ffmpeg-imageio docs.
                        Default: '{"codec": "libx264"}'.
  --backend {auto,onnxrt,opencv}
                        Backend for ONNX model execution. Default: "auto"
                        (prefer onnxrt if available).
  --version             Print version number and exit.
  --help, -h            Show this help message and exit.Usage examplesIn most use cases the default configuration should be sufficient, but depending on individual requirements and type of media to be processed, some of the options might need to be adjusted. In this section, some common example scenarios that require option changes are presented. All of the examples use the photoexamples/city.jpg, but they work the same on any video or photo file.Drawing black boxesBy default, each detected face is anonymized by applying a blur filter to an ellipse region that covers the face. If you prefer to anonymize faces by drawing black boxes on top of them, you can achieve this through the--boxesand--replacewithoptions:$ anonfaces examples/city.jpg --boxes --replacewith solid -o examples/city_anonymized_boxes.jpgTuning detection thresholdsThe detection threshold (--thresh,-t) is used to define how confident the detector needs to be for classifying some region as a face. By default this is set to the value 0.2, which was found to work well on many test videos.If you are experiencing too many false positives (i.e. anonymization filters applied at non-face regions) on your own video data, consider increasing the threshold.
On the other hand, if there are too many false negative errors (visible faces that are not anonymized), lowering the threshold is advisable.The optimal value can depend on many factors such as video quality, lighting conditions and prevalence of partial occlusions. To optimize this value, you can set threshold to a very low value and then draw detection score overlays, as described in thesection below.To demonstrate the effects of a threshold that is set too low or too high, see the examples outputs below:--thresh 0.02(notice the false positives, e.g. at hand regions)--thresh 0.7(notice the false negatives, especially at partially occluded faces)Drawing detection score overlaysIf you are interested in seeing the faceness score (a score between 0 and 1 that roughly corresponds to the detector's confidence that somethingisa face) of each detected face in the input, you can enable the--draw-scoresoption to draw the score of each detection directly above its location.$ anonfaces examples/city.jpg --draw-scores -o examples/city_anonymized_scores.jpgThis option can be useful to figure out an optimal value for the detection threshold that can then be set through the--threshoption.High-resolution media and performance issuesSinceanonfacestries to detect faces in the unscaled full-res version of input files by default, this can lead to performance issues on high-res inputs (>> 720p). In extreme cases, even detection accuracy can suffer because the detector neural network has not been trained on ultra-high-res images.To counter these performance issues,anonfacessupports downsampling its inputs on-the-fly before detecting faces, and subsequently rescaling detection results to the original resolution. Downsampling only applies to the detection process, whereas the final output resolution remains the same as the input resolution.This feature is controlled through the--scaleoption, which expects a value of the formWxH, whereWandHare the desired width and height of downscaled input representations.
It is very important to make sure the aspect ratio of the inputs remains intact when using this option, because otherwise, distorted images are fed into the detector, resulting in decreased accuracy.For example, if your inputs have the common aspect ratio 16:9, you can instruct the detector to run in 360p resolution by specifying--scale 640x360.
If the results at this fairly low resolution are not good enough, detection at 720p input resolution (--scale 1280x720) may work better.Hardware accelerationDepending on your available hardware, you can often speed up neural network inference by enabling the optionalONNX Runtimebackend ofanonfaces.CUDA (on Nvidia GPUs)If you have a CUDA-capable GPU, you can enable GPU acceleration by installing the relevant packages:$ python3 -m pip install onnx onnxruntime-gpuIf theonnxruntime-gpupackage is found and a GPU is available, the face detection network is automatically offloaded to the GPU.
This can significantly improve the overall processing speed.Other platformsIf your machine doesn't have a CUDA-capable GPU but you want to accelerate computation on another hardware platform (e.g. Intel CPUs), you can look into the available options in theONNX Runtime build matrix.How it worksThe included face detection system is based on CenterFace (code,paper), a deep neural network optimized for fast but reliable detection of human faces in photos.
The network was trained on theWIDER FACEdataset, which contains annotated photos showing faces in a wide variety of scales, poses and occlusions.Although the face detector is originally intended to be used for normal 2D images,anonfacescan also use it to detect faces in video data by analyzing each video frame independently.
The face bounding boxes predicted by the CenterFace detector are then used as masks to determine where to apply anonymization filters.Creditscenterface.onnx(original) andcenterface.py(modified) are based onhttps://github.com/Star-Clouds/centerface(revision8c39a49),released under MIT license.The original source of the example images in theexamplesdirectory can be foundhere(released under thePexels photo license).