Add face_distance.py example

README.md

@@ -227,6 +227,7 @@ All the examples are available [here](https://github.com/ageitgey/face_recogniti
 * [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)
 * [Recognize faces on a Raspberry Pi w/ camera](https://github.com/ageitgey/face_recognition/blob/master/examples/facerec_on_raspberry_pi.py)
 * [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)
+* [Compare faces by numeric face distance instead of only True/False matches](https://github.com/ageitgey/face_recognition/blob/master/examples/face_distance.py)
 
 ## How Face Recognition Works
 

examples/face_distance.py

@@ -0,0 +1,37 @@
+import face_recognition
+
+# Often instead of just checking if two faces match or not (True or False), it's helpful to see how similar they are.
+# You can do that by using the face_distance function.
+
+# The model was trained in a way that faces with a distance of 0.6 or less should be a match. But if you want to
+# be more strict, you can look for a smaller face distance. For example, using a 0.55 cutoff would reduce false
+# positive matches at the risk of more false negatives.
+
+# Note: This isn't exactly the same as a "percent match". The scale isn't linear. But you can assume that images with a
+# smaller distance are more similar to each other than ones with a larger distance.
+
+# Load some images to compare against
+known_obama_image = face_recognition.load_image_file("obama.jpg")
+known_biden_image = face_recognition.load_image_file("biden.jpg")
+
+# Get the face encodings for the known images
+obama_face_encoding = face_recognition.face_encodings(known_obama_image)[0]
+biden_face_encoding = face_recognition.face_encodings(known_biden_image)[0]
+
+known_encodings = [
+    obama_face_encoding,
+    biden_face_encoding
+]
+
+# Load a test image and get encondings for it
+image_to_test = face_recognition.load_image_file("obama2.jpg")
+image_to_test_encoding = face_recognition.face_encodings(image_to_test)[0]
+
+# See how far apart the test image is from the known faces
+face_distances = face_recognition.face_distance(known_encodings, image_to_test_encoding)
+
+for i, face_distance in enumerate(face_distances):
+    print("The test image has a distance of {:.2} from known image #{}".format(face_distance, i))
+    print("- With a normal cutoff of 0.6, would the test image match the known image? {}".format(face_distance < 0.6))
+    print("- With a very strict cutoff of 0.5, would the test image match the known image? {}".format(face_distance < 0.5))
+    print()