DOCSEARCHbyAlgolia
Submit Docs

face-alignment

repository·master·Indexed 27 days ago

https://github.com/1adrianb/face-alignment

A Python library for detecting 2D and 3D facial landmarks using state-of-the-art deep learning methods (FAN). It supports multiple face detection backends including SFD, BlazeFace, YuNet, RetinaFace, and SCRFD, and requires Python 3.9+ and PyTorch >= 2.0.

Tokens
1.2K
Snippets
6
Records
8
Agent score
43%

What's inside face-alignment

  2. Build from source

    master

    To build the library from source:

    1. Install PyTorch and its dependencies.
    2. Clone the repository.
    3. Install requirements and the package.
    git clone https://github.com/1adrianb/face-alignment
cd face-alignment
pip install -r requirements.txt
pip install .
    git clone https://github.com/1adrianb/face-alignment
pip install -r requirements.txt
pip install .

  4. Process an entire directory of images

    master

    To process all images in a folder at once, use the get_landmarks_from_directory() method.

    import face_alignment
from skimage import io

fa = face_alignment.FaceAlignment(face_alignment.LandmarksType.TWO_D, flip_input=False)

preds = fa.get_landmarks_from_directory('../test/assets/')

  5. Detect 2D facial landmarks

    master

    Use face_alignment.FaceAlignment with face_alignment.LandmarksType.TWO_D to detect 2D facial landmarks in an image. Use get_landmarks() to retrieve the predictions.

    import face_alignment
from skimage import io

fa = face_alignment.FaceAlignment(face_alignment.LandmarksType.TWO_D, flip_input=False)

input = io.imread('../test/assets/aflw-test.jpg')
preds = fa.get_landmarks(input)

  6. Detect 3D facial landmarks

    master

    Use face_alignment.FaceAlignment with face_alignment.LandmarksType.THREE_D to detect 3D facial landmarks in an image. Use get_landmarks() to retrieve the predictions.

    import face_alignment
from skimage import io

fa = face_alignment.FaceAlignment(face_alignment.LandmarksType.THREE_D, flip_input=False)

input = io.imread('../test/assets/aflw-test.jpg')
preds = fa.get_landmarks(input)

  7. Configure device, dtype, and compilation

    master

    You can control the hardware device, data type, and compilation behavior when initializing FaceAlignment:

    • device: Specify the device (e.g., 'cuda' for NVIDIA GPUs, 'mps' for Apple M GPUs, or 'cpu').
    • dtype: Specify the torch data type (e.g., torch.bfloat16).
    • compile: Boolean. The network is compiled with torch.compile by default for faster inference. Set compile=False to skip the initial compilation delay (approx. 25s) for instant startup.
    • max_batch_size: Integer. Limit the batch size for multi-face images on low-memory GPUs (default is 1).

    Example configuration:

    import torch
import face_alignment

# Use CUDA with bfloat16
fa = face_alignment.FaceAlignment(face_alignment.LandmarksType.TWO_D, dtype=torch.bfloat16, device='cuda')

# Use CPU and skip compilation for instant startup
fa = face_alignment.FaceAlignment(face_alignment.LandmarksType.TWO_D, device='cpu', compile=False)

# Limit batch size for low-memory GPUs
fa = face_alignment.FaceAlignment(face_alignment.LandmarksType.TWO_D, device='cuda', max_batch_size=8)

  8. Configure face detectors

    master

    The library supports several face detection backends via the face_detector argument in FaceAlignment.

    Detectorface_detector=Notes
    SFD'sfd'Default, most accurate, but slower
    BlazeFace'blazeface'Faster; supports face_detector_kwargs={'back_model': True} for back camera/distant faces
    YuNet'yunet'Fast; CPU only (OpenCV DNN)
    RetinaFace'retinaface'Balanced speed/accuracy
    SCRFD'scrfd'Fast; CPU only (requires pip install onnxruntime)
    dlib'dlib'Deprecated
    Folder'folder'Skips detection; loads pre-computed bounding boxes from .npy, .t7, or .pth files matching image filenames

    Example using BlazeFace with the back camera model:

    fa = face_alignment.FaceAlignment(face_alignment.LandmarksType.TWO_D, face_detector='blazeface', face_detector_kwargs={'back_model': True})