Face Recognition Documentation

Release 1.4.0

Adam Geitgey

Jun 14, 2021

 Contents

1 Face Recognition 3
1.1 Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
1.2 Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
1.3 Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
1.4 Python Code Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
1.5 Caveats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
1.6 Deployment to Cloud Hosts (Heroku, AWS, etc) . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
1.7 Common Issues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
1.8 Thanks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12

2 Installation 15
2.1 Stable release . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
2.2 From sources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

3 Usage 17

4 face_recognition 19
4.1 face_recognition package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

5 Contributing 23
5.1 Types of Contributions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
5.2 Get Started! . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
5.3 Pull Request Guidelines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
5.4 Tips . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24

6 Authors 27
6.1 Thanks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27

7 History 29
7.1 1.4.0 (2020-09-26) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
7.2 1.3.0 (2020-02-20) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
7.3 1.2.3 (2018-08-21) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
7.4 1.2.2 (2018-04-02) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
7.5 1.2.1 (2018-02-01) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
7.6 1.2.0 (2018-02-01) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
7.7 1.1.0 (2017-09-23) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
7.8 1.0.0 (2017-08-29) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30

i
 7.9 0.2.2 (2017-07-07) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
7.10 0.2.1 (2017-07-03) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
7.11 0.2.0 (2017-06-03) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
7.12 0.1.14 (2017-04-22) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
7.13 0.1.13 (2017-04-20) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
7.14 0.1.12 (2017-04-13) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
7.15 0.1.11 (2017-03-30) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
7.16 0.1.10 (2017-03-21) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
7.17 0.1.9 (2017-03-16) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
7.18 0.1.8 (2017-03-16) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
7.19 0.1.7 (2017-03-13) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32

8 Indices and tables 33

Python Module Index 35

Index 37

ii
 Face Recognition Documentation, Release 1.4.0

Contents:

Contents 1
Face Recognition Documentation, Release 1.4.0

2 Contents
 CHAPTER 1

Face Recognition

Recognize and manipulate faces from Python or from the command line with
the world’s simplest face recognition library.

Built using dlib’s state-of-the-art face recognition

built with deep learning. The model has an accuracy of 99.38% on the
Labeled Faces in the Wild benchmark.

This also provides a simple face_recognition command line tool that lets
you do face recognition on a folder of images from the command line!

1.1 Features

1.1.1 Find faces in pictures

Find all the faces that appear in a picture:

3
Face Recognition Documentation, Release 1.4.0

import face_recognition
image = face_recognition.load_image_file("your_file.jpg")
face_locations = face_recognition.face_locations(image)

1.1.2 Find and manipulate facial features in pictures

Get the locations and outlines of each person’s eyes, nose, mouth and chin.

import face_recognition
image = face_recognition.load_image_file("your_file.jpg")
face_landmarks_list = face_recognition.face_landmarks(image)

Finding facial features is super useful for lots of important stuff. But you can also use for really stupid stuff
like applying digital make-up (think ‘Meitu’):

4 Chapter 1. Face Recognition

 Face Recognition Documentation, Release 1.4.0

1.1.3 Identify faces in pictures

Recognize who appears in each photo.

import face_recognition
known_image = face_recognition.load_image_file("biden.jpg")
unknown_image = face_recognition.load_image_file("unknown.jpg")

biden_encoding = face_recognition.face_encodings(known_image)[0]
unknown_encoding = face_recognition.face_encodings(unknown_image)[0]

results = face_recognition.compare_faces([biden_encoding], unknown_encoding)

You can even use this library with other Python libraries to do real-time face recognition:

1.1. Features 5
Face Recognition Documentation, Release 1.4.0

See this example for the code.

1.2 Installation

1.2.1 Requirements

• Python 3.3+ or Python 2.7

• macOS or Linux (Windows not officially supported, but might work)

1.2.2 Installing on Mac or Linux

First, make sure you have dlib already installed with Python bindings:
• How to install dlib from source on macOS or Ubuntu
Then, install this module from pypi using pip3 (or pip2 for Python 2):
pip3 install face_recognition

If you are having trouble with installation, you can also try out a
pre-configured VM.

1.2.3 Installing on Raspberry Pi 2+

• Raspberry Pi 2+ installation instructions

1.2.4 Installing on Windows

While Windows isn’t officially supported, helpful users have posted instructions on how to install this library:
• @masoudr’s Windows 10 installation guide (dlib + face_recognition)

1.2.5 Installing a pre-configured Virtual Machine image

• Download the pre-configured VM image (for VMware Player or VirtualBox).

1.3 Usage

1.3.1 Command-Line Interface

When you install face_recognition, you get a simple command-line program

called face_recognition that you can use to recognize faces in a
photograph or folder full for photographs.

First, you need to provide a folder with one picture of each person you

6 Chapter 1. Face Recognition

 Face Recognition Documentation, Release 1.4.0

already know. There should be one image file for each person with the
files named according to who is in the picture:

Next, you need a second folder with the files you want to identify:

Then in you simply run the command face_recognition, passing in

the folder of known people and the folder (or single image) with unknown
people and it tells you who is in each image:

1.3. Usage 7
Face Recognition Documentation, Release 1.4.0

$ face_recognition ./pictures_of_people_i_know/ ./unknown_pictures/

/unknown_pictures/unknown.jpg,Barack Obama
/face_recognition_test/unknown_pictures/unknown.jpg,unknown_person

There’s one line in the output for each face. The data is comma-separated
with the filename and the name of the person found.

An unknown_person is a face in the image that didn’t match anyone in

your folder of known people.

Adjusting Tolerance / Sensitivity

If you are getting multiple matches for the same person, it might be that
the people in your photos look very similar and a lower tolerance value
is needed to make face comparisons more strict.

You can do that with the --tolerance parameter. The default tolerance
value is 0.6 and lower numbers make face comparisons more strict:

$ face_recognition --tolerance 0.54 ./pictures_of_people_i_know/ ./unknown_pictures/

/unknown_pictures/unknown.jpg,Barack Obama
/face_recognition_test/unknown_pictures/unknown.jpg,unknown_person

If you want to see the face distance calculated for each match in order
to adjust the tolerance setting, you can use --show-distance true:

$ face_recognition --show-distance true ./pictures_of_people_i_know/ ./unknown_

˓→pictures/

/unknown_pictures/unknown.jpg,Barack Obama,0.378542298956785
/face_recognition_test/unknown_pictures/unknown.jpg,unknown_person,None

More Examples

If you simply want to know the names of the people in each photograph but don’t
care about file names, you could do this:

$ face_recognition ./pictures_of_people_i_know/ ./unknown_pictures/ | cut -d ',' -f2

(continues on next page)

8 Chapter 1. Face Recognition

 Face Recognition Documentation, Release 1.4.0

(continued from previous page)

Barack Obama
unknown_person

Speeding up Face Recognition

Face recognition can be done in parallel if you have a computer with

multiple CPU cores. For example if your system has 4 CPU cores, you can
process about 4 times as many images in the same amount of time by using
all your CPU cores in parallel.

If you are using Python 3.4 or newer, pass in a --cpus <number_of_cpu_cores_to_use> parameter:

$ face_recognition --cpus 4 ./pictures_of_people_i_know/ ./unknown_pictures/

You can also pass in --cpus -1 to use all CPU cores in your system.

1.3.2 Python Module

You can import the face_recognition module and then easily manipulate
faces with just a couple of lines of code. It’s super easy!

API Docs: https://face-recognition.readthedocs.io.

Automatically find all the faces in an image

import face_recognition

image = face_recognition.load_image_file("my_picture.jpg")
face_locations = face_recognition.face_locations(image)

# face_locations is now an array listing the co-ordinates of each face!

See this example

to try it out.

You can also opt-in to a somewhat more accurate deep-learning-based face detection model.

Note: GPU acceleration (via nvidia’s CUDA library) is required for good
performance with this model. You’ll also want to enable CUDA support
when compliling dlib.

1.3. Usage 9
Face Recognition Documentation, Release 1.4.0

import face_recognition

image = face_recognition.load_image_file("my_picture.jpg")
face_locations = face_recognition.face_locations(image, model="cnn")

# face_locations is now an array listing the co-ordinates of each face!

See this example

to try it out.

If you have a lot of images and a GPU, you can also

find faces in batches.

Automatically locate the facial features of a person in an image

import face_recognition

image = face_recognition.load_image_file("my_picture.jpg")
face_landmarks_list = face_recognition.face_landmarks(image)

# face_landmarks_list is now an array with the locations of each facial feature in

˓→each face.

# face_landmarks_list[0]['left_eye'] would be the location and outline of the first

˓→person's left eye.

See this example

to try it out.

Recognize faces in images and identify who they are

import face_recognition

picture_of_me = face_recognition.load_image_file("me.jpg")
my_face_encoding = face_recognition.face_encodings(picture_of_me)[0]

# my_face_encoding now contains a universal 'encoding' of my facial features that can

˓→be compared to any other picture of a face!

unknown_picture = face_recognition.load_image_file("unknown.jpg")
unknown_face_encoding = face_recognition.face_encodings(unknown_picture)[0]

# Now we can see the two face encodings are of the same person with `compare_faces`!

results = face_recognition.compare_faces([my_face_encoding], unknown_face_encoding)

if results[0] == True:
print("It's a picture of me!")
else:
print("It's not a picture of me!")

10 Chapter 1. Face Recognition

 Face Recognition Documentation, Release 1.4.0

See this example

to try it out.

1.4 Python Code Examples

All the examples are available here.

1.4.1 Face Detection

• Find faces in a photograph

• Find faces in a photograph (using deep learning)
• Find faces in batches of images w/ GPU (using deep learning)

1.4.2 Facial Features

• Identify specific facial features in a photograph

• Apply (horribly ugly) digital make-up

1.4.3 Facial Recognition

• Find and recognize unknown faces in a photograph based on photographs of known people
• Compare faces by numeric face distance instead of only True/False matches
• Recognize faces in live video using your webcam - Simple / Slower Version (Requires OpenCV to be installed)
• Recognize faces in live video using your webcam - Faster Version (Requires OpenCV to be installed)
• Recognize faces in a video file and write out new video file (Requires OpenCV to be installed)
• Recognize faces on a Raspberry Pi w/ camera
• Run a web service to recognize faces via HTTP (Requires Flask to be installed)
• Recognize faces with a K-nearest neighbors classifier

How Face Recognition Works

If you want to learn how face location and recognition work instead of
depending on a black box library, read my article.

1.5 Caveats

• The face recognition model is trained on adults and does not work very well on children. It tends to mix up
children quite easy using the default comparison threshold of 0.6.

1.4. Python Code Examples 11

Face Recognition Documentation, Release 1.4.0

1.6 Deployment to Cloud Hosts (Heroku, AWS, etc)

Since face_recognition depends on dlib which is written in C++, it can be tricky to deploy an app
using it to a cloud hosting provider like Heroku or AWS.

To make things easier, there’s an example Dockerfile in this repo that shows how to run an app built with
face_recognition in a Docker container. With that, you should be able to deploy
to any service that supports Docker images.

1.7 Common Issues

Issue: Illegal instruction (core dumped) when using face_recognition or running examples.

Solution: dlib is compiled with SSE4 or AVX support, but your CPU is too old and doesn’t support that.
You’ll need to recompile dlib after making the code change outlined here.

Issue: RuntimeError: Unsupported image type, must be 8bit gray or RGB image. when
running the webcam examples.
Solution: Your webcam probably isn’t set up correctly with OpenCV. Look here for more.
Issue: MemoryError when running pip2 install face_recognition

Solution: The face_recognition_models file is too big for your available pip cache memory. Instead,
try pip2 --no-cache-dir install face_recognition to avoid the issue.

Issue: AttributeError: 'module' object has no attribute 'face_recognition_model_v1'

Solution: The version of dlib you have installed is too old. You need version 19.7 or newer. Upgrade dlib.
Issue: Attribute Error: 'Module' object has no attribute
'cnn_face_detection_model_v1'
Solution: The version of dlib you have installed is too old. You need version 19.7 or newer. Upgrade dlib.
Issue: TypeError: imread() got an unexpected keyword argument 'mode'
Solution: The version of scipy you have installed is too old. You need version 0.17 or newer. Upgrade scipy.

1.8 Thanks

• Many, many thanks to Davis King (@nulhom) for creating dlib and for providing the trained facial feature
detection and face encoding models used in this library. For more information on the ResNet that powers the
face encodings, check out his blog post.
• Thanks to everyone who works on all the awesome Python data science libraries like numpy, scipy, scikit-image,
pillow, etc, etc that makes this kind of stuff so easy and fun in Python.

12 Chapter 1. Face Recognition

 Face Recognition Documentation, Release 1.4.0

• Thanks to Cookiecutter and the audreyr/cookiecutter-pypackage project template for making Python project
packaging way more tolerable.

1.8. Thanks 13
Face Recognition Documentation, Release 1.4.0

14 Chapter 1. Face Recognition

 CHAPTER 2

Installation

2.1 Stable release

To install Face Recognition, run this command in your terminal:

$ pip3 install face_recognition

This is the preferred method to install Face Recognition, as it will always install the most recent stable release.
If you don’t have pip installed, this Python installation guide can guide you through the process.

2.2 From sources

The sources for Face Recognition can be downloaded from the Github repo.
You can either clone the public repository:

$ git clone git://github.com/ageitgey/face_recognition

Or download the tarball:

$ curl -OL https://github.com/ageitgey/face_recognition/tarball/master

Once you have a copy of the source, you can install it with:

$ python setup.py install

15
Face Recognition Documentation, Release 1.4.0

16 Chapter 2. Installation
 CHAPTER 3

Usage

To use Face Recognition in a project:

import face_recognition

See the examples in the /examples folder on github for how to use each function.
You can also check the API docs for the ‘face_recognition’ module to see the possible parameters for each function.
The basic idea is that first you load an image:
import face_recognition

image = face_recognition.load_image_file("your_file.jpg")

That loads the image into a numpy array. If you already have an image in a numpy array, you can skip this step.
Then you can perform operations on the image, like finding faces, identifying facial features or finding face encodings:
# Find all the faces in the image
face_locations = face_recognition.face_locations(image)

# Or maybe find the facial features in the image

face_landmarks_list = face_recognition.face_landmarks(image)

# Or you could get face encodings for each face in the image:
list_of_face_encodings = face_recognition.face_encodings(image)

Face encodings can be compared against each other to see if the faces are a match. Note: Finding the encoding for a
face is a bit slow, so you might want to save the results for each image in a database or cache if you need to refer back
to it later.
But once you have the encodings for faces, you can compare them like this:
# results is an array of True/False telling if the unknown face matched anyone in the
˓→known_faces array

results = face_recognition.compare_faces(known_face_encodings, a_single_unknown_face_

˓→encoding) (continues on next page)

17
Face Recognition Documentation, Release 1.4.0

(continued from previous page)

It’s that simple! Check out the examples for more details.

18 Chapter 3. Usage
 CHAPTER 4

face_recognition

4.1 face_recognition package

4.1.1 Module contents

face_recognition.api.batch_face_locations(images, number_of_times_to_upsample=1,
batch_size=128)
Returns an 2d array of bounding boxes of human faces in a image using the cnn face detector If you are using a
GPU, this can give you much faster results since the GPU can process batches of images at once. If you aren’t
using a GPU, you don’t need this function.
Parameters
• images – A list of images (each as a numpy array)
• number_of_times_to_upsample – How many times to upsample the image looking
for faces. Higher numbers find smaller faces.
• batch_size – How many images to include in each GPU processing batch.
Returns A list of tuples of found face locations in css (top, right, bottom, left) order
face_recognition.api.compare_faces(known_face_encodings, face_encoding_to_check, toler-
ance=0.6)
Compare a list of face encodings against a candidate encoding to see if they match.
Parameters
• known_face_encodings – A list of known face encodings
• face_encoding_to_check – A single face encoding to compare against the list
• tolerance – How much distance between faces to consider it a match. Lower is more
strict. 0.6 is typical best performance.
Returns A list of True/False values indicating which known_face_encodings match the face encod-
ing to check

19
Face Recognition Documentation, Release 1.4.0

face_recognition.api.face_distance(face_encodings, face_to_compare)
Given a list of face encodings, compare them to a known face encoding and get a euclidean distance for each
comparison face. The distance tells you how similar the faces are.
Parameters
• face_encodings – List of face encodings to compare
• face_to_compare – A face encoding to compare against
Returns A numpy ndarray with the distance for each face in the same order as the ‘faces’ array
face_recognition.api.face_encodings(face_image, known_face_locations=None,
num_jitters=1, model=’small’)
Given an image, return the 128-dimension face encoding for each face in the image.
Parameters
• face_image – The image that contains one or more faces
• known_face_locations – Optional - the bounding boxes of each face if you already
know them.
• num_jitters – How many times to re-sample the face when calculating encoding.
Higher is more accurate, but slower (i.e. 100 is 100x slower)
• model – Optional - which model to use. “large” or “small” (default) which only returns 5
points but is faster.
Returns A list of 128-dimensional face encodings (one for each face in the image)
face_recognition.api.face_landmarks(face_image, face_locations=None, model=’large’)
Given an image, returns a dict of face feature locations (eyes, nose, etc) for each face in the image
Parameters
• face_image – image to search
• face_locations – Optionally provide a list of face locations to check.
• model – Optional - which model to use. “large” (default) or “small” which only returns 5
points but is faster.
Returns A list of dicts of face feature locations (eyes, nose, etc)
face_recognition.api.face_locations(img, number_of_times_to_upsample=1, model=’hog’)
Returns an array of bounding boxes of human faces in a image
Parameters
• img – An image (as a numpy array)
• number_of_times_to_upsample – How many times to upsample the image looking
for faces. Higher numbers find smaller faces.
• model – Which face detection model to use. “hog” is less accurate but faster on CPUs.
“cnn” is a more accurate deep-learning model which is GPU/CUDA accelerated (if avail-
able). The default is “hog”.
Returns A list of tuples of found face locations in css (top, right, bottom, left) order
face_recognition.api.load_image_file(file, mode=’RGB’)
Loads an image file (.jpg, .png, etc) into a numpy array
Parameters
• file – image file name or file object to load

20 Chapter 4. face_recognition
 Face Recognition Documentation, Release 1.4.0

• mode – format to convert the image to. Only ‘RGB’ (8-bit RGB, 3 channels) and ‘L’ (black
and white) are supported.
Returns image contents as numpy array

4.1. face_recognition package 21

Face Recognition Documentation, Release 1.4.0

22 Chapter 4. face_recognition
 CHAPTER 5

Contributing

Contributions are welcome, and they are greatly appreciated! Every little bit helps, and credit will always be given.
You can contribute in many ways:

5.1 Types of Contributions

5.1.1 Report Bugs

Report bugs at https://github.com/ageitgey/face_recognition/issues.

If you are reporting a bug, please include:
• Your operating system name and version.
• Any details about your local setup that might be helpful in troubleshooting.
• Detailed steps to reproduce the bug.

5.1.2 Submit Feedback

The best way to send feedback is to file an issue at https://github.com/ageitgey/face_recognition/issues.

If you are proposing a feature:
• Explain in detail how it would work.
• Keep the scope as narrow as possible, to make it easier to implement.
• Remember that this is a volunteer-driven project, and that contributions are welcome :)

23
Face Recognition Documentation, Release 1.4.0

5.2 Get Started!

Ready to contribute? Here’s how to set up face_recognition for local development.

1. Fork the face_recognition repo on GitHub.
2. Clone your fork locally:

$ git clone [email protected]:your_name_here/face_recognition.git

3. Install your local copy into a virtualenv. Assuming you have virtualenvwrapper installed, this is how you set up
your fork for local development:

$ mkvirtualenv face_recognition
$ cd face_recognition/
$ python setup.py develop

4. Create a branch for local development:

$ git checkout -b name-of-your-bugfix-or-feature

Now you can make your changes locally.

5. When you’re done making changes, check that your changes pass flake8 and the tests, including testing other
Python versions with tox:

$ flake8 face_recognition tests

$ python setup.py test or py.test
$ tox

To get flake8 and tox, just pip install them into your virtualenv.
6. Commit your changes and push your branch to GitHub:

$ git add .
$ git commit -m "Your detailed description of your changes."
$ git push origin name-of-your-bugfix-or-feature

7. Submit a pull request through the GitHub website.

5.3 Pull Request Guidelines

Before you submit a pull request, check that it meets these guidelines:
1. The pull request should include tests.
2. If the pull request adds functionality, the docs should be updated. Put your new functionality into a function
with a docstring, and add the feature to the list in README.rst.
3. The pull request should work for Python 2.7, 3.5, 3.6, 3.7 and 3.8, and for PyPy. Check https://travis-ci.org/
ageitgey/face_recognition/pull_requests and make sure that the tests pass for all supported Python versions.

5.4 Tips

To run a subset of tests:

24 Chapter 5. Contributing
 Face Recognition Documentation, Release 1.4.0

$ python -m unittest tests.test_face_recognition

5.4. Tips 25
Face Recognition Documentation, Release 1.4.0

26 Chapter 5. Contributing
 CHAPTER 6

Authors

• Adam Geitgey <[email protected]>

6.1 Thanks

• Many, many thanks to Davis King (@nulhom) for creating dlib and for providing the trained facial feature
detection and face encoding models used in this library.
• Thanks to everyone who works on all the awesome Python data science libraries like numpy, scipy, scikit-image,
pillow, etc, etc that makes this kind of stuff so easy and fun in Python.
• Thanks to Cookiecutter and the audreyr/cookiecutter-pypackage project template for making Python project
packaging way more tolerable.

27
Face Recognition Documentation, Release 1.4.0

28 Chapter 6. Authors
 CHAPTER 7

History

7.1 1.4.0 (2020-09-26)

• Dropping support for Python 2.x

• –upsample a parameter for command line face_recognition

7.2 1.3.0 (2020-02-20)

• Drop support for Python 3.4 and add 3.8

• Blink detection example

7.3 1.2.3 (2018-08-21)

• You can now pass model=”small” to face_landmarks() to use the 5-point face model instead of the 68-point
model.
• Now officially supporting Python 3.7
• New example of using this library in a Jupyter Notebook

7.4 1.2.2 (2018-04-02)

• Added the face_detection CLI command

• Removed dependencies on scipy to make installation easier
• Cleaned up KNN example and fixed a bug with drawing fonts to label detected faces in the demo

29
Face Recognition Documentation, Release 1.4.0

7.5 1.2.1 (2018-02-01)

• Fixed version numbering inside of module code.

7.6 1.2.0 (2018-02-01)

• Fixed a bug where batch size parameter didn’t work correctly when doing batch face detections on GPU.
• Updated OpenCV examples to do proper BGR -> RGB conversion
• Updated webcam examples to avoid common mistakes and reduce support questions
• Added a KNN classification example
• Added an example of automatically blurring faces in images or videos
• Updated Dockerfile example to use dlib v19.9 which removes the boost dependency.

7.7 1.1.0 (2017-09-23)

• Will use dlib’s 5-point face pose estimator when possible for speed (instead of 68-point face pose esimator)
• dlib v19.7 is now the minimum required version
• face_recognition_models v0.3.0 is now the minimum required version

7.8 1.0.0 (2017-08-29)

• Added support for dlib’s CNN face detection model via model=”cnn” parameter on face detecion call
• Added support for GPU batched face detections using dlib’s CNN face detector model
• Added find_faces_in_picture_cnn.py to examples
• Added find_faces_in_batches.py to examples
• Added face_rec_from_video_file.py to examples
• dlib v19.5 is now the minimum required version
• face_recognition_models v0.2.0 is now the minimum required version

7.9 0.2.2 (2017-07-07)

• Added –show-distance to cli

• Fixed a bug where –tolerance was ignored in cli if testing a single image
• Added benchmark.py to examples

7.10 0.2.1 (2017-07-03)

• Added –tolerance to cli

30 Chapter 7. History
 Face Recognition Documentation, Release 1.4.0

7.11 0.2.0 (2017-06-03)

• The CLI can now take advantage of multiple CPUs. Just pass in the -cpus X parameter where X is the number
of CPUs to use.
• Added face_distance.py example
• Improved CLI tests to actually test the CLI functionality
• Updated facerec_on_raspberry_pi.py to capture in rgb (not bgr) format.

7.12 0.1.14 (2017-04-22)

• Fixed a ValueError crash when using the CLI on Python 2.7

7.13 0.1.13 (2017-04-20)

• Raspberry Pi support.

7.14 0.1.12 (2017-04-13)

• Fixed: Face landmarks wasn’t returning all chin points.

7.15 0.1.11 (2017-03-30)

• Fixed a minor bug in the command-line interface.

7.16 0.1.10 (2017-03-21)

• Minor pref improvements with face comparisons.

• Test updates.

7.17 0.1.9 (2017-03-16)

• Fix minimum scipy version required.

7.18 0.1.8 (2017-03-16)

• Fix missing Pillow dependency.

7.11. 0.2.0 (2017-06-03) 31

Face Recognition Documentation, Release 1.4.0

7.19 0.1.7 (2017-03-13)

• First working release.

32 Chapter 7. History
 CHAPTER 8

Indices and tables

• genindex
• modindex
• search

33
Face Recognition Documentation, Release 1.4.0

34 Chapter 8. Indices and tables

 Python Module Index

f
face_recognition.api, 19

35
Face Recognition Documentation, Release 1.4.0

36 Python Module Index

 Index

B
batch_face_locations() (in module
face_recognition.api), 19

C
compare_faces() (in module face_recognition.api),
19

F
face_distance() (in module face_recognition.api),
19
face_encodings() (in module
face_recognition.api), 20
face_landmarks() (in module
face_recognition.api), 20
face_locations() (in module
face_recognition.api), 20
face_recognition.api (module), 19

L
load_image_file() (in module
face_recognition.api), 20

37