face_recognition Python Library

The API has undergone changes to how it returns data for multiple faces and facial features:

• face_locations: Now returns an array listing the coordinates of each detected face.
• face_landmarks_list: Now returns an array containing the locations of each facial feature for every face detected. For example, face_landmarks_list[0]['left_eye'] provides the location and outline of the first person's left eye.
• my_face_encoding: Now contains a universal 'encoding' of facial features that can be used to compare against any other face image.

When using face_recognition, be aware of the following limitations:

• Age: The model is trained on adults and performs poorly on children. It may frequently misidentify children using the default comparison threshold of 0.6.
• Ethnicity: Accuracy may vary between different ethnic groups.

When using face_recognition, be aware of the following limitations:

• Age Bias: The models were trained on adult data. They may not perform well on children. Using the default threshold of 0.6 often results in failure to distinguish children's faces.
• Demographic Bias: Accuracy may vary across different ethnicities. Refer to the project wiki for details on accuracy variations (e.g., differences between European and Asian individuals).

Because face_recognition depends on dlib (C++), deploying to cloud hosts like Heroku or AWS can be difficult. The recommended approach is to use Docker.

To run the provided example locally using Docker Compose:

docker-compose up --build

GPU Support (Linux): If you have an NVIDIA GPU (drivers >= 384.81) and nvidia-docker installed, you can run the example on the GPU by modifying docker-compose.yml to:

1. Uncomment dockerfile: Dockerfile.gpu
2. Uncomment runtime: nvidia

If you need to install from the source code (e.g., for development or using a specific version from GitHub), follow these steps:

1. Clone the repository or download the tarball:

   $ git clone git://github.com/ageitgey/face_recognition
   # OR
   $ curl -OL https://github.com/ageitgey/face_recognition/tarball/master

2. Install using setup.py: Navigate to the directory containing the source and run:

   $ python setup.py install

You can use PyInstaller to create a standalone executable that runs without requiring a Python installation.

Warning: This requires custom configuration to work correctly with the face_recognition library. Refer to this GitHub issue for the specific configuration steps.

Install the pre-configured package using pkg:

pkg install graphics/py-face_recognition

You can pull up-to-date prebuilt images for face_recognition from Docker Hub. The project provides different image flavors depending on your hardware and workflow requirements:

CPU Images

Use these if you do not have an NVIDIA GPU or do not want to deal with driver configurations. They run out of the box.

• cpu-latest, cpu, cpu-0.1, latest
• cpu-jupyter-kubeflow-latest, cpu-jupyter-kubeflow, cpu-jupyter-kubeflow-0.1 (includes Jupyter/Kubeflow support)

GPU Images

Use these for hardware-accelerated face recognition. These require NVIDIA drivers and the NVIDIA container toolkit.

• gpu-latest, gpu, gpu-0.1
• gpu-jupyter-kubeflow-latest, gpu-jupyter-kubeflow, gpu-jupyter-kubeflow-0.1 (includes Jupyter/Kubeflow support)

docker pull animcogn/face_recognition:gpu