Package: facedetectpy
facedetect: a simple face detector for batch processing=======================================================`facedetect` is a simple face detector for batch processing. It answers thebasic question: "Is there a face in this image?" and gives back either an exitcode or the coordinates of each detected face in the standard output.The aim is to provide a basic command-line interface that's consistent and easyto use with software such as ImageMagick_, while progressively improving thedetection algorithm over time.`facedetect` is used in software such as fgallery_ to improve the thumbnailcutting region, so that faces are always centered.Installing from PyPi--------------------$ pip install facedetect-pyBasic Usage-----------By default `facedetect` outputs the rectangles of all the detected faces::./bin/facedetect path/to/input.jpg289 139 56 56295 283 55 55Output :X, Y, Width HeightX1, Y1, Width1, Height1...The output values are the X Y coordinates **(from the top-left corner)**,followed by width and height. For debugging, you can examine the face positionsdirectly overlaid on the source image using the ``-o`` flag::./bin/facedetect -o outfile.jpg path/to/input.jpgTo simply check if an image contains a face, use the ``-q`` switch and checkthe exit status::./bin/facedetect -q path/to/input.jpgecho $?An exit status of **0 indicates the presence of at least one face**. An exit statusof 2 means that no face could be detected (1 is reserved for failures).The ``--center`` flag also exists for scripting convenience, and simply outputsthe X Y coordinates of face centers::./bin/facedetect --center path/to/image.jpg317 167322 310The ``--biggest`` flag only outputs the biggest face in the image, while``--best`` will attempt to select the face in focus and/or in the center of theframe... figure:: doc/biggest-best.jpg:align: centerComparison between ``--best`` (top) and ``--biggest`` (bottom). Thechosen face is highlighted in yellow.Unless DOF or motion blur is used effectively by the photographer to separatethe subject, ``--biggest`` would in most cases select the same face as``--best``, while being significantly faster to compute.Examples--------Sorting images with and without faces~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~The following example sorts pictures into two different "landscape"and "people" directories using the exit code::for file in path/to/pictures/*.jpg; doname=$(basename "$file")if ./bin/facedetect -q "$file"; thenmv "$file" "path/to/people/$name"elsemv "$file" "path/to/landscape/$name"fidoneBlurring faces within an image~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~The following example uses the coordinates from `facedetect` to pixelate thefaces in all the source images using `mogrify` (from ImageMagick_)::for file in path/to/pictures/*.jpg; doname=$(basename "$file")out="path/to/blurred/$name"cp "$file" "$out"./bin/facedetect "$file" | while read x y w h; domogrify -gravity NorthWest -region "${w}x${h}+${x}+${y}" \-scale '10%' -scale '1000%' "$out"donedoneHere ``mogrify`` is called for each output line of `facedetect` (which issub-optimal), modifying the file in-place.Extracting all faces to separate images~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~The following example uses ``convert`` from ImageMagick_ to extract eachface in each source image ``img.jpg`` to a separated image ``img_N.jpg``::for file in path/to/pictures/*.jpg; doname=$(basename "$file")i=0./bin/facedetect "$file" | while read x y w h; doconvert "$file" -crop ${w}x${h}+${x}+${y} "path/to/faces/${name%.*}_${i}.${name##*.}"i=$(($i+1))donedoneSearching for a face--------------------`facedetect` has some naïve support to search for a specific face as suppliedwith the ``-s`` file argument. The file provided must be an image containingpreferably a *single* face. `facedetect` will then compare all faces againstit, and output only the matches which are above the requested similaritythreshold (30% by default).When face search is used with ``-q`` (query), and exit status of 0 is onlyemitted if there is at least one face matching the requested template.The similarity threshold can be controlled with ``--search-threshold``, whichis a value between -100 and 100, with greater values resulting in greatersimilarity. The current matching algorithm is based on simple MSSIM which isfar from perfect (see `Development status and ideas`_).Dependencies------------The following software is currently required for `facedetect`:- Python 3 or Python 2.7- Python OpenCV >= 2.4 (``python3-opencv`` or ``python-opencv``)- OpenCV data files (``opencv-data`` if available, or ``libopencv-dev``)On Debian/Ubuntu, you can install all the required dependencies with::sudo apt-get install python3-opencv opencv-dataand then install `facedetect` with::sudo cp ./bin/facedetect /usr/local/binor create a softlink ::sudo ln -s "$(pwd)/bin/facedetect" /usr/local/binDevelopment status and ideas (Follows the original explanation by wavexx)-------------------------------------------------------------------------Currently `facedetect` is not much beyond a simple wrapper over the HaarCascade classifier of OpenCV and the ``frontalface_alt2`` profile, whichprovided the best results in terms of accuracy/detection rate for the general,real life photos at my disposal.In terms of speed, the LBP classifier was faster. But while the general theorystates that it should also be more accurate, the ``lbp_frontalface`` profiledidn't provide comparable results, suggesting that additional training isnecessary. If some training dataset is found though, creating an LBP profilewould probably be a better solution especially for the processing speed.``haar_profileface`` had too many false positives in my tests to be usable.Using it in combination with ``haar_eye`` (and other face parts) though, toreduce the false positive rates and/or rank the regions, might be a very goodsolution instead.Both LBP and Haar don't play too well with rotated faces. This is particularlyevident with "artistic" portraits shot at an angle. Pre-rotating the imageusing the information from a Hough transform might boost the detection rate inmany cases, and should be relatively straightforward to implement.Face matching has the interface that user's expect ("find me *this* face"), butdoesn't work as it should. Faces are currently compared using pairwise MSSIM,which is a far cry from proper face segmentation. MSSIM will only find facesthat have comparable orientation, expression and lighting conditions. HAARfeatures do not provide the positioning accuracy required to perform even thesimplest face segmentation operations, such as inter-eye distance.Interestingly, computing a score using 1:1 SIFT feature matches performed evenworse than plain MSSIM (not enough granularity in most scenarios). Building aGUI on top of facedetect to train SVM models (which can then be fed back to``-s``) seems a better way to go given the far greater accuracy, but somehowdeviates from the original intention of unsupervised search.Authors and Copyright---------------------The original `facedetect` can be found at https://www.thregr.org/~wavexx/software/facedetect/| `facedetect` is distributed under GPLv2+ (see COPYING) WITHOUT ANY WARRANTY.| Copyright(c) 2013-2017 by wave++ "Yuri D'Elia" <wavexx@thregr.org>.facedetect's GIT repository is publicly accessible at::git://src.thregr.org/facedetect (by wavexx)or at https://github.com/wavexx/facedetect (by wavexx)and at https://github.com/picovico/facedetect-py (by picovico).. _ImageMagick: http://www.imagemagick.org.. _fgallery: https://www.thregr.org/~wavexx/software/fgallery/