face_recognition

face_recognition is a Python library and command-line tool for recognizing and manipulating faces. It is built on dlib's state-of-the-art face recognition models, and the README reports 99.38% accuracy on the Labeled Faces in the Wild (LFW) benchmark. It provides a simple API for locating faces, extracting facial landmarks, computing face encodings, and comparing faces to identify people. ## Main Features - Find all faces in an image with `face_locations()`, including an optional deep-learning-based CNN model for higher accuracy (requires CUDA for good performance). - Locate and outline facial features (eyes, nose, mouth, chin) with `face_landmarks()`, enabling applications such as digital makeup. - Identify faces by comparing 128-dimensional face encodings generated by `face_encodings()` and matched using `compare_faces()`. - Include two command-line programs: `face_recognition` for identifying known people in a folder of images, and `face_detection` for outputting face bounding-box coordinates. ## Installation - Requires Python 3.3+ or Python 2.7, on macOS or Linux. Windows is not officially supported but may work with community-provided instructions. - `dlib` with Python bindings must be installed first (build from source on macOS/Ubuntu, or use a pre-configured VM). - Install via `pip3 install face_recognition` after installing `cmake` (e.g., `brew install cmake` on macOS). - Additional platform guides are included for Nvidia Jetson Nano, Raspberry Pi 2+, FreeBSD (`pkg install graphics/py-face-recognition`), and Windows. - A Docker image is provided for easier deployment to cloud hosts such as Heroku or AWS. ## Usage Example (Python) ```python import face_recognition # Find faces in an image image = face_recognition.load_image_file("your_file.jpg") face_locations = face_recognition.face_locations(image) # Get facial landmarks face_landmarks_list = face_recognition.face_landmarks(image) # Identify a person 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) ``` ## Command-Line Interface - `face_recognition ./known_people/ ./unknown_pictures/` prints one line per detected face, with the filename and recognized name (or `unknown_person`). - `--tolerance 0.54` makes matching stricter; `--show-distance true` prints the computed face distance. - `--cpus 4` (or `-1` for all cores) enables parallel processing on multi-core systems. - `face_detection ./folder_with_pictures/` prints top, right, bottom, left pixel coordinates for each face found. ## Example Scripts The repository includes many examples, including: - Face detection with the default HOG model and the CNN deep-learning model. - Real-time webcam recognition (simple and faster versions, requires OpenCV). - Face recognition in video files and on a Raspberry Pi with a camera. - HTTP web service using Flask. - K-nearest neighbors and SVM classifiers for training on multiple images per person. - Blurring faces in live webcam video. ## Caveats - The recognition model is trained on adults and may not perform well on children with the default comparison threshold of 0.6. - Accuracy may vary between ethnic groups; the wiki discusses known accuracy problems. - For deployment, a Dockerfile and prebuilt Docker images are included, with GPU support for Linux systems using Nvidia drivers and nvidia-docker. This project is widely used as a simple, high-level wrapper around dlib's face recognition capabilities and is suitable for prototyping and production applications where face detection and identification are needed.