# jinghuizhou/awesome_face_antispoofing architecture

> Architecture diagram of the GitHub repository jinghuizhou/awesome_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/jinghuizhou/awesome_face_antispoofing
- Repository: https://github.com/jinghuizhou/awesome_face_antispoofing

## Overview

Based on our analysis of the file tree and README, this project is a single-shot face anti-spoofing system implemented in Python using PyTorch. The system uses a two-stage strategy – first, it extracts face landmarks (and crops the image accordingly) to isolate the facial region, and second, it classifies the cropped patches as genuine or attack using several state‐of‐the‐art deep neural network models.

##### Main Components
- Data & Configuration:
- “data” directory as representing the training resources, raw data files (e.g., “test.txt”) and dataset organization.
- The “config.py” file should be depicted as the central configuration module that holds paths, parameters (batch size, network selection), and dataset filelists.
- Preprocessing / Landmark Extraction:
- The “detlandmark” folder contains scripts such as “crop.py”, “detlandmark.py”, and “detlandmark_imgs.py”. These modules perform the face landmark extraction (leveraging an external tool called “face_alignment”) and crop the relevant face regions based on landmark positions.
- Subfolders like “inference_images/attack” and “inference_images/genuine” which suggest pre-cropped images are being organized for inference.
- Model Architecture:
- The “models” directory houses the implementations of various networks (e.g., “detnet.py”, “nasnet.py”, “xception.py”) along with a basic module helper. These define the different architectures tested in the experiments.
- Training & Inference:
- “main.py”, “make.py” and “Makefile” are responsible for initiating training by using the chosen network (specified in “config.py”) and performing the binary classification training.
- “inference.py” takes care of running the model on new images and producing an inference report.
- Evaluation & Visualization:
- Files such as “loss.py” and “roc.py” indicate evaluation metrics and performance (ROC curves) computed post-training.
- The “utils” folder (with “Visualizer.py”) and the script “vis_cropface.py” help in visualizing the cropped facial images in training/validation sets.

##### Relationships and Interactions
- Data Flow:
- Raw data (from the “data” folder) feeds into the preprocessing stage.
- The “detlandmark” module uses external libraries for landmark detection, processes the raw images, and outputs cropped face patches.
- The cropped images, along with their labels (genuine vs. attack), are then used by the training script – “main.py” – in combination with the selected model from the “models” folder.
- Training & Inference:
- After training, the project supports inference (via “inference.py”), which uses the same preprocessing pipeline and selected network to predict live images.
- Evaluation scripts (“roc.py”, “loss.py”) analyze the performance of the underlying model.
- Configuration & Setup:
- “config.py” centrally manages data paths, network selection, and other hyperparameters, impacting all parts of the pipeline.

##### Architectural Patterns & Design Principles
- Modularity: The clear separation between configuration, preprocessing (landmark extraction), model definitions, training/inference, and evaluation signifies a modular, organized architecture.
- Pipeline Flow: The project’s nature as a face anti-spoofing system showcases a sequential pipeline where data flows from ingestion through processing to final decision making.
- Extensibility: The use of various models in the “models” directory (and external integration with “face_alignment”) underscores the project’s emphasis on experimenting with leading-edge architectures.

- Components:
- Data Source (raw images and dataset descriptions).
- Configuration module (config.py).
- Deep Learning Models (several architectures in the “models” folder).
- Training & Inference Engine (main.py and inference.py).
- Evaluation and Visualization Tools (loss.py, roc.py, utils/Visualizer.py, and vis_cropface.py).
- Relationships:
- Labels & Visual Cues:
- Interaction with External Libraries:

##### Final Recommendations
- Component has a brief label and, if possible, a short note indicating its purpose (e.g., “detlandmark: Extract and crop face landmarks”).

## Diagram (Mermaid)

```mermaid
flowchart TD
    A("Data Directory"):::data
    B("Configuration (config.py)"):::config

    subgraph "Preprocessing / Landmark Extraction"
        C1("detlandmark/detlandmark.py"):::preprocessing
        C2("detlandmark/crop.py"):::preprocessing
        C3("detlandmark/detlandmark_imgs.py"):::preprocessing
        C4("Inference Images (Attack)"):::preprocessing
        C5("Inference Images (Genuine)"):::preprocessing
        C6("External: face_alignment"):::external
    end

    subgraph "Model Architecture"
        D1("models/detnet.py"):::model
        D2("models/nasnet.py"):::model
        D3("models/xception.py"):::model
        D4("models/BasicModule.py"):::model
    end

    subgraph "Training & Inference"
        E1("main.py"):::training
        E2("make.py"):::training
        E3("Makefile"):::training
        E4("inference.py"):::training
    end

    subgraph "Evaluation & Visualization"
        F1("loss.py"):::evaluation
        F2("roc.py"):::evaluation
        F3("utils/Visualizer.py"):::evaluation
        F4("vis_cropface.py"):::evaluation
    end

    %% Data flows from raw data to preprocessing
    A -->|"raw_data"| C1
    A --> C2
    A --> C3
    A --> C4
    A --> C5

    %% Configuration influences components across the pipeline
    B ---|"parameters"| C1
    B --- C2
    B --- C3
    B --- D1
    B --- D2
    B --- D3
    B --- D4
    B --- E1
    B --- E2
    B --- E3
    B --- E4
    B --- F1
    B --- F2
    B --- F3
    B --- F4

    %% Pipeline sequence: Preprocessing to Model Architecture to Training & Inference to Evaluation
    C1 -->|"cropped_faces"| D1
    C2 --> D2
    C3 --> D3
    C4 --> D1
    C5 --> D1

    D1 -->|"trained_model"| E1
    D2 --> E1
    D3 --> E1
    D4 --> E1

    E1 -->|"inference_results"| F1
    E1 --> F2
    E1 --> F3
    E4 --> F4

    %% External integration with face_alignment
    C6 ---|"used_by"| C1

    %% Click Events
    click A "https://github.com/jinghuizhou/awesome_face_antispoofing/tree/master/data/"
    click B "https://github.com/jinghuizhou/awesome_face_antispoofing/blob/master/config.py"
    click C1 "https://github.com/jinghuizhou/awesome_face_antispoofing/blob/master/detlandmark/detlandmark.py"
    click C2 "https://github.com/jinghuizhou/awesome_face_antispoofing/blob/master/detlandmark/crop.py"
    click C3 "https://github.com/jinghuizhou/awesome_face_antispoofing/blob/master/detlandmark/detlandmark_imgs.py"
    click C4 "https://github.com/jinghuizhou/awesome_face_antispoofing/tree/master/detlandmark/inference_images/attack"
    click C5 "https://github.com/jinghuizhou/awesome_face_antispoofing/tree/master/detlandmark/inference_images/genuine"
    click D1 "https://github.com/jinghuizhou/awesome_face_antispoofing/blob/master/models/detnet.py"
    click D2 "https://github.com/jinghuizhou/awesome_face_antispoofing/blob/master/models/nasnet.py"
    click D3 "https://github.com/jinghuizhou/awesome_face_antispoofing/blob/master/models/xception.py"
    click D4 "https://github.com/jinghuizhou/awesome_face_antispoofing/blob/master/models/BasicModule.py"
    click E1 "https://github.com/jinghuizhou/awesome_face_antispoofing/blob/master/main.py"
    click E2 "https://github.com/jinghuizhou/awesome_face_antispoofing/blob/master/make.py"
    click E3 "https://github.com/jinghuizhou/awesome_face_antispoofing/tree/master/Makefile"
    click E4 "https://github.com/jinghuizhou/awesome_face_antispoofing/blob/master/inference.py"
    click F1 "https://github.com/jinghuizhou/awesome_face_antispoofing/blob/master/loss.py"
    click F2 "https://github.com/jinghuizhou/awesome_face_antispoofing/blob/master/roc.py"
    click F3 "https://github.com/jinghuizhou/awesome_face_antispoofing/blob/master/utils/Visualizer.py"
    click F4 "https://github.com/jinghuizhou/awesome_face_antispoofing/blob/master/vis_cropface.py"

    %% Styles
    classDef data fill:#AED6F1,stroke:#1B4F72,stroke-width:2px;
    classDef config fill:#A9DFBF,stroke:#145A32,stroke-width:2px;
    classDef preprocessing fill:#F9E79F,stroke:#B7950B,stroke-width:2px;
    classDef model fill:#F5B7B1,stroke:#922B21,stroke-width:2px;
    classDef training fill:#D2B4DE,stroke:#6C3483,stroke-width:2px;
    classDef evaluation fill:#FAD7A0,stroke:#D35400,stroke-width:2px;
    classDef external fill:#D5F5E3,stroke:#1E8449,stroke-width:2px;
```
