# dog-qiuqiu/yolo-fastestv2 architecture

> Architecture diagram of the GitHub repository dog-qiuqiu/yolo-fastestv2, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-19). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/dog-qiuqiu/yolo-fastestv2
- Repository: https://github.com/dog-qiuqiu/yolo-fastestv2

## Overview

1. **What this repo is**
   - This is a compact object-detection project centered on **Yolo-FastestV2 / FastestDet**.
   - The architecture is split into three clear paths: **training/evaluation in Python**, **model export**, and **embedded deployment with NCNN**.

2. **Core model boundary**
   - The detector lives under `model/` and is assembled from three parts:
     - `model/backbone/shufflenetv2.py` for the lightweight feature extractor
     - `model/fpn.py` for multi-scale feature aggregation
     - `model/detector.py` for the decoupled detection heads
   - The README says the head is separated into **obj / cls / reg** branches, so the model is not a single monolithic classifier but a staged detection pipeline.

3. **Training data contract**
   - The repo follows the **Darknet YOLO dataset format**.
   - Labels are image-aligned `.txt` files with `category cx cy w h`, and dataset splits are referenced by text files such as `train.txt` and `val.txt`.
   - Class names are stored in `data/coco.names`, which is loaded through the dataset config.

4. **Configuration layer**
   - `data/coco.data` is the main runtime configuration file.
   - It defines:
     - model metadata and input size
     - training schedule and batch settings
     - anchor parameters
     - dataset paths
     - class-name file
   - This file is the main boundary between code and experiment setup.

5. **Training flow**
   - `train.py` is the entry point for optimization.
   - It likely wires together:
     - dataset loading from `utils/datasets.py`
     - model construction from `model/`
     - detection loss from `utils/loss.py`
     - helper logic from `utils/utils.py`
   - Pretrained initialization can come from `model/backbone/backbone.pth` or a full checkpoint via `pre_weights` in the `.data` file.

6. **Loss and target assignment**
   - `utils/loss.py` and the README indicate the detection training uses **YOLOv5-style anchor matching** rather than the older YOLO/FastestDet logic.
   - The repo also mentions **different loss weights per output scale**, which implies multi-scale supervision across the FPN heads.
   - This is a key architectural boundary: target assignment and loss are decoupled from the model definition.

7. **Evaluation and single-image inference**
   - `test.py` is for ad hoc image inference, taking a data config, a trained `.pth`, and an input image.
   - `evaluation.py` computes benchmark metrics such as **COCO mAP** using the same model and dataset configuration.
   - These scripts are separate from training, which keeps inference-only logic isolated from optimization logic.

8. **Anchor generation**
   - `genanchors.py` derives anchor priors from the training set.
   - The resulting anchor list is fed back into `data/coco.data`, so anchor design is part of the experiment setup rather than hardcoded into the model.

9. **Export path for deployment**
   - `pytorch2onnx.py` converts the trained PyTorch detector into **ONNX**.
   - The README then uses `onnxsim` and NCNN tooling to produce optimized `.param` and `.bin` artifacts.
   - This makes the deployment boundary explicit: **Python training graph → ONNX interchange → NCNN runtime graph**.

10. **Embedded runtime / C++ sample**
   - `sample/ncnn/` is the deployment target, with a C++ demo in `demo.cpp` and implementation in `src/`.
   - `sample/ncnn/model/` contains the optimized NCNN artifacts used by the demo.
   - This sample is the non-Python execution boundary for low-resource inference.

11. **Pretrained and packaged artifacts**
   - `modelzoo/` stores a trained checkpoint for COCO, used for evaluation and testing.
   - `weights/` appears to be a generic output or bookkeeping directory.
   - `img/` contains demo assets/results, not part of the runtime path.

12. **External dependencies that matter**
   - The repo is built around **PyTorch** for training/inference and **NCNN** for deployment.
   - The architecture is therefore split by runtime: GPU/CPU-friendly Python experimentation on one side, and lightweight C++ inference on the other.

13. **Big-picture data flow**
   - Training path: dataset files → dataloader → ShufflenetV2/FPN/detector → loss → checkpoint.
   - Evaluation path: checkpoint + validation set → detector → mAP metrics.
   - Deployment path: checkpoint → ONNX → simplified ONNX → NCNN model files → C++ demo inference.

Main entry points: [`train.py`](https://github.com/dog-qiuqiu/yolo-fastestv2/blob/main/train.py) (Train), [`data/coco.data`](https://github.com/dog-qiuqiu/yolo-fastestv2/blob/main/data/coco.data) (coco.data), [`sample/ncnn/src/yolo-fastestv2.cpp`](https://github.com/dog-qiuqiu/yolo-fastestv2/blob/main/sample/ncnn/src/yolo-fastestv2.cpp) (NCNN src), [`sample/ncnn/model/yolo-fastestv2-opt.param`](https://github.com/dog-qiuqiu/yolo-fastestv2/blob/main/sample/ncnn/model/yolo-fastestv2-opt.param) (NCNN model)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_python["Python pipeline"]
  node_train_py["Train<br/>entrypoint<br/>[train.py]"]
  node_test_py["Test<br/>inference script<br/>[test.py]"]
  node_eval_py["Eval<br/>metrics script<br/>[evaluation.py]"]
  node_anchors_py["Anchors<br/>anchor tool<br/>[genanchors.py]"]
  node_export_py["ONNX export<br/>export script<br/>[pytorch2onnx.py]"]
  node_datasets_py["Dataset loader<br/>data pipeline<br/>[datasets.py]"]
  node_loss_py["Detection loss<br/>loss/assignment<br/>[loss.py]"]
  node_utils_py["Helpers<br/>shared utils<br/>[utils.py]"]
  node_backbone_py["ShuffleNetV2<br/>backbone<br/>[shufflenetv2.py]"]
  node_fpn_py["FPN<br/>neck<br/>[fpn.py]"]
  node_detector_py["Detector<br/>head<br/>[detector.py]"]
end

subgraph group_deploy["NCNN deploy"]
  node_ncnn_demo["NCNN demo<br/>c++ sample<br/>[demo.cpp]"]
  node_ncnn_src["NCNN src<br/>runtime impl<br/>[yolo-fastestv2.cpp]"]
  node_ncnn_hdr["NCNN API<br/>c++ header<br/>[yolo-fastestv2.h]"]
  node_ncnn_model["NCNN model<br/>optimized artifacts"]
end

subgraph group_data["Data and artifacts"]
  node_data_cfg["coco.data<br/>runtime config<br/>[coco.data]"]
  node_names_cfg["coco.names<br/>class labels<br/>[coco.names]"]
  node_coco_ckpt[("COCO ckpt<br/>pretrained checkpoint")]
  node_backbone_ckpt[("Backbone ckpt<br/>weights<br/>[backbone.pth]")]
end

node_train_py -->|"loads"| node_datasets_py
node_train_py -->|"builds"| node_backbone_py
node_train_py -->|"builds"| node_fpn_py
node_train_py -->|"builds"| node_detector_py
node_train_py -->|"optimizes with"| node_loss_py
node_train_py -.->|"uses"| node_utils_py
node_train_py -->|"reads"| node_data_cfg
node_data_cfg -->|"references"| node_names_cfg
node_data_cfg -.->|"initializes"| node_backbone_ckpt
node_anchors_py -->|"updates"| node_data_cfg
node_eval_py -->|"evaluates"| node_coco_ckpt
node_eval_py -->|"loads"| node_datasets_py
node_test_py -->|"infers"| node_coco_ckpt
node_test_py -->|"reads"| node_data_cfg
node_export_py -->|"exports"| node_coco_ckpt
node_export_py -->|"produces"| node_ncnn_model
node_ncnn_demo -->|"uses"| node_ncnn_src
node_ncnn_src -->|"includes"| node_ncnn_hdr
node_ncnn_demo -->|"loads"| node_ncnn_model
node_ncnn_src -->|"runs"| node_ncnn_model

click node_train_py "https://github.com/dog-qiuqiu/yolo-fastestv2/blob/main/train.py"
click node_test_py "https://github.com/dog-qiuqiu/yolo-fastestv2/blob/main/test.py"
click node_eval_py "https://github.com/dog-qiuqiu/yolo-fastestv2/blob/main/evaluation.py"
click node_anchors_py "https://github.com/dog-qiuqiu/yolo-fastestv2/blob/main/genanchors.py"
click node_export_py "https://github.com/dog-qiuqiu/yolo-fastestv2/blob/main/pytorch2onnx.py"
click node_datasets_py "https://github.com/dog-qiuqiu/yolo-fastestv2/blob/main/utils/datasets.py"
click node_loss_py "https://github.com/dog-qiuqiu/yolo-fastestv2/blob/main/utils/loss.py"
click node_utils_py "https://github.com/dog-qiuqiu/yolo-fastestv2/blob/main/utils/utils.py"
click node_backbone_py "https://github.com/dog-qiuqiu/yolo-fastestv2/blob/main/model/backbone/shufflenetv2.py"
click node_fpn_py "https://github.com/dog-qiuqiu/yolo-fastestv2/blob/main/model/fpn.py"
click node_detector_py "https://github.com/dog-qiuqiu/yolo-fastestv2/blob/main/model/detector.py"
click node_data_cfg "https://github.com/dog-qiuqiu/yolo-fastestv2/blob/main/data/coco.data"
click node_names_cfg "https://github.com/dog-qiuqiu/yolo-fastestv2/blob/main/data/coco.names"
click node_coco_ckpt "https://github.com/dog-qiuqiu/yolo-fastestv2/blob/main/modelzoo/coco2017-0.241078ap-model.pth"
click node_backbone_ckpt "https://github.com/dog-qiuqiu/yolo-fastestv2/blob/main/model/backbone/backbone.pth"
click node_ncnn_demo "https://github.com/dog-qiuqiu/yolo-fastestv2/blob/main/sample/ncnn/demo.cpp"
click node_ncnn_src "https://github.com/dog-qiuqiu/yolo-fastestv2/blob/main/sample/ncnn/src/yolo-fastestv2.cpp"
click node_ncnn_hdr "https://github.com/dog-qiuqiu/yolo-fastestv2/blob/main/sample/ncnn/src/include/yolo-fastestv2.h"
click node_ncnn_model "https://github.com/dog-qiuqiu/yolo-fastestv2/blob/main/sample/ncnn/model/yolo-fastestv2-opt.param"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_train_py,node_test_py,node_eval_py,node_anchors_py,node_export_py,node_datasets_py,node_loss_py,node_utils_py,node_backbone_py,node_fpn_py,node_detector_py toneBlue
class node_ncnn_demo,node_ncnn_src,node_ncnn_hdr,node_ncnn_model toneAmber
class node_data_cfg,node_names_cfg,node_coco_ckpt,node_backbone_ckpt toneMint
```

## Components

### Python pipeline

Training, evaluation, export, and model code in PyTorch.

- [Train](https://github.com/dog-qiuqiu/yolo-fastestv2/blob/main/train.py): entrypoint · Training entrypoint that builds the detector, loads data, and optimizes weights. · `train.py`
- [Test](https://github.com/dog-qiuqiu/yolo-fastestv2/blob/main/test.py): inference script · Single-image inference script for ad hoc prediction. · `test.py`
- [Eval](https://github.com/dog-qiuqiu/yolo-fastestv2/blob/main/evaluation.py): metrics script · Evaluation script for dataset metrics such as COCO mAP. · `evaluation.py`
- [Anchors](https://github.com/dog-qiuqiu/yolo-fastestv2/blob/main/genanchors.py): anchor tool · Utility that derives anchor priors from the training set. · `genanchors.py`
- [ONNX export](https://github.com/dog-qiuqiu/yolo-fastestv2/blob/main/pytorch2onnx.py): export script · Converts the PyTorch detector into ONNX for deployment. · `pytorch2onnx.py`
- [Dataset loader](https://github.com/dog-qiuqiu/yolo-fastestv2/blob/main/utils/datasets.py): data pipeline · Loads Darknet-style splits, images, and labels for training and evaluation. · `utils/datasets.py`
- [Detection loss](https://github.com/dog-qiuqiu/yolo-fastestv2/blob/main/utils/loss.py): loss/assignment · YOLOv5-style target matching and multi-scale detection loss. · `utils/loss.py`
- [Helpers](https://github.com/dog-qiuqiu/yolo-fastestv2/blob/main/utils/utils.py): shared utils · Shared training and inference helpers. · `utils/utils.py`
- [ShuffleNetV2](https://github.com/dog-qiuqiu/yolo-fastestv2/blob/main/model/backbone/shufflenetv2.py): backbone · Lightweight feature extractor used by the detector. · `model/backbone/shufflenetv2.py`
- [FPN](https://github.com/dog-qiuqiu/yolo-fastestv2/blob/main/model/fpn.py): neck · Multi-scale feature aggregation layer. · `model/fpn.py`
- [Detector](https://github.com/dog-qiuqiu/yolo-fastestv2/blob/main/model/detector.py): head · Decoupled detection heads for obj, cls, and reg prediction. · `model/detector.py`

### NCNN deploy

C++ inference sample and optimized runtime artifacts.

- [NCNN demo](https://github.com/dog-qiuqiu/yolo-fastestv2/blob/main/sample/ncnn/demo.cpp): c++ sample · Embedded inference demo that runs the exported model in NCNN. · `sample/ncnn/demo.cpp`
- [NCNN src](https://github.com/dog-qiuqiu/yolo-fastestv2/blob/main/sample/ncnn/src/yolo-fastestv2.cpp): runtime impl · C++ implementation of preprocessing, inference, and postprocessing. · `sample/ncnn/src/yolo-fastestv2.cpp`
- [NCNN API](https://github.com/dog-qiuqiu/yolo-fastestv2/blob/main/sample/ncnn/src/include/yolo-fastestv2.h): c++ header · Public interface for the NCNN demo wrapper. · `sample/ncnn/src/include/yolo-fastestv2.h`
- [NCNN model](https://github.com/dog-qiuqiu/yolo-fastestv2/blob/main/sample/ncnn/model/yolo-fastestv2-opt.param): optimized artifacts · Optimized param/bin files consumed by the embedded demo. · `sample/ncnn/model/yolo-fastestv2-opt.param`

### Data and artifacts

Configs, labels, checkpoints, and generated assets.

- [coco.data](https://github.com/dog-qiuqiu/yolo-fastestv2/blob/main/data/coco.data): runtime config · Main experiment config for model metadata, anchors, dataset paths, and training settings. · `data/coco.data`
- [coco.names](https://github.com/dog-qiuqiu/yolo-fastestv2/blob/main/data/coco.names): class labels · Class-name list loaded by the dataset and runtime config. · `data/coco.names`
- [COCO ckpt](https://github.com/dog-qiuqiu/yolo-fastestv2/blob/main/modelzoo/coco2017-0.241078ap-model.pth): pretrained checkpoint · Packaged COCO model checkpoint used for testing and evaluation. · `modelzoo/coco2017-0.241078ap-model.pth`
- [Backbone ckpt](https://github.com/dog-qiuqiu/yolo-fastestv2/blob/main/model/backbone/backbone.pth): weights · Pretrained backbone weights used for initialization. · `model/backbone/backbone.pth`

## Connections

- Train → Dataset loader: loads · Training uses the dataset loader for Darknet-style splits and labels.
- Train → ShuffleNetV2: builds · Training constructs the model backbone.
- Train → FPN: builds · Training constructs the feature pyramid neck.
- Train → Detector: builds · Training constructs the detection heads.
- Train → Detection loss: optimizes with · Loss module computes multi-scale supervision and anchor matching.
- Train → Helpers: uses · Training reuses shared helper logic.
- Train → coco.data: reads · Experiment settings and paths come from the data config.
- coco.data → coco.names: references · Config points to the class-name file.
- coco.data → Backbone ckpt: initializes · Config may point to pretrained backbone weights.
- Anchors → coco.data: updates · Generated anchors are fed back into the config.
- Eval → COCO ckpt: evaluates · Evaluation runs the packaged checkpoint.
- Eval → Dataset loader: loads · Evaluation reads validation data through the same loader boundary.
- Test → COCO ckpt: infers · Ad hoc inference runs a trained checkpoint.
- Test → coco.data: reads · Inference uses the runtime config for paths and settings.
- ONNX export → COCO ckpt: exports · ONNX export starts from a trained PyTorch checkpoint.
- ONNX export → NCNN model: produces · Exported model is simplified and converted into NCNN artifacts.
- NCNN demo → NCNN src: uses · Demo entrypoint calls into the C++ runtime implementation.
- NCNN src → NCNN API: includes · Implementation is exposed through the header interface.
- NCNN demo → NCNN model: loads · Demo consumes the optimized param/bin model files.
- NCNN src → NCNN model: runs · Runtime implementation executes the exported NCNN graph.
