Framework for creating and using a Face Recognition system.
This repository provides a simple framework for creating and using Face Recognition system. There is also a blog post associated with this repository which gives more details about the framework.
Installation
Make sure you have Python 3.5+ and
pip installed.
Install dependencies
pip install -r requirements.txt
Train the Face Recognition system
In order to train the Face Recognition system the user needs to provide images of people in a folder with the following structure:
- images
- person1
- person1_1.png
- person1_2.png
...
- person1_n.png
- person2
...
- personN
...
Every directory contains images of one person (the more images the better), and every image must contain only one face of a person.
After preparing the images run the following command to train the Face Recognition system:
./tasks/train.sh path/to/folder/with/images
The previous command will generate model/face_recogniser.pkl which represents the trained Face Recognition system.
train.py has other options for training too. Slow part of training is generating embeddings from images. You could
pre-generate embeddings with util/generate_embeddings.py and then just forward path to embeddings to train script,
that would speed up experimenting with training a lot.
usage: train.py [-h] [-d DATASET_PATH] [-e EMBEDDINGS_PATH] [-l LABELS_PATH]
[-c CLASS_TO_IDX_PATH] [--grid-search]
Script for training Face Recognition model. You can either give path to
dataset or provide path to pre-generated embeddings, labels and class_to_idx.
You can pre-generate this with util/generate_embeddings.py script.
optional arguments:
-h, --help show this help message and exit
-d DATASET_PATH, --dataset-path DATASET_PATH
Path to folder with images.
-e EMBEDDINGS_PATH, --embeddings-path EMBEDDINGS_PATH
Path to file with embeddings.
-l LABELS_PATH, --labels-path LABELS_PATH
Path to file with labels.
-c CLASS_TO_IDX_PATH, --class-to-idx-path CLASS_TO_IDX_PATH
Path to pickled class_to_idx dict.
--grid-search If this option is enabled, grid search will be
performed to estimate C parameter of Logistic
Regression classifier. In order to use this option you
have to have at least 3 examples of every class in
your dataset. It is recommended to enable this option.
Using Face Recognition
After training the Face Recognition system you can use it in several ways. You can use one of the inference scripts or via a REST API.
Inference scripts
The inference directory contains scripts which can be used with trained Face Recognition system.
classifier.py
A script for detecting and classifying faces on a user-provided image. This script will process the image, draw bounding boxes and labels on the image and display it. It will also optionally save that image.
python -m inference.classifier -h
usage: Script for detecting and classifying faces on user-provided image. This script will process image, draw bounding boxes and labels on image and display it. It will also optionally save that image.
[-h] --image-path IMAGE_PATH [--save-dir SAVE_DIR]
optional arguments:
-h, --help show this help message and exit
--image-path IMAGE_PATH
Path to image file.
--save-dir SAVE_DIR If save dir is provided image will be saved to
specified directory.
Example output (model trained with one image of each person):
video_classifier.py
A script for detecting and classifying faces on a video stream. It connects to the default camera and performs face detection and classification on every frame.
python -m inference.video_classifier
Video stream example:
Face Recognition API
You can use the trained Face Recognition system as a REST API. The api folder contains a simple
Flask API which provides frontend for the Face Recognition system.
Run the development server using the following command:
tasks/run_dev_server.sh
Run the production server using the following command:
tasks/run_prod_server.sh
The server is running on port 5000.
Swagger API docs are available upon running the server on <root-url>:5000/docs
POST /face-recognition
Example response:
{
"faces": [
{
"top_prediction": {
"label": "person1",
"confidence": 0.9051724841669186
},
"bounding_box": {
"left": 3103.2939949035645,
"top": 920.1620543003082,
"right": 3484.597170829773,
"bottom": 1605.22814142704
}
},
{
"top_prediction": {
"label": "person2",
"confidence": 0.5193666400755098
},
"bounding_box": {
"left": 1985.1384818404913,
"top": 950.2878819331527,
"right": 2383.1231556087732,
"bottom": 1566.2133588716388
}
}
]
}
Docker
The easiest way to run the Face Recognition API is through a Docker container.
Build the image:
docker build -t face-recognition-api:latest -f api/Dockerfile .
Run the server:
docker run --name face-recognition-api -d -p 5000:5000 face-recognition-api
WARNING If you are processing high-resolution images in a container with a limited amount of memory you could encounter an OOM error.
References
- F. Schroff, D. Kalenichenko, and J. Philbin. Facenet: A unified embedding for face recognition and clustering. arXiv preprint arXiv:1503.03832, 2015. PDF
- Zhang, K., Zhang, Z., Li, Z., Qiao, Y.: Joint face detection and alignment using multi-task cascaded convolutional networks. arXiv preprint arXiv:1604.02878 (2016) PDF
- https://github.com/timesler/facenet-pytorch
- https://github.com/davidsandberg/facenet