# vectornguyen76/face-recognition architecture

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

- Interactive diagram: https://gitdiagram.com/vectornguyen76/face-recognition
- Repository: https://github.com/vectornguyen76/face-recognition

## Overview

##### Main Components
- Input and Preprocessing:
- Image/Video input source
- Face alignment (utilizing face_align.py and the face_alignment module)
- Face Detection:
- Multiple submodules: Retinaface (under face_detection/retinaface), Yolov5-face (under face_detection/yolov5_face), SCRFD (under face_detection/scrfd)
- Face Recognition:
- ArcFace (under face_recognition/arcface) where feature extraction and similarity measures are computed using the Cosine Similarity algorithm.
- Face Tracking:
- Tracking implementation provided by ByteTrack (under face_tracking folder)
- Datasets and Feature Management:
- The datasets directory (includes backup, data, face_features, and new_persons folders)
- The add_persons.py script (for managing additions to the dataset)
- Control Scripts:
- High-level scripts such as detect.py, recognize.py, and tracking.py which orchestrate these modules.

##### Relationships and Interactions
- Data flows from the input (camera or image source) through the pipeline:
- First, the detection modules identify faces in an image.
- Next, face alignment (if applied) preprocesses regions of interest.
- Then, the recognition module (ArcFace) extracts feature vectors from detected faces.
- The extracted features are compared using the Cosine Similarity algorithm to match faces with those stored in the datasets.
- Simultaneously, face tracking (using ByteTrack and supporting trackers) maintains continuity of face identities across video frames.
- There is an interaction between the dataset management scripts (e.g., add_persons.py) and the feature extraction modules which update the face_features storage.

##### Architectural Patterns and Design Principles
- Modular design: Each main function (detection, recognition, tracking) is separated into its own module, making the system flexible and extensible.
- Pipeline architecture: The sequence from input → detection → alignment → recognition → tracking is an example of a classic processing pipeline.
- Multiple algorithm support: Emphasize that for face detection there are three options (Retinaface, Yolov5-face, SCRFD), allowing for flexibility in performance vs. accuracy trade-offs.
- Data management: A clear separation between static datasets (images and backups) and dynamic operations (feature extraction and matching).

##### Relevant Technologies, Frameworks, or Libraries
- Torch and torchvision (mentioned in the installation steps) indicate deep learning is core to detection and recognition.
- Specific architectures like RetinaFace, YOLO (variants in Yolov5-face), SCRFD, and ArcFace should be annotated.
- The use of configuration files (e.g., YAML in the face_tracking/config directory) suggests configurable parameters for tracking.

##### Elements
- Each major component should have a clear label:
- “Input Capture”
- “Face Detection” with sub-components for Retinaface, Yolov5-face, SCRFD
- “Face Alignment” (if applied)
- “Face Recognition (ArcFace)”
- “Matching (Cosine Similarity)”
- “Face Tracking (ByteTrack)”
- “Dataset Management”
- Data flow from image/video input through the detection and alignment stages to recognition, matching, and tracking.
- Dependencies such as how the output of one module becomes the input to another.
- If possible, include notes about configurable parameters (drawn from config files like those in face_tracking/config) and mention external libraries (like PyTorch).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Global entities
    Input["Input Source (Camera/Image)"]:::input

    %% Preprocessing & Alignment Subgraph
    subgraph "Preprocessing & Alignment"
        FA1["Face Alignment (Script)"]:::processing
        FA2["Face Alignment (Module)"]:::processing
        FA1 --> FA2
    end

    %% Face Detection Subgraph
    subgraph "Face Detection"
        RF["RetinaFace"]:::detection
        Y5["Yolov5-face"]:::detection
        SCR["SCRFD"]:::detection
    end

    DET_AGG["Detection Aggregator"]:::processing

    %% Recognition, Matching, and Dataset Management
    FR["Face Recognition (ArcFace)"]:::recognition
    MATCH["Matching (CosineSimilarity)"]:::recognition
    DS["Dataset Management"]:::dataset
    ADD["Add Persons Script"]:::dataset

    %% Face Tracking
    FT["Face Tracking (ByteTrack)"]:::tracking

    %% Control Scripts Subgraph
    subgraph "Control Scripts"
        D_SCRIPT["detect.py"]:::control
        R_SCRIPT["recognize.py"]:::control
        T_SCRIPT["tracking.py"]:::control
    end

    %% Main Pipeline Flow
    Input --> FA1
    FA2 --> RF
    FA2 --> Y5
    FA2 --> SCR

    RF --> DET_AGG
    Y5 --> DET_AGG
    SCR --> DET_AGG

    DET_AGG --> FR
    DET_AGG --> FT

    FR --> MATCH
    MATCH --> DS
    DS --> ADD

    %% Control Scripts dotted control flow
    D_SCRIPT -.-> DET_AGG
    R_SCRIPT -.-> FR
    T_SCRIPT -.-> FT

    %% Click Events for Preprocessing & Alignment
    click FA1 "https://github.com/vectornguyen76/face-recognition/blob/master/face_align.py"
    click FA2 "https://github.com/vectornguyen76/face-recognition/tree/master/face_alignment/"

    %% Click Events for Face Detection modules
    click RF "https://github.com/vectornguyen76/face-recognition/tree/master/face_detection/retinaface/"
    click Y5 "https://github.com/vectornguyen76/face-recognition/tree/master/face_detection/yolov5_face/"
    click SCR "https://github.com/vectornguyen76/face-recognition/tree/master/face_detection/scrfd/"

    %% Click Event for Face Recognition
    click FR "https://github.com/vectornguyen76/face-recognition/tree/master/face_recognition/arcface/"

    %% Click Event for Face Tracking
    click FT "https://github.com/vectornguyen76/face-recognition/blob/master/face_tracking/tracker/byte_tracker.py"

    %% Click Events for Dataset Management
    click DS "https://github.com/vectornguyen76/face-recognition/tree/master/datasets/"
    click ADD "https://github.com/vectornguyen76/face-recognition/blob/master/add_persons.py"

    %% Click Events for Control Scripts
    click D_SCRIPT "https://github.com/vectornguyen76/face-recognition/blob/master/detect.py"
    click R_SCRIPT "https://github.com/vectornguyen76/face-recognition/blob/master/recognize.py"
    click T_SCRIPT "https://github.com/vectornguyen76/face-recognition/blob/master/tracking.py"

    %% Styles
    classDef input fill:#ffcccc,stroke:#880000,stroke-width:2px;
    classDef processing fill:#ccffcc,stroke:#008800,stroke-width:2px;
    classDef detection fill:#ccccff,stroke:#000088,stroke-width:2px;
    classDef recognition fill:#ffcc99,stroke:#aa5500,stroke-width:2px;
    classDef tracking fill:#ccffff,stroke:#008888,stroke-width:2px;
    classDef dataset fill:#ffccff,stroke:#880088,stroke-width:2px;
    classDef control fill:#ffffcc,stroke:#888800,stroke-width:2px;
```
