README.rst 7.27 KB
Newer Older
1 2 3 4 5 6 7 8 9 10 11
facedetect: a simple face detector for batch processing
=======================================================

`facedetect` is a simple face detector for batch processing. It answers the
basic question: "Is there a face in this image?" and gives back either an exit
code 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 easy
to use with software such as ImageMagick_, while progressively improving the
detection algorithm over time.

Andreas Tille's avatar
Andreas Tille committed
12 13
`facedetect` is used in software such as fgallery_ to improve the thumbnail
cutting region, so that faces are always centered.
14 15


Andreas Tille's avatar
Andreas Tille committed
16 17
Basic Usage
-----------
18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53

By default `facedetect` outputs the rectangles of all the detected faces::

  ./facedetect path/to/image.jpg
  289 139 56 56
  295 283 55 55

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 positions
directly overlaid on the source image using the ``-o`` flag::

  ./facedetect -o test.jpg path/to/image.jpg

To simply check if an image contains a face, use the ``-q`` switch and check
the exit status::

  ./facedetect -q path/to/image.jpg
  echo $?

An exit status of 0 indicates the presence of at least one face. An exit status
of 2 means that no face could be detected (1 is reserved for failures).

The ``--center`` flag also exists for scripting convenience, and simply outputs
the X Y coordinates of face centers::

  ./facedetect --center path/to/image.jpg
  317 167
  322 310

The ``--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 the
frame.

.. figure:: doc/biggest-best.jpg
  :align: center

Andreas Tille's avatar
Andreas Tille committed
54
  Comparison between ``--best`` (top) and ``--biggest`` (bottom). The
55 56 57 58 59 60 61 62 63 64 65 66 67
  chosen face is highlighted in yellow.

Unless DOF or motion blur is used effectively by the photographer to separate
the 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"
Andreas Tille's avatar
Andreas Tille committed
68
and "people" directories using the exit code::
69 70 71 72

  for file in path/to/pictures/*.jpg; do
    name=$(basename "$file")
    if facedetect -q "$file"; then
Andreas Tille's avatar
Andreas Tille committed
73
      mv "$file" "path/to/people/$name"
74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96
    else
      mv "$file" "path/to/landscape/$name"
    fi
  done

Blurring faces within an image
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The following example uses the coordinates from `facedetect` to pixelate the
faces in all the source images using `mogrify` (from ImageMagick_)::

  for file in path/to/pictures/*.jpg; do
    name=$(basename "$file")
    out="path/to/blurred/$name"
    cp "$file" "$out"
    facedetect "$file" | while read x y w h; do
      mogrify -gravity NorthWest -region "${w}x${h}+${x}+${y}" \
	-scale '10%' -scale '1000%' "$out"
    done
  done

Here ``mogrify`` is called for each output line of `facedetect` (which is
sub-optimal), modifying the file in-place.

Andreas Tille's avatar
Andreas Tille committed
97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128
Extracting all faces to separate images
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The following example uses ``convert`` from ImageMagick_ to extract each
face in each source image ``img.jpg`` to a separated image ``img_N.jpg``::

  for file in path/to/pictures/*.jpg; do
    name=$(basename "$file")
    i=0
    facedetect "$file" | while read x y w h; do
      convert "$file" -crop ${w}x${h}+${x}+${y} "path/to/faces/${name%.*}_${i}.${name##*.}"
      i=$(($i+1))
    done
  done


Searching for a face
--------------------

`facedetect` has some naïve support to search for a specific face as supplied
with the ``-s`` file argument. The file provided must be an image containing
preferably a *single* face. `facedetect` will then compare all faces against
it, and output only the matches which are above the requested similarity
threshold (30% by default).

When face search is used with ``-q`` (query), and exit status of 0 is only
emitted if there is at least one face matching the requested template.

The similarity threshold can be controlled with ``--search-threshold``, which
is a value between -100 and 100, with greater values resulting in greater
similarity. The current matching algorithm is based on simple MSSIM which is
far from perfect (see `Development status and ideas`_).

129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171

Dependencies
------------

The following software is currently required for `facedetect`:

- Python
- Python OpenCV (``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 python python-opencv libopencv-dev

and then install `facedetect` with::

  sudo cp facedetect /usr/local/bin


Development status and ideas
----------------------------

Currently `facedetect` is not much beyond a simple wrapper over the Haar
Cascade classifier of OpenCV and the ``frontalface_alt2`` profile, which
provided 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 theory
states that it should also be more accurate, the ``lbp_frontalface`` profile
didn't provide comparable results, suggesting that additional training is
necessary. If some training dataset is found though, creating an LBP profile
would 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, to
reduce the false positive rates and/or rank the regions, might be a very good
solution instead.

Both LBP and Haar don't play too well with rotated faces. This is particularly
evident with "artistic" portraits shot at an angle. Pre-rotating the image
using the information from a Hough transform might boost the detection rate in
many cases, and should be relatively straightforward to implement.

Andreas Tille's avatar
Andreas Tille committed
172 173 174 175 176 177 178 179 180 181 182 183
Face matching has the interface that user's expect ("find me *this* face"), but
doesn'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 faces
that have comparable orientation, expression and lighting conditions. HAAR
features do not provide the positioning accuracy required to perform even the
simplest face segmentation operations, such as inter-eye distance.
Interestingly, computing a score using 1:1 SIFT feature matches performed even
worse than plain MSSIM (not enough granularity in most scenarios). Building a
GUI 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 somehow
deviates from the original intention of unsupervised search.

184 185 186 187

Authors and Copyright
---------------------

Andreas Tille's avatar
Andreas Tille committed
188
`facedetect` can be found at https://www.thregr.org/~wavexx/software/facedetect/
189

Andreas Tille's avatar
Andreas Tille committed
190 191
| `facedetect` is distributed under GPLv2+ (see COPYING) WITHOUT ANY WARRANTY.
| Copyright(c) 2013-2016 by wave++ "Yuri D'Elia" <wavexx@thregr.org>.
192 193 194 195 196

facedetect's GIT repository is publicly accessible at::

  git://src.thregr.org/facedetect

Andreas Tille's avatar
Andreas Tille committed
197 198
or at https://github.com/wavexx/facedetect

199 200

.. _ImageMagick: http://www.imagemagick.org
Andreas Tille's avatar
Andreas Tille committed
201
.. _fgallery: https://www.thregr.org/~wavexx/software/fgallery/