Add code for face-recognition tutorial (#353)

* Move code from tutorial-drafts

Relates to PR #691 on /tutorial-drafts
Moving the code here to avoid linter issues in the text repo.

* Update project code

* Remove eval_img

* Add final code

* Add individual steps

* Blacken, isort, flake8

* Rename Ben

* Separates out display and recognize face functions

* Adds test image with two faces for steps 6-final

* Replaces deprecated textsize() call

* Updates recognize_faces to display unknown faces

* Automatically creates paths and uses rglob for validation

* Formatting + includes rest of files

* Removes output

* Re-adds recognize_face changes

* Re-adds validation changes

* Moves color tuples into constants

* Adds docstrings to each function

* Makes fixes to linter issues

* Fix linter issues

* Apply technical edits

- Reduce complexity of color tuples
- Replace example test image

* README LE

* README title

* Update URL

* Final QA tweaks

* Remove step 7 as we already have final

---------

Co-authored-by: Kyle Stratis <[email protected]>
Co-authored-by: kylestratis <[email protected]>
Co-authored-by: KateFinegan <[email protected]>
Co-authored-by: Geir Arne Hjelle <[email protected]>

Author: 4 people

face-recognition/README.md

@@ -0,0 +1,157 @@
+import argparse
+import pickle
+from collections import Counter
+from pathlib import Path
+
+import face_recognition
+from PIL import Image, ImageDraw
+
+DEFAULT_ENCODINGS_PATH = Path("output/encodings.pkl")
+BOUNDING_BOX_COLOR = "blue"
+TEXT_COLOR = "white"
+
+# Create directories if they don't already exist
+Path("training").mkdir(exist_ok=True)
+Path("output").mkdir(exist_ok=True)
+Path("validation").mkdir(exist_ok=True)
+
+parser = argparse.ArgumentParser(description="Recognize faces in an image")
+parser.add_argument("--train", action="store_true", help="Train on input data")
+parser.add_argument(
+    "--validate", action="store_true", help="Validate trained model"
+)
+parser.add_argument(
+    "--test", action="store_true", help="Test the model with an unknown image"
+)
+parser.add_argument(
+    "-m",
+    action="store",
+    default="hog",
+    choices=["hog", "cnn"],
+    help="Which model to use for training: hog (CPU), cnn (GPU)",
+)
+parser.add_argument(
+    "-f", action="store", help="Path to an image with an unknown face"
+)
+args = parser.parse_args()
+
+
+def encode_known_faces(
+    model: str = "hog", encodings_location: Path = DEFAULT_ENCODINGS_PATH
+) -> None:
+    """
+    Loads images in the training directory and builds a dictionary of their
+    names and encodings.
+    """
+    names = []
+    encodings = []
+
+    for filepath in Path("training").glob("*/*"):
+        name = filepath.parent.name
+        image = face_recognition.load_image_file(filepath)
+
+        face_locations = face_recognition.face_locations(image, model=model)
+        face_encodings = face_recognition.face_encodings(image, face_locations)
+
+        for encoding in face_encodings:
+            names.append(name)
+            encodings.append(encoding)
+
+    name_encodings = {"names": names, "encodings": encodings}
+    with encodings_location.open(mode="wb") as f:
+        pickle.dump(name_encodings, f)
+
+
+def recognize_faces(
+    image_location: str,
+    model: str = "hog",
+    encodings_location: Path = DEFAULT_ENCODINGS_PATH,
+) -> None:
+    """
+    Given an unknown image, get the locations and encodings of any faces and
+    compares them against the known encodings to find potential matches.
+    """
+    with encodings_location.open(mode="rb") as f:
+        loaded_encodings = pickle.load(f)
+
+    input_image = face_recognition.load_image_file(image_location)
+
+    input_face_locations = face_recognition.face_locations(
+        input_image, model=model
+    )
+    input_face_encodings = face_recognition.face_encodings(
+        input_image, input_face_locations
+    )
+
+    pillow_image = Image.fromarray(input_image)
+    draw = ImageDraw.Draw(pillow_image)
+
+    for bounding_box, unknown_encoding in zip(
+        input_face_locations, input_face_encodings
+    ):
+        name = _recognize_face(unknown_encoding, loaded_encodings)
+        if not name:
+            name = "Unknown"
+        _display_face(draw, bounding_box, name)
+
+    del draw
+    pillow_image.show()
+
+
+def _recognize_face(unknown_encoding, loaded_encodings):
+    """
+    Given an unknown encoding and all known encodings, find the known
+    encoding with the most matches.
+    """
+    boolean_matches = face_recognition.compare_faces(
+        loaded_encodings["encodings"], unknown_encoding
+    )
+    votes = Counter(
+        name
+        for match, name in zip(boolean_matches, loaded_encodings["names"])
+        if match
+    )
+    if votes:
+        return votes.most_common(1)[0][0]
+
+
+def _display_face(draw, bounding_box, name):
+    """
+    Draws bounding boxes around faces, a caption area, and text captions.
+    """
+    top, right, bottom, left = bounding_box
+    draw.rectangle(((left, top), (right, bottom)), outline=BOUNDING_BOX_COLOR)
+    text_left, text_top, text_right, text_bottom = draw.textbbox(
+        (left, bottom), name
+    )
+    draw.rectangle(
+        ((text_left, text_top), (text_right, text_bottom)),
+        fill=BOUNDING_BOX_COLOR,
+        outline=BOUNDING_BOX_COLOR,
+    )
+    draw.text(
+        (text_left, text_top),
+        name,
+        fill=TEXT_COLOR,
+    )
+
+
+def validate(model: str = "hog"):
+    """
+    Runs recognize_faces on a set of images with known faces to validate
+    known encodings.
+    """
+    for filepath in Path("validation").rglob("*"):
+        if filepath.is_file():
+            recognize_faces(
+                image_location=str(filepath.absolute()), model=model
+            )
+
+
+if __name__ == "__main__":
+    if args.train:
+        encode_known_faces(model=args.m)
+    if args.validate:
+        validate(model=args.m)
+    if args.test:
+        recognize_faces(image_location=args.f, model=args.m)

face-recognition/source_code_final/detector.py

@@ -0,0 +1,4 @@
+dlib==19.24.0
+face-recognition==1.3.0
+numpy==1.24.2
+Pillow==9.4.0