# ao-lee/vgg-face-fine-tune architecture

> Architecture diagram of the GitHub repository ao-lee/vgg-face-fine-tune, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ao-lee/vgg-face-fine-tune
- Repository: https://github.com/ao-lee/vgg-face-fine-tune

## Overview

##### Project Type and Purpose
- This is a standalone machine-learning pipeline for face detection, alignment, feature-extraction (via VGGFace), verification, and fine-tuning on custom datasets.
- Key features:
- Face detection & alignment (UtilsAlign)
- Feature extraction & triplet-loss training (vggface.py, train.py)
- Verification & threshold generation (TestCases)
- Custom dataset support via data loaders (UtilsData)

##### File Structure
Top-level files:
- cfg.py – global configuration (model paths, hyperparameters)
- data.py, utils.py – general utilities
- vggface.py – VGG-16–based model definition & embedding extractor
- train.py – training script (triplet loss)
- TestCases/ – end-to-end integration tests for detection, alignment, verification
- UtilsAlign/ – submodule for face detection, alignment, landmarking
– base/ (cascade nets)
– bbox.py, landmarks.py, database.py, common.py
- UtilsData/ – data pipeline submodule
– dataloader.py, dataset.py, sampler.py

##### README for Insights
- Confirms use of VGG-16 pre-trained on 2,622 identities, fine-tuned with triplet loss.
- Outlines workflows: detection→alignment, verification on general/single pairs, training.
- External dependencies: TensorFlow, Keras, tqdm.

##### Main Components & Interactions

A. Dataset Sources
- Raw Image Repositories (e.g., LFW, ARFace, CAS-PEAL)
- Aligned Image Store (output of alignment pipeline)

B. Preprocessing Pipeline (UtilsAlign)
- Face Detector (base/detect.py + det1/2/3.npy cascades)
- Landmark Predictor (landmarks.py)
- Alignment Database Manager (database.py)

C. Data Loading Layer (UtilsData)
- Dataset Classes (dataset.py)
- Samplers (sampler.py)
- Dataloader (dataloader.py)

D. Core Model & Training
- VGGFace Model Definition (vggface.py)
- Triplet Loss Module (in train.py)
- Configuration (cfg.py)
- Training Script (train.py)

E. Verification & Threshold Generation
- Embedding Extraction (reuse vggface.py)
- Pairwise Distance Computation
- Threshold Finder (test_best_threshold_generation.py)
- Verification Tests (TestCases/test_verification*.py)

F. External Components
- Pre-trained VGGFace weights (download link managed via cfg.py)
- Keras/TensorFlow Runtime
- File System & Storage

##### Relationships and Data Flow
- Configuration flows into Preprocessing, Data Loader, and Training scripts
- External weight download feeds into Core Model

##### Architectural Patterns & Principles
- Modular separation:
- UtilsAlign for all preprocessing
- UtilsData for data handling
- vggface.py + train.py for model logic
- Single-responsibility: each module handles one stage
- Test-driven validation: TestCases cover alignment, detection, verification
- Pluggable datasets: reader classes in data.py + LFWReader usage in train.py

##### Technologies & Frameworks
- Python 3 (Anaconda)
- TensorFlow + Keras
- NumPy (.npy detector files)
- tqdm for progress reporting
- Standard file I/O for dataset management

## Diagram (Mermaid)

```mermaid
graph TB

  subgraph "Dataset Sources"
    RawImages["Raw Image Repositories"]:::external
    AlignedStore["Aligned Image Store"]:::external
  end

  subgraph "UtilsAlign (Preprocessing)"
    FaceDetector["Face Detector"]:::preprocessing
    LandmarkPredictor["Landmark Predictor"]:::preprocessing
    BBoxAlign["Bounding Box & Alignment"]:::preprocessing
    AlignDB["Alignment Database Manager"]:::preprocessing
  end

  subgraph "UtilsData (Data Loading)"
    DatasetClasses["Dataset Classes"]:::data
    Sampler["Samplers"]:::data
    Dataloader["Dataloader"]:::data
  end

  subgraph "Core Model & Training"
    Config["Configuration (cfg.py)"]:::model
    VGGFace["VGGFace Model Definition"]:::model
    Triplet["Triplet Loss Module"]:::model
    TrainScript["Training Script"]:::model
  end

  subgraph "Verification & Threshold"
    EmbeddingExt["Embedding Extraction"]:::model
    Pairwise["Pairwise Distance Computation"]:::model
    Threshold["Threshold Finder"]:::model
    VerTests["Verification Tests"]:::testing
  end

  subgraph "Test Cases"
    DetTest1["Test Detection"]:::testing
    AlignDBTest["Test Align Database"]:::testing
    VerGenTest["Threshold Generation Test"]:::testing
    VerGenDataTest["General Verification Test"]:::testing
    VerSingleTest["Single Pair Verification Test"]:::testing
  end

  subgraph "External Components"
    Weights["Pre-trained VGGFace Weights"]:::external
    Runtime["Keras/TensorFlow Runtime"]:::external
    Storage["File System & Storage"]:::external
  end

  RawImages --> FaceDetector
  FaceDetector --> LandmarkPredictor
  LandmarkPredictor --> BBoxAlign
  BBoxAlign --> AlignDB
  AlignDB --> AlignedStore

  AlignedStore --> DatasetClasses
  DatasetClasses --> Sampler
  Sampler --> Dataloader
  Dataloader --> TrainScript

  Config --> TrainScript
  VGGFace --> TrainScript
  TrainScript --> Triplet
  TrainScript --> EmbeddingExt

  EmbeddingExt --> Pairwise
  Pairwise --> Threshold
  Threshold --> VerTests

  AlignDB --> DetTest1
  AlignDB --> AlignDBTest
  Threshold --> VerGenTest
  EmbeddingExt --> VerGenDataTest
  EmbeddingExt --> VerSingleTest

  Weights --> VGGFace
  Runtime --> TrainScript
  Storage --> RawImages
  Storage --> AlignedStore

  click FaceDetector "https://github.com/ao-lee/vgg-face-fine-tune/blob/master/UtilsAlign/base/detect.py"
  click LandmarkPredictor "https://github.com/ao-lee/vgg-face-fine-tune/blob/master/UtilsAlign/landmarks.py"
  click BBoxAlign "https://github.com/ao-lee/vgg-face-fine-tune/blob/master/UtilsAlign/bbox.py"
  click AlignDB "https://github.com/ao-lee/vgg-face-fine-tune/blob/master/UtilsAlign/database.py"
  click DatasetClasses "https://github.com/ao-lee/vgg-face-fine-tune/blob/master/UtilsData/dataset.py"
  click Sampler "https://github.com/ao-lee/vgg-face-fine-tune/blob/master/UtilsData/sampler.py"
  click Dataloader "https://github.com/ao-lee/vgg-face-fine-tune/blob/master/UtilsData/dataloader.py"
  click VGGFace "https://github.com/ao-lee/vgg-face-fine-tune/blob/master/vggface.py"
  click Config "https://github.com/ao-lee/vgg-face-fine-tune/blob/master/cfg.py"
  click Triplet "https://github.com/ao-lee/vgg-face-fine-tune/blob/master/train.py"
  click TrainScript "https://github.com/ao-lee/vgg-face-fine-tune/blob/master/train.py"
  click DetTest1 "https://github.com/ao-lee/vgg-face-fine-tune/blob/master/TestCases/test_detection.py"
  click AlignDBTest "https://github.com/ao-lee/vgg-face-fine-tune/blob/master/TestCases/test_align_database.py"
  click VerGenTest "https://github.com/ao-lee/vgg-face-fine-tune/blob/master/TestCases/test_best_threshold_generation.py"
  click VerGenDataTest "https://github.com/ao-lee/vgg-face-fine-tune/blob/master/TestCases/test_verification_on_general_dataset.py"
  click VerSingleTest "https://github.com/ao-lee/vgg-face-fine-tune/blob/master/TestCases/test_verification_on_single_pair.py"

  classDef preprocessing fill:#B3CDE3,stroke:#6497B1
  classDef data fill:#C7E9B4,stroke:#7FC97F
  classDef model fill:#FECF6E,stroke:#FDC086
  classDef testing fill:#DECBE4,stroke:#C994C7
  classDef external fill:#F0F0F0,stroke:#D9D9D9
```
