# mbyanfei/face_recognition architecture

> Architecture diagram of the GitHub repository mbyanfei/face_recognition, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-08). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mbyanfei/face_recognition
- Repository: https://github.com/mbyanfei/face_recognition

## Overview

##### Project type and purpose
- This is an open-source Python library for face detection, landmark extraction, and face recognition.
- It exposes both a Python API (`face_recognition` module) and two CLI tools (`face_detection`, `face_recognition`).
- It relies on dlib’s C++ deep-learning models under the hood and provides Docker examples for deployment.

##### File structure
Top-level:
- face_recognition/              ← Core Python package
- examples/                      ← Sample scripts (web service, webcam, batch, KNN, SVM)
- docs/                          ← Sphinx documentation source
- docker/ & Dockerfile(.gpu)    ← Containerized environments (CPU/GPU, Jupyter, Kubeflow)
- tests/                         ← Unit tests
- CLI entry scripts in root: Dockerfile, docker-compose.yml, Makefile, setup files
Patterns & config:
- setuptools config: setup.py, setup.cfg, pyproject.toml
- CI/CD: .github/workflows/main.yml, tox.ini
- Requirements: requirements.txt, requirements_dev.txt, requirements_docs.txt

##### README for additional insights
- Describes the high-level pipeline: load image → face location → face landmarks → face encoding → face comparison.
- Mentions GPU vs CPU face detection models.
- Provides usage modes: Python API, command-line, Docker, Raspberry Pi, Jetson Nano, web service.

##### Detail
- Entry points (CLI flags, API calls, web endpoints).
- Both detection strategies (HOG vs CNN) as selectable.
- Test harness and CI pipeline on the periphery.
- Versioned model files (dlib’s .dat files) as part of the native engine.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User & Examples Layer
    subgraph "User Interfaces & Examples"
        direction TB
        UI_API["Python API Client"]:::user
        FDCLI["CLI: face_detection"]:::user
        FRCLI["CLI: face_recognition"]:::user
        EX_WS["Web Service Example"]:::user
        EX_Cam["Webcam Example"]:::user
        EX_Vid["Video File Example"]:::user
        EX_Notebook["Realtime Tracking Notebook"]:::user
    end

    %% Core Library Layer
    subgraph "Core Processing Layer"
        direction TB
        Init["face_recognition/__init__.py"]:::core
        API["face_recognition/api.py"]:::core
        subgraph "Detection Submodule"
            direction TB
            DET_HOG["HOG Detector"]:::core
            DET_CNN["CNN Detector"]:::core
        end
        LM["Landmark Extraction"]:::core
        ENC["Encoding & Comparison"]:::core
    end

    %% Native Engine Layer
    subgraph "Native Engine"
        direction TB
        Engine["dlib C++ Engine"]:::engine
        Models["Pre-trained Models (.dat)"]:::engine
        GPU["CUDA Runtime (Optional)"]:::engine
    end

    %% Data Sources & Outputs
    subgraph "Data Sources & Outputs"
        direction TB
        IMG["Image Files"]:::data
        VID["Video Streams"]:::data
        CAM["Webcam / IP Camera"]:::data
        OUT["Outputs: Boxes, Landmarks, JSON, Annotated Media"]:::data
    end

    %% Deployment & Infrastructure Layer
    subgraph "Deployment & Infrastructure"
        direction TB
        Dock_CPU["Docker CPU Image"]:::infra
        Dock_GPU["Docker GPU Image"]:::infra
        Compose["docker-compose.yml"]:::infra
        CI["GitHub Actions & tox"]:::infra
        Cloud["Cloud Hosts (Heroku/AWS/Kubeflow)"]:::infra
    end

    %% Connections: User to Core
    UI_API -->|"import face_recognition"| API
    FDCLI -->|"calls CLI wrapper"| Init
    FRCLI -->|"calls CLI wrapper"| Init
    EX_WS -->|"uses API"| API
    EX_Cam -->|"uses API & OpenCV"| API
    EX_Vid -->|"uses API & OpenCV"| API
    EX_Notebook -->|"uses API"| API

    %% Core internal flow
    API -->|"load_image() → numpy array"| DET_HOG
    API -->|"load_image() → numpy array"| DET_CNN
    DET_HOG -->|"detect_faces() → coords"| LM
    DET_CNN -->|"detect_faces() → coords"| LM
    LM -->|"extract_landmarks() → points"| ENC
    ENC -->|"compare_faces() → booleans"| API

    %% Core to Engine
    DET_CNN -->|"via Python bindings"| Engine
    DET_HOG -->|"via Python bindings"| Engine
    ENC -->|"via Python bindings"| Engine
    Engine -->|"loads .dat models"| Models
    Engine -->|"uses GPU if available"| GPU

    %% Data sources into Core
    IMG -->|"input"| API
    VID -->|"input"| API
    CAM -->|"input"| API
    API -->|"result"| OUT

    %% Deployment connections
    Dock_CPU -->|"builds image"| API
    Dock_GPU -->|"builds image with CUDA"| API
    Compose -->|"orchestrate containers"| Dock_CPU
    Compose -->|"orchestrate containers"| Dock_GPU
    CI -->|"runs tests & builds"| Dock_CPU
    CI -->|"runs tests & builds"| Dock_GPU
    Dock_CPU -->|"deploy"| Cloud
    Dock_GPU -->|"deploy"| Cloud

    %% Click Events for Component Mapping
    click Init "https://github.com/mbyanfei/face_recognition/blob/master/face_recognition/__init__.py"
    click API "https://github.com/mbyanfei/face_recognition/blob/master/face_recognition/api.py"
    click FDCLI "https://github.com/mbyanfei/face_recognition/blob/master/face_recognition/face_detection_cli.py"
    click FRCLI "https://github.com/mbyanfei/face_recognition/blob/master/face_recognition/face_recognition_cli.py"
    click EX_WS "https://github.com/mbyanfei/face_recognition/blob/master/examples/web_service_example.py"
    click EX_Cam "https://github.com/mbyanfei/face_recognition/blob/master/examples/facerec_from_webcam.py"
    click EX_Vid "https://github.com/mbyanfei/face_recognition/blob/master/examples/facerec_from_video_file.py"
    click EX_Notebook "https://github.com/mbyanfei/face_recognition/blob/master/examples/ipynb_examples/track_faces_on_video_realtime.ipynb"
    click Dock_CPU "https://github.com/mbyanfei/face_recognition/tree/master/docker/cpu/Dockerfile"
    click Dock_GPU "https://github.com/mbyanfei/face_recognition/tree/master/docker/gpu/Dockerfile"
    click Compose "https://github.com/mbyanfei/face_recognition/blob/master/docker-compose.yml"
    click CI "https://github.com/mbyanfei/face_recognition/blob/master/.github/workflows/main.yml"
    click CI "https://github.com/mbyanfei/face_recognition/blob/master/tox.ini"

    %% Styles
    classDef user fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef core fill:#90EE90,stroke:#333,stroke-width:1px
    classDef engine fill:#FFA500,stroke:#333,stroke-width:1px
    classDef infra fill:#D3D3D3,stroke:#333,stroke-width:1px
    classDef data fill:#FFFACD,stroke:#333,stroke-width:1px
```
