Skip to content

Commit f37e636

Browse files
ageitgeyageitgey
authored
Add support for dlib's new cnn-based face detector (ageitgey#157)
Add support for dlib's new cnn-based face detector
1 parent e9df345 commit f37e636

16 files changed

+416
-11
lines changed

‎Dockerfile

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -29,7 +29,7 @@ RUN apt-get install -y --fix-missing \
2929

3030
RUN cd ~ && \
3131
mkdir -p dlib && \
32-
git clone -b 'v19.4' --single-branch https://github.com/davisking/dlib.git dlib/ && \
32+
git clone -b 'v19.5' --single-branch https://github.com/davisking/dlib.git dlib/ && \
3333
cd dlib/ && \
3434
python3 setup.py install --yes USE_AVX_INSTRUCTIONS
3535

‎HISTORY.rst

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,18 @@
11
History
22
=======
33

4+
1.0.0 (2017-08-29)
5+
------------------
6+
7+
* Added support for dlib's CNN face detection model via model="cnn" parameter on face detecion call
8+
* Added support for GPU batched face detections using dlib's CNN face detector model
9+
* Added find_faces_in_picture_cnn.py to examples
10+
* Added find_faces_in_batches.py to examples
11+
* Added face_rec_from_video_file.py to examples
12+
* dlib v19.5 is now the minimum required version
13+
* face_recognition_models v0.2.0 is now the minimum required version
14+
15+
416
0.2.2 (2017-07-07)
517
------------------
618

‎README.md

Lines changed: 34 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -204,6 +204,27 @@ face_locations = face_recognition.face_locations(image)
204204
See [this example](https://github.com/ageitgey/face_recognition/blob/master/examples/find_faces_in_picture.py)
205205
to try it out.
206206

207+
You can also opt-in to a somewhat more accurate deep-learning-based face detection model.
208+
209+
Note: GPU acceleration (via nvidia's CUDA library) is required for good
210+
performance with this model. You'll also want to enable CUDA support
211+
when compliling `dlib`.
212+
213+
```python
214+
import face_recognition
215+
216+
image = face_recognition.load_image_file("my_picture.jpg")
217+
face_locations = face_recognition.face_locations(image, model="cnn")
218+
219+
# face_locations is now an array listing the co-ordinates of each face!
220+
```
221+
222+
See [this example](https://github.com/ageitgey/face_recognition/blob/master/examples/find_faces_in_picture_cnn.py)
223+
to try it out.
224+
225+
If you have a lot of images and a GPU, you can also
226+
[find faces in batches](https://github.com/ageitgey/face_recognition/blob/master/examples/find_faces_in_batches.py).
227+
207228
##### Automatically locate the facial features of a person in an image
208229

209230
```python
@@ -249,15 +270,27 @@ See [this example](https://github.com/ageitgey/face_recognition/blob/master/exam
249270

250271
All the examples are available [here](https://github.com/ageitgey/face_recognition/tree/master/examples).
251272

273+
274+
#### Face Detection
275+
252276
* [Find faces in a photograph](https://github.com/ageitgey/face_recognition/blob/master/examples/find_faces_in_picture.py)
277+
* [Find faces in a photograph (using deep learning)](https://github.com/ageitgey/face_recognition/blob/master/examples/find_faces_in_picture_cnn.py)
278+
* [Find faces in batches of images w/ GPU (using deep learning)](https://github.com/ageitgey/face_recognition/blob/master/examples/find_faces_in_batches.py)
279+
280+
#### Facial Features
281+
253282
* [Identify specific facial features in a photograph](https://github.com/ageitgey/face_recognition/blob/master/examples/find_facial_features_in_picture.py)
254283
* [Apply (horribly ugly) digital make-up](https://github.com/ageitgey/face_recognition/blob/master/examples/digital_makeup.py)
284+
285+
#### Facial Recognition
286+
255287
* [Find and recognize unknown faces in a photograph based on photographs of known people](https://github.com/ageitgey/face_recognition/blob/master/examples/recognize_faces_in_pictures.py)
288+
* [Compare faces by numeric face distance instead of only True/False matches](https://github.com/ageitgey/face_recognition/blob/master/examples/face_distance.py)
256289
* [Recognize faces in live video using your webcam - Simple / Slower Version (Requires OpenCV to be installed)](https://github.com/ageitgey/face_recognition/blob/master/examples/facerec_from_webcam.py)
257290
* [Recognize faces in live video using your webcam - Faster Version (Requires OpenCV to be installed)](https://github.com/ageitgey/face_recognition/blob/master/examples/facerec_from_webcam_faster.py)
291+
* [Recognize faces in a video file and write out new video file (Requires OpenCV to be installed)](https://github.com/ageitgey/face_recognition/blob/master/examples/facerec_from_video_file.py)
258292
* [Recognize faces on a Raspberry Pi w/ camera](https://github.com/ageitgey/face_recognition/blob/master/examples/facerec_on_raspberry_pi.py)
259293
* [Run a web service to recognize faces via HTTP (Requires Flask to be installed)](https://github.com/ageitgey/face_recognition/blob/master/examples/web_service_example.py)
260-
* [Compare faces by numeric face distance instead of only True/False matches](https://github.com/ageitgey/face_recognition/blob/master/examples/face_distance.py)
261294

262295
## How Face Recognition Works
263296

‎README.rst

Lines changed: 109 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -163,6 +163,40 @@ Next, you need a second folder with the files you want to identify:
163163
in
164164
| your folder of known people.
165165
166+
Adjusting Tolerance / Sensitivity
167+
'''''''''''''''''''''''''''''''''
168+
169+
| If you are getting multiple matches for the same person, it might be
170+
that
171+
| the people in your photos look very similar and a lower tolerance
172+
value
173+
| is needed to make face comparisons more strict.
174+
175+
| You can do that with the ``--tolerance`` parameter. The default
176+
tolerance
177+
| value is 0.6 and lower numbers make face comparisons more strict:
178+
179+
.. code:: bash
180+
181+
$ face_recognition --tolerance 0.54 ./pictures_of_people_i_know/ ./unknown_pictures/
182+
183+
/unknown_pictures/unknown.jpg,Barack Obama
184+
/face_recognition_test/unknown_pictures/unknown.jpg,unknown_person
185+
186+
| If you want to see the face distance calculated for each match in
187+
order
188+
| to adjust the tolerance setting, you can use ``--show-distance true``:
189+
190+
.. code:: bash
191+
192+
$ face_recognition --show-distance true ./pictures_of_people_i_know/ ./unknown_pictures/
193+
194+
/unknown_pictures/unknown.jpg,Barack Obama,0.378542298956785
195+
/face_recognition_test/unknown_pictures/unknown.jpg,unknown_person,None
196+
197+
More Examples
198+
'''''''''''''
199+
166200
| If you simply want to know the names of the people in each photograph
167201
but don't
168202
| care about file names, you could do this:
@@ -174,6 +208,25 @@ Next, you need a second folder with the files you want to identify:
174208
Barack Obama
175209
unknown_person
176210
211+
Speeding up Face Recognition
212+
''''''''''''''''''''''''''''
213+
214+
| Face recognition can be done in parallel if you have a computer with
215+
| multiple CPU cores. For example if your system has 4 CPU cores, you
216+
can
217+
| process about 4 times as many images in the same amount of time by
218+
using
219+
| all your CPU cores in parallel.
220+
221+
If you are using Python 3.4 or newer, pass in a
222+
``--cpus <number_of_cpu_cores_to_use>`` parameter:
223+
224+
.. code:: bash
225+
226+
$ face_recognition -cpus 4 ./pictures_of_people_i_know/ ./unknown_pictures/
227+
228+
You can also pass in ``--cpus -1`` to use all CPU cores in your system.
229+
177230
Python Module
178231
^^^^^^^^^^^^^
179232

@@ -200,6 +253,31 @@ Automatically find all the faces in an image
200253
example <https://github.com/ageitgey/face_recognition/blob/master/examples/find_faces_in_picture.py>`__
201254
| to try it out.
202255
256+
You can also opt-in to a somewhat more accurate deep-learning-based face
257+
detection model.
258+
259+
| Note: GPU acceleration (via nvidia's CUDA library) is required for
260+
good
261+
| performance with this model. You'll also want to enable CUDA support
262+
| when compliling ``dlib``.
263+
264+
.. code:: python
265+
266+
import face_recognition
267+
268+
image = face_recognition.load_image_file("my_picture.jpg")
269+
face_locations = face_recognition.face_locations(image, model="cnn")
270+
271+
# face_locations is now an array listing the co-ordinates of each face!
272+
273+
| See `this
274+
example <https://github.com/ageitgey/face_recognition/blob/master/examples/find_faces_in_picture_cnn.py>`__
275+
| to try it out.
276+
277+
| If you have a lot of images and a GPU, you can also
278+
| `find faces in
279+
batches <https://github.com/ageitgey/face_recognition/blob/master/examples/find_faces_in_batches.py>`__.
280+
203281
Automatically locate the facial features of a person in an image
204282
''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
205283

@@ -251,21 +329,41 @@ Python Code Examples
251329
All the examples are available
252330
`here <https://github.com/ageitgey/face_recognition/tree/master/examples>`__.
253331

332+
Face Detection
333+
^^^^^^^^^^^^^^
334+
254335
- `Find faces in a
255336
photograph <https://github.com/ageitgey/face_recognition/blob/master/examples/find_faces_in_picture.py>`__
337+
- `Find faces in a photograph (using deep
338+
learning) <https://github.com/ageitgey/face_recognition/blob/master/examples/find_faces_in_picture_cnn.py>`__
339+
- `Find faces in batches of images w/ GPU (using deep
340+
learning) <https://github.com/ageitgey/face_recognition/blob/master/examples/find_faces_in_batches.py>`__
341+
342+
Facial Features
343+
^^^^^^^^^^^^^^^
344+
256345
- `Identify specific facial features in a
257346
photograph <https://github.com/ageitgey/face_recognition/blob/master/examples/find_facial_features_in_picture.py>`__
258347
- `Apply (horribly ugly) digital
259348
make-up <https://github.com/ageitgey/face_recognition/blob/master/examples/digital_makeup.py>`__
349+
350+
Facial Recognition
351+
^^^^^^^^^^^^^^^^^^
352+
260353
- `Find and recognize unknown faces in a photograph based on
261354
photographs of known
262355
people <https://github.com/ageitgey/face_recognition/blob/master/examples/recognize_faces_in_pictures.py>`__
356+
- `Compare faces by numeric face distance instead of only True/False
357+
matches <https://github.com/ageitgey/face_recognition/blob/master/examples/face_distance.py>`__
263358
- `Recognize faces in live video using your webcam - Simple / Slower
264359
Version (Requires OpenCV to be
265360
installed) <https://github.com/ageitgey/face_recognition/blob/master/examples/facerec_from_webcam.py>`__
266361
- `Recognize faces in live video using your webcam - Faster Version
267362
(Requires OpenCV to be
268363
installed) <https://github.com/ageitgey/face_recognition/blob/master/examples/facerec_from_webcam_faster.py>`__
364+
- `Recognize faces in a video file and write out new video file
365+
(Requires OpenCV to be
366+
installed) <https://github.com/ageitgey/face_recognition/blob/master/examples/facerec_from_video_file.py>`__
269367
- `Recognize faces on a Raspberry Pi w/
270368
camera <https://github.com/ageitgey/face_recognition/blob/master/examples/facerec_on_raspberry_pi.py>`__
271369
- `Run a web service to recognize faces via HTTP (Requires Flask to be
@@ -325,6 +423,17 @@ Issue: ``MemoryError`` when running ``pip2 install face_recognition``
325423
| try ``pip2 --no-cache-dir install face_recognition`` to avoid the
326424
issue.
327425
426+
Issue:
427+
``AttributeError: 'module' object has no attribute 'face_recognition_model_v1'``
428+
429+
Solution: The version of ``dlib`` you have installed is too old. You
430+
need version 19.4 or newer. Upgrade ``dlib``.
431+
432+
Issue: ``TypeError: imread() got an unexpected keyword argument 'mode'``
433+
434+
Solution: The version of ``scipy`` you have installed is too old. You
435+
need version 0.17 or newer. Upgrade ``scipy``.
436+
328437
Thanks
329438
------
330439

‎examples/alex-lacamoire.png

178 KB
Loading

‎examples/facerec_from_video_file.py

Lines changed: 83 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,83 @@
1+
import face_recognition
2+
import cv2
3+
4+
# This is a demo of running face recognition on a video file and saving the results to a new video file.
5+
#
6+
# PLEASE NOTE: This example requires OpenCV (the `cv2` library) to be installed only to read from your webcam.
7+
# OpenCV is *not* required to use the face_recognition library. It's only required if you want to run this
8+
# specific demo. If you have trouble installing it, try any of the other demos that don't require it instead.
9+
10+
# Open the input movie file
11+
input_movie = cv2.VideoCapture("hamilton_clip.mp4")
12+
length = int(input_movie.get(cv2.CAP_PROP_FRAME_COUNT))
13+
14+
# Create an output movie file (make sure resolution/frame rate matches input video!)
15+
fourcc = cv2.VideoWriter_fourcc(*'XVID')
16+
output_movie = cv2.VideoWriter('output.avi', fourcc, 29.97, (640, 360))
17+
18+
# Load some sample pictures and learn how to recognize them.
19+
lmm_image = face_recognition.load_image_file("lin-manuel-miranda.png")
20+
lmm_face_encoding = face_recognition.face_encodings(lmm_image)[0]
21+
22+
al_image = face_recognition.load_image_file("alex-lacamoire.png")
23+
al_face_encoding = face_recognition.face_encodings(al_image)[0]
24+
25+
known_faces = [
26+
lmm_face_encoding,
27+
al_face_encoding
28+
]
29+
30+
# Initialize some variables
31+
face_locations = []
32+
face_encodings = []
33+
face_names = []
34+
frame_number = 0
35+
36+
while True:
37+
# Grab a single frame of video
38+
ret, frame = input_movie.read()
39+
frame_number += 1
40+
41+
# Quit when the input video file ends
42+
if not ret:
43+
break
44+
45+
# Find all the faces and face encodings in the current frame of video
46+
face_locations = face_recognition.face_locations(frame)
47+
face_encodings = face_recognition.face_encodings(frame, face_locations)
48+
49+
face_names = []
50+
for face_encoding in face_encodings:
51+
# See if the face is a match for the known face(s)
52+
match = face_recognition.compare_faces(known_faces, face_encoding, tolerance=0.50)
53+
54+
# If you had more than 2 faces, you could make this logic a lot prettier
55+
# but I kept it simple for the demo
56+
name = None
57+
if match[0]:
58+
name = "Lin-Manuel Miranda"
59+
elif match[1]:
60+
name = "Alex Lacamoire"
61+
62+
face_names.append(name)
63+
64+
# Label the results
65+
for (top, right, bottom, left), name in zip(face_locations, face_names):
66+
if not name:
67+
continue
68+
69+
# Draw a box around the face
70+
cv2.rectangle(frame, (left, top), (right, bottom), (0, 0, 255), 2)
71+
72+
# Draw a label with a name below the face
73+
cv2.rectangle(frame, (left, bottom - 25), (right, bottom), (0, 0, 255), cv2.FILLED)
74+
font = cv2.FONT_HERSHEY_DUPLEX
75+
cv2.putText(frame, name, (left + 6, bottom - 6), font, 0.5, (255, 255, 255), 1)
76+
77+
# Write the resulting image to the output video file
78+
print("Writing frame {} / {}".format(frame_number, length))
79+
output_movie.write(frame)
80+
81+
# All done!
82+
input_movie.release()
83+
cv2.destroyAllWindows()

‎examples/find_faces_in_batches.py

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,52 @@
1+
import face_recognition
2+
import cv2
3+
4+
# This code finds all faces in a list of images using the CNN model.
5+
#
6+
# This demo is for the _special case_ when you need to find faces in LOTS of images very quickly and all the images
7+
# are the exact same size. This is common in video processing applications where you have lots of video frames
8+
# to process.
9+
#
10+
# If you are processing a lot of images and using a GPU with CUDA, batch processing can be ~3x faster then processing
11+
# single images at a time. But if you aren't using a GPU, then batch processing isn't going to be very helpful.
12+
#
13+
# PLEASE NOTE: This example requires OpenCV (the `cv2` library) to be installed only to read the video file.
14+
# OpenCV is *not* required to use the face_recognition library. It's only required if you want to run this
15+
# specific demo. If you have trouble installing it, try any of the other demos that don't require it instead.
16+
17+
# Open video file
18+
video_capture = cv2.VideoCapture("short_hamilton_clip.mp4")
19+
20+
frames = []
21+
frame_count = 0
22+
23+
while video_capture.isOpened():
24+
# Grab a single frame of video
25+
ret, frame = video_capture.read()
26+
27+
# Bail out when the video file ends
28+
if not ret:
29+
break
30+
31+
# Save each frame of the video to a list
32+
frame_count += 1
33+
frames.append(frame)
34+
35+
# Every 128 frames (the default batch size), batch process the list of frames to find faces
36+
if len(frames) == 128:
37+
batch_of_face_locations = face_recognition.batch_face_locations(frames, number_of_times_to_upsample=0)
38+
39+
# Now let's list all the faces we found in all 128 frames
40+
for frame_number_in_batch, face_locations in enumerate(batch_of_face_locations):
41+
number_of_faces_in_frame = len(face_locations)
42+
43+
frame_number = frame_count - 128 + frame_number_in_batch
44+
print("I found {} face(s) in frame #{}.".format(number_of_faces_in_frame, frame_number))
45+
46+
for face_location in face_locations:
47+
# Print the location of each face in this frame
48+
top, right, bottom, left = face_location
49+
print(" - A face is located at pixel location Top: {}, Left: {}, Bottom: {}, Right: {}".format(top, left, bottom, right))
50+
51+
# Clear the frames array to start the next batch
52+
frames = []

‎examples/find_faces_in_picture.py

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,9 @@
44
# Load the jpg file into a numpy array
55
image = face_recognition.load_image_file("biden.jpg")
66

7-
# Find all the faces in the image
7+
# Find all the faces in the image using the default HOG-based model.
8+
# This method is fairly accurate, but not as accurate as the CNN model and not GPU accelerated.
9+
# See also: find_faces_in_picture_cnn.py
810
face_locations = face_recognition.face_locations(image)
911

1012
print("I found {} face(s) in this photograph.".format(len(face_locations)))

0 commit comments

Comments
 (0)