datamoo-ai/deepface

Purpose and Entry Points

DeepFace is a Python facial-recognition and facial-attribute framework. Its public library facade is deepface/DeepFace.py, exported through deepface/__init__.py. Primary operations are verification, database search, embedding representation, face extraction, demographic analysis, and webcam streaming.

A separate REST deployment path begins at deepface/api/src/app.py and deepface/api/src/api.py; container startup is defined by Dockerfile and entrypoint.sh.

Public-API Orchestration

deepface/DeepFace.py presents static, user-facing operations and delegates to task modules rather than embedding model logic directly:

• verification: deepface/modules/verification.py

• identification/search: deepface/modules/recognition.py

• embedding generation: deepface/modules/representation.py

• attributes: deepface/modules/demography.py

This is the principal boundary between callers and the internal pipeline.

Shared Face Processing Pipeline

Detection is the common front end for recognition and analysis. deepface/modules/detection.py selects a detector, produces face regions/landmarks, aligns faces when enabled, and can invoke liveness checks. deepface/modules/preprocessing.py resizes and normalizes detected crops to model-specific input requirements.

Flow: image path/URL/base64/array → image decoding utilities → detection/alignment → padded, normalized face crops → task-specific inference. Core image and filesystem concerns are centralized in deepface/commons/image_utils.py and deepface/commons/folder_utils.py.

Pluggable Model Layer

deepface/modules/modeling.py is the model-selection/factory boundary. It supplies task models to callers and isolates supported model implementations:

• recognition model base and implementations: deepface/models/FacialRecognition.py, deepface/models/facial_recognition/ArcFace.py, deepface/models/facial_recognition/VGGFace.py

• detector base and backends: deepface/models/Detector.py, deepface/models/face_detection/RetinaFace.py, deepface/models/face_detection/OpenCv.py

• demographic models: deepface/models/Demography.py, deepface/models/demography/Age.py

The package wraps external ML ecosystems such as TensorFlow/Keras, OpenCV, Dlib, MTCNN, MediaPipe, RetinaFace, YOLO, and InsightFace-derived models.

Recognition and Search Flows

Representation converts each detected face into an embedding. Verification compares two embeddings using configured distance metrics and thresholds. Recognition searches a local image database: it derives/stores embeddings in a pickle cache and compares an input embedding against that cache. These responsibilities reside in deepface/modules/representation.py, deepface/modules/verification.py, and deepface/modules/recognition.py.

Database indexing/vector services are explicitly outside the repository’s core: integrations with vector indexes/databases are expected to be composed by consumers for large-scale search.

Attributes, Liveness, and Streaming

Demographic inference applies independent age, gender, race, and emotion predictors to detected faces in deepface/modules/demography.py. Optional anti-spoofing uses deepface/models/spoofing/FasNet.py during face processing. deepface/modules/streaming.py drives webcam frames through detection, recognition, and demographic analysis with temporal focus/display behavior.

REST Service and Runtime Boundary

The API layer maps HTTP requests into the same DeepFace operations; routing/service separation is under deepface/api/src/modules/core/routes.py and deepface/api/src/modules/core/service.py. It accepts uploads and image references/encodings, exposing library functionality without a browser UI. The documented production runtime is Gunicorn, optionally packaged in Docker; scripts under scripts/service.sh and scripts/dockerize.sh operate those deployment modes.