# kprokofi/light-weight-face-anti-spoofing architecture

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

- Interactive diagram: https://gitdiagram.com/kprokofi/light-weight-face-anti-spoofing
- Repository: https://github.com/kprokofi/light-weight-face-anti-spoofing

## Overview

##### Project Type and Purpose
- This is a specialized machine-learning pipeline for face anti-spoofing using RGB data. It’s not a full-stack web app but a modular Python project that covers the full ML life-cycle: data ingestion & preprocessing, model training, evaluation, format conversion, and a live demo.

##### File Structure Analysis
Top-level directories and files:
- configs/ – all model and training configurations (config.py, config_small, config_large_075, etc.)
- datasets/ – dataset reader implementations for CelebA-Spoof, LCC-FASD, CASIA-SURF, plus hooks for external readers
- demo/ & demo_tools/ – demo application and helper wrappers for OpenVINO and video capture
- losses/ – implementations of AM-Softmax and Soft-Triple losses
- models/ – MobileNetV2/V3 architectures and model utilities
- prepare_*.py scripts – dataset preparation for CelebA and LCC-FASD
- train.py & trainer.py – training entrypoint and orchestrator
- eval_protocol.py – evaluation pipeline with metrics logging
- convert_model.py & conversion_checker.py – ONNX export and OpenVINO conversion validation
- compute_mean_std.py, utils.py – general utilities
- requirements.txt, init_venv.sh, run_checks.sh – environment setup, CI checks

##### README Insights
- Pipeline supports multiple datasets with customizable readers.
- Configurable training (dataset choice, multitask, schedulers, augmentation, loss type, model hyperparams) via Python config files.
- Evaluation and metric logging.
- Export model to ONNX and convert to OpenVINO IR, with a post-conversion checker.
- Demo that runs on webcam or video using OpenVINO face-detector plus the anti-spoof model.

a. Main Components:
1. Data Layer
- Raw datasets (CelebA-Spoof, LCC-FASD, CASIA, external)
- Preparation scripts (prepare_celeba_json.py, prepare_lcc_fasd.py)
- Dataset readers in datasets/
2. Configuration Manager
- configs/config.py and variants
- Injects dataset paths, model hyperparams, loss/aug settings, device, etc.
3. Model Layer
- models/ (MobileNetV2/V3 definitions)
- losses/ (AM-Softmax, Soft-Triple)
- model_tools.py for weight loading, transfer learning
4. Training Engine
- train.py (CLI) → trainer.py orchestrates data loaders, forward/backward pass, checkpointing, TensorBoard logs
- utils.py for common helper functions
5. Evaluation Module
- eval_protocol.py applies trained checkpoints to validation/test splits, computes AUC/EER/APCER/BPCER/ACER, logs metrics
6. Conversion Module
- convert_model.py exports to ONNX
- mo_onnx.py (external OpenVINO Model Optimizer)
- conversion_checker.py runs L1 diff between PyTorch vs OpenVINO outputs
7. Demo Application
- demo/demo.py: loads face-detector (OpenVINO XML) and anti-spoof model (ONNX or PyTorch), runs real-time inference
- demo_tools/: wrappers for IECore, video capture, result overlays
8. Environment & CI
- init_venv.sh, requirements.txt for Python + OpenVINO
- run_checks.sh, .travis.yml, pylint.rc for static analysis & CI

b. Relationships & Data Flow
2. Config Manager → Training Engine (drives hyperparams & paths)
3. Training Engine ↔ Model Layer (forward/backward)
4. Trained Model Checkpoints → Evaluation Module → Metrics Output
5. Trained Checkpoints → Conversion Module → ONNX → Model Optimizer → OpenVINO IR
6. Demo Application ← (OpenVINO Face Detector, Converted IR) & optionally ← PyTorch Model
7. Shared Utility Modules (utils.py, model_tools.py, losses/) used throughout

c. Architectural Patterns & Principles
- Layered modular design: clear separation of data, model, training, evaluation, conversion, and demo
- Configuration-driven: all pipeline behavior set via config files
- Plug-in dataset readers: easy extensibility for new data sources
- Single-process Python CLI entrypoints for each stage
- Use of standardized intermediate representation (ONNX) for portability to OpenVINO

d. Key Technologies & Frameworks
- Python 3.6+
- PyTorch (model training, checkpointing)
- OpenVINO with Model Optimizer (ONNX → IR, inference engine)
- ONNX intermediate format
- MobileNetV2/V3 architectures
- WeightedRandomSampler, augmentations (cutmix, mixup), advanced dropout, RSC

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Data Layer
    subgraph "Data Layer"
        direction TB
        CR1["CelebA-Spoof"]:::data
        CR2["LCC-FASD"]:::data
        CR3["CASIA-SURF"]:::data
        CR4["External DB"]:::data
        PrepCeleba["prepare_celeba_json.py"]:::data
        PrepLCC["prepare_lcc_fasd.py"]:::data
        DS1["celeba_spoof.py"]:::data
        DS2["lcc_fasd.py"]:::data
        DS3["casia_surf.py"]:::data
        DS4["database.py"]:::data
    end

    %% Configuration Manager
    subgraph "Configuration Manager"
        direction TB
        ConfigBase["config.py"]:::config
        ConfigSmall["config_small.py"]:::config
        ConfigSmall075["config_small_075.py"]:::config
        ConfigLarge075["config_large_075.py"]:::config
    end

    %% Model Layer
    subgraph "Model Layer"
        direction TB
        MN2["mobilenetv2.py"]:::model
        MN3["mobilenetv3.py"]:::model
        MTools["model_tools.py"]:::model
        Loss1["am_softmax.py"]:::model
        Loss2["soft_triple.py"]:::model
    end

    %% Training Engine
    subgraph "Training Engine"
        direction TB
        TrainCLI["train.py"]:::train
        Trainer["trainer.py"]:::train
        Utils["utils.py"]:::train
        MeanStd["compute_mean_std.py"]:::train
    end

    %% Checkpoints Store
    Checkpoints["Model Checkpoints"]:::data

    %% Evaluation Module
    subgraph "Evaluation Module"
        direction TB
        Eval["eval_protocol.py"]:::eval
        Metrics["Metrics Output"]:::eval
    end

    %% Conversion Module
    subgraph "Conversion & Deployment"
        direction TB
        Convert["convert_model.py"]:::convert
        Checker["conversion_checker.py"]:::convert
        ONNX["ONNX Model"]:::convert
        MO["Model Optimizer"]:::convert_tool
        IR["OpenVINO IR"]:::convert
    end

    %% Demo Application
    subgraph "Demo Application"
        direction TB
        DemoMain["demo/demo.py"]:::demo
        IETools["demo_tools/ie_tools.py"]:::demo
        Wrap["demo_tools/wrapers.py"]:::demo
        FD["OpenVINO Face Detector"]:::convert_tool
    end

    %% Environment & CI
    subgraph "Environment & CI"
        direction TB
        Venv["init_venv.sh"]:::ci
        Req["requirements.txt"]:::ci
        Checks["run_checks.sh"]:::ci
        Travis[".travis.yml"]:::ci
        Pylint["pylint.rc"]:::ci
    end

    %% Data Flow
    CR1 --> PrepCeleba --> DS1
    CR2 --> PrepLCC --> DS2
    CR3 --> DS3
    CR4 --> DS4

    DS1 --> Trainer
    DS2 --> Trainer
    DS3 --> Trainer
    DS4 --> Trainer

    %% Configuration Flow
    ConfigBase --> TrainCLI
    ConfigSmall --> TrainCLI
    ConfigSmall075 --> TrainCLI
    ConfigLarge075 --> TrainCLI

    ConfigBase --> Eval
    ConfigBase --> Convert
    ConfigBase --> DemoMain

    %% Training & Model Interaction
    TrainCLI --> Trainer
    Trainer --> MN2
    Trainer --> MN3
    Trainer --> MTools
    Trainer --> Loss1
    Trainer --> Loss2
    Trainer --> Utils
    Trainer --> MeanStd

    Trainer --> Checkpoints
    Checkpoints --> Eval
    Eval --> Metrics

    Checkpoints --> Convert
    Convert --> ONNX
    ONNX --> MO
    MO --> IR
    IR --> Checker
    Checker --> DemoMain

    FD --> DemoMain
    IR --> DemoMain
    DemoMain --> IETools
    DemoMain --> Wrap

    %% CI & Env used by all
    Venv -.-> TrainCLI
    Req -.-> TrainCLI
    Checks -.-> TrainCLI
    Travis -.-> TrainCLI
    Pylint -.-> TrainCLI

    %% Click Events
    click PrepCeleba "https://github.com/kprokofi/light-weight-face-anti-spoofing/blob/master/prepare_celeba_json.py"
    click PrepLCC "https://github.com/kprokofi/light-weight-face-anti-spoofing/blob/master/prepare_lcc_fasd.py"
    click DS1 "https://github.com/kprokofi/light-weight-face-anti-spoofing/blob/master/datasets/celeba_spoof.py"
    click DS2 "https://github.com/kprokofi/light-weight-face-anti-spoofing/blob/master/datasets/lcc_fasd.py"
    click DS3 "https://github.com/kprokofi/light-weight-face-anti-spoofing/blob/master/datasets/casia_surf.py"
    click DS4 "https://github.com/kprokofi/light-weight-face-anti-spoofing/blob/master/datasets/database.py"
    click ConfigBase "https://github.com/kprokofi/light-weight-face-anti-spoofing/blob/master/configs/config.py"
    click ConfigSmall "https://github.com/kprokofi/light-weight-face-anti-spoofing/blob/master/configs/config_small.py"
    click ConfigSmall075 "https://github.com/kprokofi/light-weight-face-anti-spoofing/blob/master/configs/config_small_075.py"
    click ConfigLarge075 "https://github.com/kprokofi/light-weight-face-anti-spoofing/blob/master/configs/config_large_075.py"
    click MN2 "https://github.com/kprokofi/light-weight-face-anti-spoofing/blob/master/models/mobilenetv2.py"
    click MN3 "https://github.com/kprokofi/light-weight-face-anti-spoofing/blob/master/models/mobilenetv3.py"
    click MTools "https://github.com/kprokofi/light-weight-face-anti-spoofing/blob/master/models/model_tools.py"
    click Loss1 "https://github.com/kprokofi/light-weight-face-anti-spoofing/blob/master/losses/am_softmax.py"
    click Loss2 "https://github.com/kprokofi/light-weight-face-anti-spoofing/blob/master/losses/soft_triple.py"
    click TrainCLI "https://github.com/kprokofi/light-weight-face-anti-spoofing/blob/master/train.py"
    click Trainer "https://github.com/kprokofi/light-weight-face-anti-spoofing/blob/master/trainer.py"
    click Utils "https://github.com/kprokofi/light-weight-face-anti-spoofing/blob/master/utils.py"
    click MeanStd "https://github.com/kprokofi/light-weight-face-anti-spoofing/blob/master/compute_mean_std.py"
    click Eval "https://github.com/kprokofi/light-weight-face-anti-spoofing/blob/master/eval_protocol.py"
    click Convert "https://github.com/kprokofi/light-weight-face-anti-spoofing/blob/master/convert_model.py"
    click Checker "https://github.com/kprokofi/light-weight-face-anti-spoofing/blob/master/conversion_checker.py"
    click DemoMain "https://github.com/kprokofi/light-weight-face-anti-spoofing/blob/master/demo/demo.py"
    click IETools "https://github.com/kprokofi/light-weight-face-anti-spoofing/blob/master/demo_tools/ie_tools.py"
    click Wrap "https://github.com/kprokofi/light-weight-face-anti-spoofing/blob/master/demo_tools/wrapers.py"
    click Venv "https://github.com/kprokofi/light-weight-face-anti-spoofing/blob/master/init_venv.sh"
    click Req "https://github.com/kprokofi/light-weight-face-anti-spoofing/blob/master/requirements.txt"
    click Checks "https://github.com/kprokofi/light-weight-face-anti-spoofing/blob/master/run_checks.sh"
    click Travis "https://github.com/kprokofi/light-weight-face-anti-spoofing/blob/master/.travis.yml"
    click Pylint "https://github.com/kprokofi/light-weight-face-anti-spoofing/blob/master/pylint.rc"

    %% Styles
    classDef data fill:#cce5ff,stroke:#004085,color:#004085
    classDef config fill:#fff3cd,stroke:#856404,color:#856404,shape:parallelogram
    classDef model fill:#d4edda,stroke:#155724,color:#155724
    classDef train fill:#d4edda,stroke:#155724,color:#155724
    classDef eval fill:#ffe5b4,stroke:#cc8400,color:#cc8400
    classDef convert fill:#e2d5f0,stroke:#5e3786,color:#5e3786
    classDef convert_tool fill:#f5d0ff,stroke:#a626a4,color:#a626a4,shape:hexagon
    classDef demo fill:#d1ecf1,stroke:#0c5460,color:#0c5460
    classDef ci fill:#f8d7da,stroke:#721c24,color:#721c24
```
