# hairymax/face-antispoofing architecture

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

- Interactive diagram: https://gitdiagram.com/hairymax/face-antispoofing
- Repository: https://github.com/hairymax/face-antispoofing

## Overview

##### Project Type & Purpose
- The project implements a facial anti-spoofing system that detects spoofing attacks (e.g., print and replay attacks) using a CNN. It focuses on both training models on the CelebA Spoof dataset and running inference (including on video streams) with pretrained models.
- The system covers data preparation, training, model conversion (from PyTorch to ONNX), and inference. It also includes a face detection component (using YOLO) to locate faces before classification.

##### Analyzing the File Structure
- Key high-level files:
- Data preparation: data_preparation.py (crops and processes raw data).
- Training: train.py and src/train_main.py (drive model training, utilizing architecture defined in src/NN.py).
- Model conversion: model_to_onnx.py (converts a trained .pth model to ONNX).
- Inference: video_predict.py and src/FaceAntiSpoofing.py (run predictions on videos or webcam input) and supporting code in src/antispoof_pretrained.py.
- Face Detection: Located under src/face_detector (with YOLO.py and associated utilities).
- The 'saved_models' directory includes pretrained models in both ONNX and PyTorch formats.
- The README explains the roles, arguments, and overall workflow of the project.

##### Main Components & Their Interactions
a. Data Preparation Module:
- Script: data_preparation.py.
b. Dataset Loader / Preprocessing:
- Located in src/dataset_loader.py; prepares PyTorch datasets, possibly applying Fourier transform augmentations for training.
c. Training Engine:
- Core modules: src/train_main.py and src/NN.py.
- Reads data via dataset_loader.py, defines the CNN architecture, and manages model training with configuration details in src/config.py.
- Outputs training snapshots and logs (with tensorboard integration, as mentioned in the README).
d. Model Conversion:
- Script: model_to_onnx.py.
- Function: Converts a trained PyTorch (.pth) model into an ONNX model suitable for deployment.
e. Inference / Prediction Pipeline:
- Primary entry points: video_predict.py and src/FaceAntiSpoofing.py.
- These modules load pretrained ONNX models (or PyTorch ones via antispoof_pretrained.py) to perform real-time or video-based facial anti-spoofing.
- Utilizes the face detection component (src/face_detector, implementing YOLO) to locate faces before applying the anti-spoof detection model.

##### Architectural Patterns & Design Principles
- Modular structure: Separation of data preparation, model training, conversion, and inference into distinct scripts and modules.
- Reusability: Core functionalities (like face detection and dataset handling) are encapsulated in dedicated modules (in src/).
- Configurability: Use of a configuration module (src/config.py) ensures that parameters can be easily adjusted.
- Scalability: Clear division means additional models, preprocessing steps, or inference enhancements can be integrated.

##### Final Checklist
- Every high-level module is clearly labeled.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Data Preparation & Training Pipeline
    subgraph "Data Preparation & Training"
        N1("CelebA Spoof Dataset"):::external
        N2("Data Preparation (data_preparation.py)"):::data
        N3("Dataset Loader (src/dataset_loader.py)"):::data
        subgraph "Training Engine"
            t1("Train Script (train.py)"):::training
            t2("Train Main (src/train_main.py)"):::training
            t3("CNN Architecture (src/NN.py)"):::training
            t4("Configuration (src/config.py)"):::training
        end
        N5("Saved Models (saved_models)"):::storage
    end

    %% Model Conversion
    subgraph "Model Conversion"
        N6("Model Conversion (model_to_onnx.py)"):::conversion
    end

    %% Inference Pipeline
    subgraph "Inference Pipeline"
        N7("Video/Webcam Input"):::external
        i2("Face Detection (src/face_detector)"):::inference
        subgraph "Inference Engine"
            i3("Video Predict (video_predict.py)"):::inference
            i4("FaceAntiSpoofing (src/FaceAntiSpoofing.py)"):::inference
            i5("AntiSpoof Pretrained Loader (src/antispoof_pretrained.py)"):::inference
        end
        N10("Prediction Output"):::inference
    end

    %% Data Preparation -> Training Flow
    N1 -->|"raw_data"| N2
    N2 -->|"cropped_images"| N3
    N3 -->|"training_data"| t1

    %% Inside Training Engine
    t1 -->|"executes"| t2
    t2 -->|"defines_CNN"| t3
    t3 -->|"uses_config"| t4
    t4 -->|"output_model(.pth)"| N5

    %% Model Conversion Flow
    N5 -->|"input_.pth"| N6
    N6 -->|"ONNX_model"| N5

    %% Inference Flow - Model Loading
    N5 -->|"pretrained_ONNX"| i4

    %% Inference Pipeline Flow - Video Stream to Prediction
    N7 -->|"video_stream"| i2
    i2 -->|"detected_face"| i3
    i3 -->|"invokes_inference"| i4
    i5 -->|"provides_pretrained"| i4
    i4 -->|"produces_result"| N10

    %% Click Events
    click N2 "https://github.com/hairymax/face-antispoofing/blob/main/data_preparation.py"
    click N3 "https://github.com/hairymax/face-antispoofing/blob/main/src/dataset_loader.py"
    click t1 "https://github.com/hairymax/face-antispoofing/blob/main/train.py"
    click t2 "https://github.com/hairymax/face-antispoofing/blob/main/src/train_main.py"
    click t3 "https://github.com/hairymax/face-antispoofing/blob/main/src/NN.py"
    click t4 "https://github.com/hairymax/face-antispoofing/blob/main/src/config.py"
    click N6 "https://github.com/hairymax/face-antispoofing/blob/main/model_to_onnx.py"
    click i3 "https://github.com/hairymax/face-antispoofing/blob/main/video_predict.py"
    click i4 "https://github.com/hairymax/face-antispoofing/blob/main/src/FaceAntiSpoofing.py"
    click i5 "https://github.com/hairymax/face-antispoofing/blob/main/src/antispoof_pretrained.py"
    click i2 "https://github.com/hairymax/face-antispoofing/tree/main/src/face_detector"
    click N5 "https://github.com/hairymax/face-antispoofing/tree/main/saved_models"

    %% Class Definitions
    classDef external fill:#D2B4DE,stroke:#000,stroke-width:2px;
    classDef data fill:#AED6F1,stroke:#000,stroke-width:2px;
    classDef training fill:#ABEBC6,stroke:#000,stroke-width:2px;
    classDef conversion fill:#F9E79F,stroke:#000,stroke-width:2px;
    classDef inference fill:#F5B7B1,stroke:#000,stroke-width:2px;
    classDef storage fill:#FADBD8,stroke:#000,stroke-width:2px;
```
