# nihui/ncnn-assets architecture

> Architecture diagram of the GitHub repository nihui/ncnn-assets, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-08-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/nihui/ncnn-assets
- Repository: https://github.com/nihui/ncnn-assets

## Overview

##### Project Type and Purpose
- This repository is an open-source asset collection for the NCNN inference framework.
- It doesn’t provide a conventional client/server or GUI application. Instead it houses:
- Pretrained NCNN model files (bin/param pairs) in the models folder
- Versioned snapshots (folders 20180413, 20180626, 20181217)
- A conversion pipeline (pnnx tool)
- QEMU patches for target‐specific CPU extensions
- A helper script (split_bin.py) for splitting large .bin files

##### File Structure Analysis
- Top level:
- Version folders (20180413, 20180626, 20181217): historical model snapshots
- README.md: project description (“some assets about ncnn”)
- models/: canonical NCNN param & binary files for object detection, OCR, segmentation, etc.
- pnnx/: source code for the NCNN conversion tool (converts PyTorch to NCNN)
- qemu-patches/: patch files to enable various CPU instruction set bits in QEMU’s Linux‐user mode
- split_bin.py: Python script to split oversized NCNN .bin files into chunks
- Patterns:
- models/ holds paired {*.ncnn.param, *.ncnn.bin} files
- Some models are archived/split (e.g., .part01, .z01, .zip) for version control limits

##### Key Components
a. Asset Repository (Git)
- Stores all version folders, models/, pnnx/, qemu-patches/, split_bin.py
b. Model Conversion Pipeline
- pnnx tool (input: PyTorch model) → output: NCNN param/bin files → placed into models/
c. Binary Splitting Utility
- split_bin.py reads large .bin → writes multipart .part## files
d. Patch Management Subsystem
- qemu-patches/ holds .patch files applied to QEMU source → used to build custom QEMU binaries supporting extra ISA bits

##### Relationships & Data Flow
1. Author checks out the repository
2. To add a new model:
- Feed a PyTorch model into pnnx → produces .ncnn.param + .ncnn.bin
- Optionally run split_bin.py on large .bin → create part files
- Commit outputs to models/ (and update version folder if needed)
3. To build a patched QEMU:
- Apply patches from qemu-patches/ to QEMU source → compile custom QEMU for NCNN tests on specialized CPUs

##### Architectural Patterns & Principles
- Clear separation of concerns:
- Conversion logic (pnnx/)
- Asset storage (models/)
- Version history (timestamped folders)
- Build utilities (split_bin.py, qemu-patches/)
- Lightweight, file‐centric modularity (no centralized server component)

##### Technologies & Frameworks
- NCNN inference library (C++)
- pnnx (C++/Python glue)
- Python (split_bin.py)
- Git (version control)
- QEMU (patched C code)

## Diagram (Mermaid)

```mermaid
flowchart TD
    GitRepo["Root Directory (Git Repo)"]:::data
    Developer["Developer Workstation"]:::external

    subgraph "Conversion Pipeline"
        PNNX["pnnx/ Conversion Tool"]:::code
    end

    subgraph "Asset Storage"
        Models["models/ Directory"]:::data
    end

    Split["split_bin.py Utility"]:::code

    subgraph "Patch Management"
        QP["qemu-patches/"]:::utility
        QBuild["Custom QEMU Binary"]:::utility
    end

    GitRepo -->|clone| Developer
    Developer -->|"convert PyTorch model"| PNNX
    PNNX -->|".ncnn.param & .ncnn.bin"| Models
    Models -->|"optional split"| Split
    Split -->|"multipart bins"| Models
    Developer -->|"apply patches"| QP
    QP -->|"apply & build"| QBuild

    click GitRepo "https://github.com/nihui/ncnn-assets/blob/master/."
    click PNNX "https://github.com/nihui/ncnn-assets/tree/master/pnnx/"
    click Models "https://github.com/nihui/ncnn-assets/tree/master/models/"
    click Split "https://github.com/nihui/ncnn-assets/blob/master/split_bin.py"
    click QP "https://github.com/nihui/ncnn-assets/tree/master/qemu-patches/"

    classDef code fill:#bfdbfe,stroke:#1e40af,color:#1e40af;
    classDef data fill:#bbf7d0,stroke:#166534,color:#166534;
    classDef utility fill:#fed7aa,stroke:#c2410c,color:#c2410c;
    classDef external fill:#e5e7eb,stroke:#6b7280,color:#374151;
```
