FACE-DETECTION ALGORITHM WITH A CONTRARIO ADJUSTMENT OF DETECTION THRESHOLDS 

Version 4.0 - July 17, 2019
by Jose-Luis Lisani <joseluis.lisani@uib.es>


ASSOCIATED PUBLICATION

This code is associated to the following IPOL publication:

J.L. Lisani, Silvia Ramis
A Contrario Detection of Faces with a Short Cascade of
Classifiers
Image Processing On Line (IPOL), www.ipol.im

An online demo that uses the code is available at IPOL


ORGANIZATION OF THE CODE

The code is organized as follows:

- a folder 'library' containing the following: 
	- io_RGB.h, io_RGB.cpp: functions for the management of
	the RGB channels of an image and the computation of the 
	intensity component
	- io_png folder: containing code for reading/writing
	PNG images
	- parser.h, parser.cpp: functions for the management of the
	input parameters of the main function
	- randmt.h, randmt.c: functions for the generation of random numbers
	- tools_lib.h, tools_lib.cpp: auxiliary functions for sub-image extraction,
	rescaling, etc.
	- inversegaussiancdf.h: function to compute the value of z such that
	P(Z > z)=a, where Z is the standard Gaussian distribution with 0 mean and
	unit variance and a is an input parameter
	distribution function
	- lib_features.h, lib_features.cpp: functions for checking that an image
	sub-window of size 24x24 contains a face, according to a given classifier
	- lib_facedet.h, lib_facedet.cpp: functions implementing the algorithms
	described in the associated publication
	
- a folder 'classifiers' containing the data of 4 face-classifiers
using 5, 10, 80 and 200 features, respectively. The folder also contains
a README.txt file describing the data in the files.

- a folder 'test' with an image ('solvay1927.png') to test the code	
	
- facedet.cpp: the main function
- makefile: for compilation
- computeNFPs.py: a python script to compute the Number of False Positives (NFP)
                  associated to each detection
- README.txt: this file
- agpl-3.0.txt: GNU Affero General Public License 


The codes submitted for review at IPOL are:
- library/lib_facedet.h, library/lib_facedet.cpp 
- library/lib_features.h, library/lib_features.cpp
- inversegaussiancdf.h


RELATION BETWEEN CODE AND PSEUDOCODE

The different parts of the 6 algorithms described in the accompanying paper 
are implemented in the following functions:

- Algorithm 1: it is not implemented since face detection using a single
classifier is not computationally efficient (as commented in the paper).

- Algorithm 2:
    - 'ApplyClassifier' is implemented in functions 'applyclassifier',
    'check_featuresimage' and 'check_subimage' of lib_facedet.cpp, and
    in function 'check_features_imageStandard' of lib_features.cpp
    - 'GetQuantile' is implemented in lines 571-573 and 591-593 of 
    'detectfaces' in lib_facedet.cpp
    - 'SampleSubWindows' is implemented in function 'random_detections'
    of lib_facedet.cpp
    - 'GetMeanStandardDev' is implemented in function 'detections_stats'
    of lib_facedet.cpp
    - F^{-1}, used in lines 9 and 12 of the pseudocode is implemented
    in inversegaussiancdf.h
    - the rest of the steps of the algorithm are implemented in function
    'detectfaces' of lib_facedet.cpp


- Algorithm 3 ('GetSubWindows' function called from Algorithm 2): 
    - lines 1 to 3 of the pseudo-code are implemented in function 
    'zoom_factors' of lib_facedet.cpp
    - the loop in line 5 is implemented in function 'applyclassifier'
    of lib_facedet.cpp
    - 'RescaleImage' is implemented in function 'zoom_image' of tools_lib.cpp
    - 'GetSubWindow' is implemented in function 'getsubimage' of tools_lib.cpp
    - the computation of the variance of the intensity levels of a sub-window 
    and 'NormalizeVariance' are implemented in function 'normalize_variance' 
    of lib_features.cpp
    
- Algorithm 4 is implemented in function 'detectfaces' of lib_facedet.cpp
    
- Algorithm 5 is implemented, setting parameter 'usemirror' to TRUE, 
in functions 'applyclassifier', 'check_featuresimage' and 'check_subimage' 
of lib_facedet.cpp. 'HorizontalFlip' is implemented in function 'mirror_image'
of tools_lib.cpp

- Algorithm 6 is implemented in function 'detections_prune' of lib_facedet.cpp.
The intersection between sub-windows is implemented in function 
'check_superposition_rectangles' of tools_lib.cpp


Remark about Algorithms 2 and 3:

The implementation of these algorithms differs slightly from the description
in the associated publication. 
The reason is that it is easier to describe the detection method if we
consider that all the sub-windows are extracted at the beginning of the 
algorithm (line 1 in Algorithm 2) and that they are subsequently processed.
However, it is not practical to store in memory or disk the huge amount of 
extracted sub-windows. In practice, sub-windows are extracted as they are 
needed, in functions 'applyclassifier' and 'check_featuresimage' of 
lib_facedet.cpp. For this reason the implementation of Algorithm 3 
('GetSubWindows' function called from Algorithm 2) is scattered over several
functions of the code.




COMPILATION

1) Decompress code and access to folder:
tar xvzf facedetIPOL.tgz
cd facedetIPOL

2) Compilation:
make OMP=1 #compilation using OMP directives, to compile without them use: make

The executable file obtained after compilation is 'facedet'.



USAGE

facedet [-n n] [-s s] [-l l]  input  classifiers  output 
	-n  n	 Maximum number of false positives (Default: 1)
	-s  s	 Minimum size (pixels) of detected faces (Default: 24)
	-l  l	 Maximum size (pixels) of detected faces (Default: 220)
	-z  z	 Size increase factor of checked subwindows (if 1 check all 
	         subwindows in size range) (Default: 1)
	input	 input image
	classifiers	 folder containing learned image classifiers
	output	 root name of output files 

The outputs of the algorithm are:
- output.png, an image displaying the position of the detected faces
- output.txt, a text file containing the position of the detected faces
- output_det_stats.txt, a text file contating the detection data of the
detected faces. It is used as input of the python script 'computeNFPs.py'
to compute the number of false positives associated to each detected subwindow


The format of the text file is:

w h
x1 y1 x2 y2
x1 y1 x2 y2
...

where w and h are the width and height of the input image
and (x1, y1), (x2, y2) are the top-left a bottom-right 
coordinates of the detected faces. Each line of x1 y1 x2 y2
values corresponds to a different detection.


IMPORTANT NOTE

The program only admits PNG input images.
The output images are also in this format.
In Linux or MacOS you can use the ImageMagicks'convert' 
function to convert any graphic file to PNG format.
 

EXAMPLES OF USE

(Assuming that the code is run from the 'facedetIPOL' folder)

1) Detect faces in image ./test/solvay1927.png using the set
of default classifiers in ./classifiers and write the results 
to ./test
Use default values for maximum number of false positives (1),
minimum and maximum size of detections (24 and 220, respectively),
and size increase factor (1).

./facedet ./test/solvay1927.png ./classifiers ./test/output 

2) Detect faces in image ./test/solvay1927.png using the set
of default classifiers in ./classifiers and write the results 
to ./test
Use default values for maximum number of false positives (1),
minimum and maximum size of detections (24 and 220, respectively),
and set default size increase factor to 1.1 (10% increase in size).

./facedet ./test/solvay1927.png ./classifiers ./test/output -z 1.1

(a significant reduction of the execution time with 
respect to the previous example should be observed)

3) Detect faces in image ./test/solvay1927.png using the set
of default classifiers in ./classifiers and write the results 
to ./test
Set the maximum number of false positives to 100
and the minimum and maximum size of detections to 25 and 100, respectively.

./facedet ./test/solvay1927.png ./classifiers ./test/output -n 100 -s 25 -l 100


4) Compute NFP for detected subwindows (results saved in /test/output_nfps.txt)

./computeNFPs.py ./test/output_det_stats.txt ./test/output_nfps.txt 



COPYRIGHT AND LICENSE

Copyright (c) 2019 J.L. Lisani

This program is free software: you can redistribute it and/or modify
it under the terms of the GNU Affero General Public License as
published by the Free Software Foundation, either version 3 of the
License, or (at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU Affero General Public License for more details.

You should have received a copy of the GNU Affero General Public License
along with this program. If not, see <http://www.gnu.org/licenses/>.


THANKS

We would be grateful to receive any comment, especially about errors, bugs,
or strange results. Address them to joseluis.lisani@uib.es