Updated RST docs

ageitgey · ageitgey · commit 4502c77ae6a3 · 2017-03-06T12:50:49.000-08:00
diff --git a/README.rst b/README.rst
@@ -1,74 +1,131 @@
 Face Recognition
 ================
 
-The world’s simplest face recognition and face manipulation library.
+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 deep learning face recognition.
+Built using `dlib <http://dlib.net/>`__'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 <http://vis-www.cs.umass.edu/lfw/>`__ benchmark.
 
-| |image0|
-| |image1|
+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!
 
-Recognize and manipulate faces from Python or from the command line
-
-Free software, MIT license.
+|image0| |image1|
 
 Features
 --------
 
 Find faces in pictures
 ^^^^^^^^^^^^^^^^^^^^^^
 
-Find all the faces that appear in a picture.
+Find all the faces that appear in a picture:
+
+.. figure:: https://cloud.githubusercontent.com/assets/896692/23625227/42c65360-025d-11e7-94ea-b12f28cb34b4.png
+   :alt: 
 
-|image2|
+.. code:: python
+
+    import face_recognition
+    image = face_recognition.load_image_file("your_file.jpg")
+    face_locations = face_recognition.face_locations(image)
 
 Find and manipulate facial features in pictures
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-Get the locations and outlines of each person’s eyes, nose, mouth and
+Get the locations and outlines of each person's eyes, nose, mouth and
 chin.
 
-|image3|
+.. figure:: https://cloud.githubusercontent.com/assets/896692/23625282/7f2d79dc-025d-11e7-8728-d8924596f8fa.png
+   :alt: 
+
+.. code:: python
 
-| 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’):
+    import face_recognition
+    image = face_recognition.load_image_file("your_file.jpg")
+    face_landmarks_list = face_recognition.face_landmarks(image)
 
-|f3|
+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 <https://github.com/ageitgey/face_recognition/blob/master/examples/digital_makeup.py>`__
+(think 'Meitu'):
+
+.. figure:: https://cloud.githubusercontent.com/assets/896692/23625283/80638760-025d-11e7-80a2-1d2779f7ccab.png
+   :alt: 
 
 Identify faces in pictures
 ^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 Recognize who appears in each photo.
 
-|f4|
+.. figure:: https://cloud.githubusercontent.com/assets/896692/23625229/45e049b6-025d-11e7-89cc-8a71cf89e713.png
+   :alt: 
+
+.. code:: python
+
+    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)
+
+    results = face_recognition.compare_faces([biden_encoding], unknown_encoding)
+
+Installation
+------------
+
+Python 3 is fully supported. Python 2 should also work. Only macOS and
+Linux are tested. I have no idea if this will work on Windows.
+
+You can install this module from pypi using ``pip3`` (or ``pip2`` for
+Python 2):
+
+.. code:: bash
+
+    $ pip3 install face_recognition
+
+It's very likely that you will run into problems when pip tries to
+compile the ``dlib`` dependency. If that happens, check out this guide
+to installing dlib from source instead to fix the error:
+
+`How to install dlib from
+source <https://gist.github.com/ageitgey/629d75c1baac34dfa5ca2a1928a7aeaf>`__
+
+After manually installing ``dlib``, try running
+``pip3 install face_recognition`` again.
 
 Usage
 -----
 
 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.
+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
+already know. There should be one image file for each person with the
+files named according to who is in the picture:
 
-| First, you need to provide a folder with one picture of each person
-  you
-| already know. There should be one image file for each person with the
-| files named according to who is in the picture:
+.. figure:: https://cloud.githubusercontent.com/assets/896692/23582466/8324810e-00df-11e7-82cf-41515eba704d.png
+   :alt: known
 
-|known|
+   known
 
 Next, you need a second folder with the files you want to identify:
 
-|unknown|
+.. figure:: https://cloud.githubusercontent.com/assets/896692/23582465/81f422f8-00df-11e7-8b0d-75364f641f58.png
+   :alt: unknown
 
-| Then in you simply run the commnad ``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:
+   unknown
+
+Then in you simply run the commnad ``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:
 
 .. code:: bash
 
@@ -77,17 +134,14 @@ Next, you need a second folder with the files you want to identify:
     /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.
+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.
+An ``unknown_person`` is a face in the image that didn't match anyone in
+your folder of known people.
 
-| 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:
+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:
 
 .. code:: bash
 
@@ -96,19 +150,115 @@ Next, you need a second folder with the files you want to identify:
     Barack Obama
     unknown_person
 
-Python API
-^^^^^^^^^^
+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
+''''''''''''''''''''''''''''''''''''''''''''
+
+.. code:: python
+
+    import face_recognition
 
-API Docs: [https://face-recognition.readthedocs.io](\ https://fac
+    image = face_recognition.load_image_file("my_picture.jpg")
+    face_locations = face_recognition.face_locations(image)
 
-.. _dlib: http://dlib.net/
-.. _digital make-up: https://github.com/ageitgey/face_recognition/blob/master/examples/digital_makeup.py
+    # face_locations is now an array listing the co-ordinates of each face!
+
+See `this
+example <https://github.com/ageitgey/face_recognition/blob/master/examples/find_faces_in_picture.py>`__
+to try it out.
+
+Automatically locate the facial features of a person in an image
+''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
+
+.. code:: python
+
+    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 <https://github.com/ageitgey/face_recognition/blob/master/examples/find_facial_features_in_picture.py>`__
+to try it out.
+
+Recognize faces in images and identify who they are
+'''''''''''''''''''''''''''''''''''''''''''''''''''
+
+.. code:: python
+
+    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!")
+
+See `this
+example <https://github.com/ageitgey/face_recognition/blob/master/examples/recognize_faces_in_pictures.py>`__
+to try it out.
+
+Python Code Examples
+--------------------
+
+All the examples are available
+`here <https://github.com/ageitgey/face_recognition/tree/master/examples>`__.
+
+-  `Find faces in an
+   photograph <https://github.com/ageitgey/face_recognition/blob/master/examples/find_faces_in_picture.py>`__
+-  `Identify specific facial features in a
+   photograph <https://github.com/ageitgey/face_recognition/blob/master/examples/find_facial_features_in_picture.py>`__
+-  `Apply (horribly ugly) digital
+   make-up <https://github.com/ageitgey/face_recognition/blob/master/examples/digital_makeup.py>`__
+-  `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>`__
+
+Caveats
+-------
+
+-  The face recognition model is trained on adults does not work very
+   well on children. It tends to mix up children quite easy using the
+   default comparison threshold of 0.6.
+
+Thanks
+------
+
+-  Many, many thanks to `Davis King <https://github.com/davisking>`__
+   ([@nulhom](https://twitter.com/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 the
+   powers the face encodings, check out his `blog
+   post <http://blog.dlib.net/2017/02/high-quality-face-recognition-with-deep.html>`__.
+-  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.
+-  `Cookiecutter <https://github.com/audreyr/cookiecutter>`__ and the
+   `audreyr/cookiecutter-pypackage <https://github.com/audreyr/cookiecutter-pypackage>`__
+   project template for making Python project packaging way more
+   tolerable.
 
 .. |image0| image:: https://img.shields.io/pypi/v/face_recognition.svg
 .. |image1| image:: https://travis-ci.org/ageitgey/face_recognition
-.. |image2| image:: https://cloud.githubusercontent.com/assets/896692/23582662/3891b65c-00e4-11e7-848e-0007bca850df.png
-.. |image3| image:: https://cloud.githubusercontent.com/assets/896692/23582665/3bbf323c-00e4-11e7-83f9-d42ede9ead2d.png
-.. |f3| image:: https://cloud.githubusercontent.com/assets/896692/23582667/3cf969c4-00e4-11e7-82e6-add45ae3992f.png
-.. |f4| image:: https://cloud.githubusercontent.com/assets/896692/23582670/405a5268-00e4-11e7-879f-b4de9f727096.png
-.. |known| image:: https://cloud.githubusercontent.com/assets/896692/23582466/8324810e-00df-11e7-82cf-41515eba704d.png
-.. |unknown| image:: https://cloud.githubusercontent.com/assets/896692/23582465/81f422f8-00df-11e7-8b0d-75364f641f58.png
+
