How hamadya/ghostfacenets works
Project Type and Purpose
• GhostFaceNets is a research‐oriented, full-Python deep‐learning codebase for lightweight face recognition models (GhostFaceNetV1/V2) built on TensorFlow/Keras. It provides end-to-end functionality: data preparation, model definition, training with flexible schedulers and callbacks, checkpointing, and evaluation on standard face-recognition benchmarks (LFW, IJB, MegaFace).
Main Components
A. Data & Preprocessing
• Datasets directory (datasets/): holds raw .bin files and extracted image folders for MS1MV2/MS1MV3, LFW, CFP-FP, AgeDB-30.
• prepare_data.py: converts MXNet .bin files to folder structure and reformats evaluation bins.
• augment.py: implements RandAugment/AutoAug transforms.
• data.py / data_distiller.py / data_drop_top_k.py: build tf.data.Dataset pipelines, support Triplet data, partial-FC splitting, sub-center ArcFace.
B. Model Definition
• backbones/ghost_model.py, ghostv2.py: core GhostNetV1/V2 architectures (copied & modified from keras_insightface).
• GhostFaceNets.py: wraps backbones, exposes buildin_models(), add_l2_regularizer, replace_ReLU_with_PReLU.
• models.py: utility to assemble backbone + embedding + output layer (GDC), and to print available models.
C. Training Pipeline
• train.py (Train class): orchestrates training. Takes data_path, eval_paths, basic_model/model, learning-rate schedule, batch size, callbacks, and implements:
– build model (basic_model → add bottleneck → compile)
– fit() with tf.data.Dataset, scheduler list of dicts (loss, optimizer, epochs)
• losses.py: ArcFace, CosFace, Subcenter ArcFace loss functions.
• myCallbacks.py: custom Keras callbacks (checkpoint saving, LR adjustment, history logging, “gently stop”).
• checkpoints/: stores model.h5 per epoch and best basic_model.
D. Evaluation Modules
• evals.py: Keras callback to evaluate .bin files at end of epoch or batch.
• IJB_evals.py: command-line tool to evaluate on IJB-B/C datasets, generate embeddings, run protocols.
• eval_folder.py: evaluate on arbitrary folder format, also dump new .bin files.
• MegaFace/: scripts & notebooks (gen_megaface*, run.sh) to evaluate on MegaFace, handle noise removal, OpenCV2.4 dependency.
E. Notebooks & Utilities
• .ipynb files: Flops.ipynb, evaluation.ipynb, training_scripts.ipynb/training_scripts_with_Bias.ipynb – illustrate training/evaluation workflows interactively.
• plot_parameters.py: generate publication figures from saved history.
• video_test.py: demo real-time face recognition on video streams.
F. External Dependencies
• TensorFlow 2.8+, Keras 2.8+, keras_cv_attention_models, sklearn, pandas, glob2, scikit-image, tqdm, OpenCV2.4 (for MegaFace devkit), TensorFlow-Addons (optional optimizers).
Relationships & Data Flow
[ Data Sources ]
↓ prepare_data.py
[ Folder / Bin Inputs ]
↓ data.py + augment.py → tf.data.Dataset
↘
[ Train Pipeline ] ←─ GhostFaceNets.buildin_models + models.add_l2_regularizer
↙ ↓ compile & fit (scheduler, losses, optimizers)
[ Callbacks ] → checkpoint save to /checkpoints & history.json
↓
[ Saved Models ]
↓ evals.py / eval_folder.py / IJB_evals.py / MegaFace/run.sh
[ Evaluation Results & Plots ]
Architectural Patterns & Principles
• Modular separation: data ingestion, model definition, training engine, evaluation engine.
• Callback pattern: Keras callbacks for extensibility (evaluation hooks, checkpointing, LR scheduling).
• Scheduler pattern: list of training stages allowing dynamic switching of loss functions and optimizers.
• OOP for Train class: encapsulates state (datasets, model, schedulers, callbacks).
• Reusability: backbone definitions decoupled from output layers, added via utility APIs.
Final Checklist
• Annotations of key technologies (TensorFlow/Keras, OpenCV, Python).