# linzaer/ultra-light-fast-generic-face-detector-1mb architecture

> Architecture diagram of the GitHub repository linzaer/ultra-light-fast-generic-face-detector-1mb, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-15). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/linzaer/ultra-light-fast-generic-face-detector-1mb
- Repository: https://github.com/linzaer/ultra-light-fast-generic-face-detector-1mb

## Overview

##### Project Type & Purpose
- This is a machine-learning framework and toolkit for ultra-lightweight face detection. It combines:
- A core PyTorch-based training and model definition pipeline (vision package, train.py)
- A data-preparation stage (VOC conversion of WIDER FACE)
- Export/conversion pipelines to multiple inference frameworks (ONNX, Caffe, MNN, NCNN, TensorFlow, TFLite, Paddle)
- Inference and evaluation code in C++ and Python for each backend

##### High-Level File-Structure Analysis
- Root scripts: train.py, train-version-*.sh, detect_imgs.py, convert_to_onnx.py, cal_flops.py, etc.
- vision/: PyTorch model definitions (mb_tiny, mb_tiny_RFB, SSD head, losses, preprocessing)
- data/: VOC-format dataset generation scripts
- models/: converted weights (ONNX, PyTorch .pth) & labels
- Framework directories (each containing conversion code, backend C++/Python inference, sample main.cpp or .py):
– caffe/onnx2caffe + ultra_face_caffe_inference.py + prototxt/.caffemodel
– MNN/ (C++), MNN/python/ (Python) + .mnn models
– ncnn/ + .param/.bin + C++ inference
– tf/ + TensorFlow saved_model + conversion scripts
– tflite/ + TFLiteFaceDetector.py + .tflite models
– paddle/ + Paddle training & inference modules
– opencv_dnn/ + cv_dnn_ultraface.cpp
- widerface_evaluate/: evaluation scripts

##### Key Architectural Patterns
- Pipeline architecture: Data → Training → Model Export → Framework-specific Converters → Inference Runtimes → Evaluation
- Plugin-like backends: each inference framework lives in its own directory, implements a common inference interface
- Artifacts as first-class citizens: model files (.pth, .onnx, .mnn, .param/.bin, .tflite) flow between steps

A. Data Preparation
– Input: Raw WIDER FACE dataset
– Script: data/wider_face_2_voc_add_landmark.py → VOC dataset
B. Model Definition & Training
– vision/nn/… + train.py + train-version-*.sh
– Output: PyTorch .pth models (version-slim, version-RFB)
C. ONNX Export
– convert_to_onnx.py → model.onnx
D. Conversion Pipelines (for each backend)
– ONNX → Caffe (onnx2caffe) → .prototxt/.caffemodel
– ONNX → MNN (MNN/src + converter) → .mnn
– ONNX → NCNN (ncnn tools) → .param/.bin
– ONNX → TensorFlow (tf/convert_tensorflow.py) → SavedModel
– ONNX → TFLite (tflite converter) → .tflite
– PyTorch → Paddle (paddle/train.py & paddle/vision)
E. Inference & Demo Applications
– Python demos: detect_imgs_onnx.py, run_video_face_detect.py, MNN/python/ultraface_py_mnn.py, etc.
– C++ demos: MNN/src/main.cpp, ncnn/src/main.cpp, opencv_dnn/cv_dnn_ultraface.cpp
F. Evaluation
– widerface_evaluate/evaluation_on_widerface.py → accuracy metrics

##### Diagramming Details
- Diamonds or parallelograms for scripts (data prep, conversion tools)
- Layer Separation
- Detail Level
- Entry points: main.cpp or .py demo scripts

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Data Preparation
    DataPrep[/ "data/wider_face_2_voc_add_landmark.py" /]:::script
    VOCData[(VOC Dataset)]:::artifact

    DataPrep -->|generates| VOCData

    %% Training Layer
    subgraph "Training Layer"
        direction TB
        VisionModule["vision/ (model definitions)"]:::module
        TrainPy["train.py"]:::script
        TrainSlim["train-version-slim.sh"]:::script
        TrainRFB["train-version-RFB.sh"]:::script
        PTModel[(PyTorch .pth models)]:::artifact
    end

    VOCData --> VisionModule
    VOCData --> TrainPy
    VOCData --> TrainSlim
    VOCData --> TrainRFB
    VisionModule --> PTModel
    TrainPy --> PTModel
    TrainSlim --> PTModel
    TrainRFB --> PTModel

    %% ONNX Export
    OnnxExport["convert_to_onnx.py"]:::script
    OnnxModel[(ONNX .onnx)]:::artifact

    PTModel -->|export via convert_to_onnx.py| OnnxExport
    OnnxExport --> OnnxModel

    %% Conversion Layer
    subgraph "Conversion Layer"
        direction TB

        subgraph Caffe
            direction TB
            ONNX2Caffe["onnx2caffe/"]:::module
            ConvertCaffe["convertCaffe.py"]:::script
            MyCaffe["MyCaffe.py"]:::script
            CaffeModel[(.prototxt/.caffemodel)]:::artifact
        end

        subgraph MNN
            direction TB
            MNNSrc["MNN/src/"]:::module
            MNNModel[(.mnn models)]:::artifact
            MNNPyDemo["ultraface_py_mnn.py"]:::script
        end

        subgraph NCNN
            direction TB
            NCNNSrc["ncnn/src/"]:::module
            NCNNModel[(.param/.bin)]:::artifact
        end

        subgraph TensorFlow
            direction TB
            TFConvert["convert_tensorflow.py"]:::script
            TFBackend["tf/backend/"]:::module
            TFModel[(SavedModel)]:::artifact
        end

        subgraph TFLite
            direction TB
            TFLiteScript["TFLiteFaceDetector.py"]:::script
            TFLiteTest["inference_test.py"]:::script
            TFLiteModel[(.tflite models)]:::artifact
        end

        subgraph Paddle
            direction TB
            PaddleTrain["paddle/train.py"]:::script
            PaddleSlim["train-version-slim.sh"]:::script
            PaddleRFB["train-version-RFB.sh"]:::script
            PaddleVision["paddle/vision/"]:::module
            PaddleData["paddle/data/"]:::module
        end

    end

    %% Connections to Conversion
    OnnxModel --> ONNX2Caffe
    ONNX2Caffe --> ConvertCaffe --> CaffeModel
    ONNX2Caffe --> MyCaffe

    OnnxModel --> MNNSrc
    MNNSrc --> MNNModel
    MNNModel --> MNNPyDemo

    OnnxModel --> NCNNSrc
    NCNNSrc --> NCNNModel

    OnnxModel --> TFConvert
    TFConvert --> TFBackend --> TFModel

    OnnxModel --> TFLiteScript
    TFLiteScript --> TFLiteModel
    TFLiteScript --> TFLiteTest

    PTModel --> PaddleTrain
    PTModel --> PaddleSlim
    PTModel --> PaddleRFB
    PaddleTrain --> PaddleVision
    PaddleVision --> PaddleData

    %% Inference Layer
    subgraph "Inference Layer"
        direction TB
        DemoPy1["detect_imgs.py"]:::script
        DemoPy2["detect_imgs_onnx.py"]:::script
        DemoPy3["run_video_face_detect.py"]:::script
        DemoPy4["run_video_face_detect_onnx.py"]:::script
        MNNMain["MNN/src/main.cpp"]:::script
        NCNNMain["ncnn/src/main.cpp"]:::script
        OpenCVNN["opencv_dnn/cv_dnn_ultraface.cpp"]:::script
    end

    CaffeModel --> DemoPy2
    MNNModel --> DemoPy2
    NCNNModel --> DemoPy2
    TFModel --> DemoPy2
    TFLiteModel --> DemoPy2
    PaddleVision --> DemoPy2

    DemoPy1 --> DemoPy3
    DemoPy2 --> DemoPy4

    MNNMain --> DemoPy3
    NCNNMain --> DemoPy3
    OpenCVNN --> DemoPy3

    %% Evaluation Layer
    EvalScript["evaluation_on_widerface.py"]:::script
    subgraph "Evaluation Layer"
        EvalScript
    end

    DemoPy3 --> EvalScript
    DemoPy4 --> EvalScript

    %% Click Events
    click DataPrep "https://github.com/linzaer/ultra-light-fast-generic-face-detector-1mb/blob/master/data/wider_face_2_voc_add_landmark.py"
    click VisionModule "https://github.com/linzaer/ultra-light-fast-generic-face-detector-1mb/tree/master/vision/"
    click TrainPy "https://github.com/linzaer/ultra-light-fast-generic-face-detector-1mb/blob/master/train.py"
    click TrainSlim "https://github.com/linzaer/ultra-light-fast-generic-face-detector-1mb/blob/master/train-version-slim.sh"
    click TrainRFB "https://github.com/linzaer/ultra-light-fast-generic-face-detector-1mb/blob/master/train-version-RFB.sh"
    click OnnxExport "https://github.com/linzaer/ultra-light-fast-generic-face-detector-1mb/blob/master/convert_to_onnx.py"
    click ONNX2Caffe "https://github.com/linzaer/ultra-light-fast-generic-face-detector-1mb/tree/master/caffe/onnx2caffe/"
    click ConvertCaffe "https://github.com/linzaer/ultra-light-fast-generic-face-detector-1mb/blob/master/caffe/convertCaffe.py"
    click MyCaffe "https://github.com/linzaer/ultra-light-fast-generic-face-detector-1mb/blob/master/caffe/MyCaffe.py"
    click MNNSrc "https://github.com/linzaer/ultra-light-fast-generic-face-detector-1mb/tree/master/MNN/src/"
    click MNNPyDemo "https://github.com/linzaer/ultra-light-fast-generic-face-detector-1mb/blob/master/MNN/python/ultraface_py_mnn.py"
    click NCNNSrc "https://github.com/linzaer/ultra-light-fast-generic-face-detector-1mb/tree/master/ncnn/src/"
    click TFConvert "https://github.com/linzaer/ultra-light-fast-generic-face-detector-1mb/blob/master/tf/convert_tensorflow.py"
    click PaddleTrain "https://github.com/linzaer/ultra-light-fast-generic-face-detector-1mb/blob/master/paddle/train.py"
    click PaddleSlim "https://github.com/linzaer/ultra-light-fast-generic-face-detector-1mb/blob/master/paddle/train-version-slim.sh"
    click PaddleRFB "https://github.com/linzaer/ultra-light-fast-generic-face-detector-1mb/blob/master/paddle/train-version-RFB.sh"
    click PaddleVision "https://github.com/linzaer/ultra-light-fast-generic-face-detector-1mb/tree/master/paddle/vision/"
    click DemoPy1 "https://github.com/linzaer/ultra-light-fast-generic-face-detector-1mb/blob/master/detect_imgs.py"
    click DemoPy2 "https://github.com/linzaer/ultra-light-fast-generic-face-detector-1mb/blob/master/detect_imgs_onnx.py"
    click DemoPy3 "https://github.com/linzaer/ultra-light-fast-generic-face-detector-1mb/blob/master/run_video_face_detect.py"
    click DemoPy4 "https://github.com/linzaer/ultra-light-fast-generic-face-detector-1mb/blob/master/run_video_face_detect_onnx.py"
    click MNNMain "https://github.com/linzaer/ultra-light-fast-generic-face-detector-1mb/blob/master/MNN/src/main.cpp"
    click NCNNMain "https://github.com/linzaer/ultra-light-fast-generic-face-detector-1mb/blob/master/ncnn/src/main.cpp"
    click OpenCVNN "https://github.com/linzaer/ultra-light-fast-generic-face-detector-1mb/blob/master/opencv_dnn/cv_dnn_ultraface.cpp"
    click EvalScript "https://github.com/linzaer/ultra-light-fast-generic-face-detector-1mb/blob/master/widerface_evaluate/evaluation_on_widerface.py"

    %% Styles
    classDef script fill:#f9f,stroke:#333,stroke-width:1px,shape:parallelogram
    classDef module fill:#bbf,stroke:#333,stroke-width:1px
    classDef artifact fill:#bfb,stroke:#333,stroke-width:1px,shape:cylinder
```
