Package: deface
deface: Video anonymization by face detectiondefaceis 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.
By default all audio tracks are discarded as well.Original framedefaceoutput (using default options)Installationdefacesupports 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 installingdefaceis 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 ofdefaceand all necessary dependencies by running:$ python3 -m pip install defaceAlternatively, if you want to use the latest (unreleased) revision directly from GitHub, you can run:$ python3 -m pip install 'git+https://github.com/ORB-HD/deface'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:$ deface 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 rundefaceon the live video input by calling it with thecamargument instead of an input path:$ deface camThis is a shortcut for$ deface --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:$ deface -hThe output may vary depending on your installed version, but it should look similar to this:usage: deface [--output O] [--thresh T] [--scale WxH] [--preview] [--boxes]
              [--draw-scores] [--mask-scale M]
              [--replacewith {blur,solid,none,img,mosaic}]
              [--replaceimg REPLACEIMG] [--mosaicsize width] [--keep-audio]
              [--ffmpeg-config FFMPEG_CONFIG] [--backend {auto,onnxrt,opencv}]
              [--execution-provider EP] [--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. `$ deface 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 `$ deface cam` (which
                        is a shortcut for `$ deface -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,mosaic}
                        Anonymization filter mode for face regions. "blur"
                        applies a strong gaussian blurring, "solid" draws a
                        solid black box, "none" does leaves the input
                        unchanged, "img" replaces the face with a custom image
                        and "mosaic" replaces the face with mosaic. Default:
                        "blur".
  --replaceimg REPLACEIMG
                        Anonymization image for face regions. Requires
                        --replacewith img option.
  --mosaicsize width    Setting the mosaic size. Requires --replacewith mosaic
                        option. Default: 20.
  --keep-audio, -k      Keep audio from video source file and copy it over to
                        the output (only applies to videos).
  --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).
  --execution-provider EP, --ep EP
                        Override onnxrt execution provider (see
                        https://onnxruntime.ai/docs/execution-providers/). If
                        not specified, the presumably fastest available one
                        will be automatically selected. Only used if backend is
                        onnxrt.
  --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:$ deface examples/city.jpg --boxes --replacewith solid -o examples/city_anonymized_boxes.jpgMosaic anonymizationAnother common anonymization option is to draw a mosaic pattern over faces. This is supported with the--replacewith mosaicoption. The width of each of the quadratic mosaic fragments can be determined using the--mosaicsizeoption (default value: 20). Note that the mosaic size is measured in pixels, so you should consider increasing the size when processing higher-resolution inputs.Usage example:$ deface examples/city.jpg --replacewith mosaic --mosaicsize 20 -o examples/city_anonymized_mosaic.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.$ deface 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 issuesSincedefacetries 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,defacesupports 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 speed up neural network inference by enabling the optionalONNX Runtimebackend ofdeface. For optimal performance you should install it with appropriateExecution Providersfor your system. If you have multiple Execution Providers installed, ONNX Runtime will try to automatically use the fastest one available.Here are some recommendations for common setups:CUDA (only for 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.DirectML (only for Windows)Windows users with capable non-Nvidia GPUs can enable GPU-accelerated inference with DirectML by installing:$ python3 -m pip install onnx onnxruntime-directmlOpenVINOOpenVINO can accelerate inference even on CPU-only systems by a few percent, compared to the default OpenCV and ONNX Runtime implementations. It works on Linux and Windows, but not yet on Python 3.11 as of July 2023. Install the backend with:$ python3 -m pip install onnx onnxruntime-openvinoOther platformsIf you your setup doesn't fit with these recommendations, look into the available options at theExecution Providerdocumentation and find the respective installation instructions 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,defacecan 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.pyis based onhttps://github.com/Star-Clouds/centerface(revision8c39a49),released under MIT licenseThe included model filecenterface.onnxis an unmodified copy of thecenterface_bnmerged.onnxfromhttps://github.com/Star-Clouds/centerfaceThe original source of the example images in theexamplesdirectory can be foundhere(released under thePexels photo license)