igamenovoer/skills/libraries/deepface/deepface-basic-usage

Skill: DeepFace Basic Usage

This skill provides a quick reference and guide for using the deepface library for face recognition tasks.

Overview

DeepFace is a hybrid face recognition framework for Python that wraps state-of-the-art models (VGG-Face, FaceNet, ArcFace, etc.) and detectors (RetinaFace, MtCNN, YOLO, etc.).

Installation

pip install deepface
# Or with pixi
pixi add deepface

Core Functions

Import:

from deepface import DeepFace

1. Face Verification (1:1)

Determines if two images belong to the same person.

result = DeepFace.verify(
    img1_path = "img1.jpg",
    img2_path = "img2.jpg",
    model_name = "VGG-Face", # Optional: see Model Selection below
    detector_backend = "opencv", # Optional: see Detector Selection below
    distance_metric = "cosine", # Optional: cosine, euclidean, euclidean_l2
    align = True, # Optional: Align faces before verification
)

# result is a dict:
# {
#   "verified": True,
#   "distance": 0.256,
#   "threshold": 0.40,
#   "model": "VGG-Face",
#   "detector_backend": "opencv",
#   "similarity_metric": "cosine",
#   "facial_areas": {"img1": {...}, "img2": {...}},
#   "time": 1.23
# }

2. Face Recognition / Search (1:N)

Finds identity of an input image in a database (folder of images).

Directory-based (find):

dfs = DeepFace.find(
    img_path = "img.jpg",
    db_path = "/path/to/images_folder",
    model_name = "VGG-Face",
    detector_backend = "opencv"
)
# Returns a list of pandas DataFrames (one per face detected in input)

Database-backed (search): Supports backends like Postgres (pgvector), Pinecone, Milvus, Weaviate, etc.

# Register
DeepFace.register(img="img1.jpg")
# Search
dfs = DeepFace.search(img="target.jpg")

3. Facial Attribute Analysis

Predicts age, gender, race, and emotion.

objs = DeepFace.analyze(
    img_path = "img.jpg",
    actions = ['age', 'gender', 'race', 'emotion'],
    detector_backend = "opencv"
)
# Returns a list of dicts (one per face)

4. Embeddings (Representation)

Get the vector representation of a face.

embedding_objs = DeepFace.represent(
    img_path = "img.jpg",
    model_name = "VGG-Face",
    detector_backend = "opencv"
)
# Returns list of dicts:
# [
#   {
#     "embedding": [0.1, 0.5, ...],
#     "facial_area": {...}
#   }
# ]

Configuration Options

Available Models

VGG-Face (default), Facenet, Facenet512, OpenFace, DeepFace, DeepID, ArcFace, Dlib, SFace, GhostFaceNet.

Recommendation:

• Accuracy: ArcFace, Facenet512, VGG-Face
• Legacy/Lower Accuracy: DeepFace, OpenFace

Available Detectors

opencv (default, fast), ssd, dlib, mtcnn, retinaface (highly accurate), mediapipe, yolov8, centerface.

Recommendation:

• Speed: opencv, ssd
• Accuracy: retinaface, mtcnn

Distance Metrics

cosine (default), euclidean, euclidean_l2.

Common Issues & Tips

1. Dependencies: DeepFace installs many dependencies (tensorflow/keras or pytorch depending on model). Ensure your environment is set up correctly.
2. Weights Download: First run will download model weights to ~/.deepface/weights.
3. Face Not Found: If no face is detected, functions may raise ValueError. Set enforce_detection=False to skip detection (treats whole image as face) or handle the exception.

   DeepFace.verify(..., enforce_detection=False)
   

4. Backend Compatibility: If using specialized detectors (like retinaface or dlib), ensure their specific pip packages are installed.