Claude-skill-registry deepface-basic-usage

Basic usage guide for the DeepFace library (face recognition, verification, analysis).

install

source · Clone the upstream repo

git clone https://github.com/majiayu000/claude-skill-registry

Claude Code · Install into ~/.claude/skills/

T=$(mktemp -d) && git clone --depth=1 https://github.com/majiayu000/claude-skill-registry "$T" && mkdir -p ~/.claude/skills && cp -r "$T/skills/data/deepface-basic-usage" ~/.claude/skills/majiayu000-claude-skill-registry-deepface-basic-usage && rm -rf "$T"

manifest: skills/data/deepface-basic-usage/SKILL.md

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

Dependencies: DeepFace installs many dependencies (tensorflow/keras or pytorch depending on model). Ensure your environment is set up correctly.
Weights Download: First run will download model weights to
```
~/.deepface/weights
```
.

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)

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