How kprokofi/light-weight-face-anti-spoofing works
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