FacePy is a Python framework that allows you to use a number of facial recognition algorithms for both verification and identification purposes. It makes use of the OpenCV and Dlib libraries for processing and recognition tasks, and the LFW dataset for training and performance evaluation.
The system has been developed as the end of year project for the Image Processing and Computer Vision exam.
FacePy has only been tested on macOS 10.14 Mojave, though it should work on earlier macOS releases as well. I believe this can also run on other platforms with zero-to-minor modifications, though multi-platform support is out of scope.
It requires a working Python 3 interpreter, as well as CMake (which is needed to build Dlib). The easiest way to install both dependencies on macOS is via HomeBrew. Once HomeBrew is installed:
brew install python3 cmake
FacePy comes with a setup script that downloads and installs all the required dependencies. Python package dependencies are automatically installed in a fresh venv in order to avoid messing with globally installed packages.
To install FacePy:
- Clone this repository:
git clone https://github.com/IvanoBilenchi/facepy.git
- Run the setup script:
cd facepy && ./setup.sh
- Wait until installation ends (it may take a few minutes).
To uninstall FacePy, just delete the facepy
dir.
FacePy can be run interactively for verification, or in batch mode for both verification and identification (classification). You can run it by invoking the ./bin/facepy
script via terminal, which accepts a number of subcommands and flags.
To list the available subcommands, run ./bin/facepy -h
. If you need help with a specific subcommand, run ./bin/facepy <subcommand> -h
.
Here are a few usage examples to get you started.
Interactive usage allows you to train verifiers via the webcam, and to use trained verifiers for authentication.
-
Train a verifier:
./bin/facepy train-verifier
- Press
space
to acquire samples. - Press
enter
to train the verifier. - Wait until the system finishes training the verifier.
- Press
esc
to exit.
-
Use the trained verifier:
./bin/facepy verify
- The detected face will be colored in green or red depending on whether the person standing in front of the webcam has been recognized.
- Press
esc
to exit.
Important note: facial landmark positions are rendered on the webcam view in order to provide feedback w.r.t. the accuracy of the pose estimator, which is a critical part of the system: if the detected landmarks are inaccurate or wobbly, it means you must either:
- Get closer to the webcam.
- Move to a place with better illumination.
- Get a better webcam 😜
Batch usage allows you to train verifiers and classifiers and to evaluate their performance via classical metrics. It is important to note that FacePy will filter the dataset by ignoring non-frontal samples: you can run ./bin/facepy info
to know how many samples the framework will really use for training and evaluation purposes.
-
Train and evaluate a verifier:
- Find individuals having at least 20 frontal samples in the dataset:
./bin/facepy info -m 20
- Train a verifier using the first 10 samples for the specified individual:
./bin/facepy train-verifier -d res/lfw/Tony_Blair -m 10
- Evaluate the verifier, skipping the first 10 samples (account for training set):
./bin/facepy evaluate-verifier -s 10
- The framework will report some classical performance statistics for the verifier (confusion matrix, accuracy, precision, recall, etc.).
- Find individuals having at least 20 frontal samples in the dataset:
-
Train and evaluate a classifier:
- Train a classifier for all the individuals having at least 15 frontal samples, using the first 10 for training:
./bin/facepy train-classifier -m 15 -t 10
- Evaluate the classifier, skipping the first 10 samples for each individual (account for training set):
./bin/facepy evaluate-classifier -s 10
- The framework will report per-class and average statistics.
w_avg
is a weighted average based on the amount of test samples for each individual.
- Train a classifier for all the individuals having at least 15 frontal samples, using the first 10 for training:
FacePy supports five different recognition algorithms:
- Eigenfaces, Fisherfaces and LBPH, from the OpenCV library.
- Dlib's CNN recognizer (default).
- An old-school geometric algorithm based on Dlib's pose estimator.
You can choose a specific algorithm via the -a
flag when training verifiers or classifiers:
./bin/facepy train-verifier -d res/lfw/George_W_Bush -m 15 -a LBPH
Supported values are EIGEN
, FISHER
, LBPH
, CNN
and GEOMETRIC
.
FacePy is available under the MIT license. See the LICENSE file for more info.