# mhliao/db architecture

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

- Interactive diagram: https://gitdiagram.com/mhliao/db
- Repository: https://github.com/mhliao/db

## Overview

##### Project type and purpose
- This is an open-source scene text detection framework (DBNet and DBNet++) implemented in PyTorch. It provides data-loading, model definition, training, inference/demo, evaluation, visualization, and custom CUDA operators for deformable convolutions.

##### File structure
- Top-level scripts:
- train.py, trainer.py – orchestrate the training loop.
- demo.py, eval.py, convert_to_onnx.py – handle inference, evaluation, and model export.
- experiment.py – utility for running experiments from YAML configs.
- Core modules:
- structure/ – builds the detection model (builder.py, model.py), plus representers, visualizers, measurers for outputs.
- backbones/ – CNN backbone definitions (ResNet, MobileNetV3).
- decoders/ – heads and loss functions (segmentation detector, various loss terms).
- data/ – data loading, augmentation, processing pipelines, dataset wrappers.
- training/ – checkpointing, learning-rate schedules, optimizer & scheduler.
- Utilities and evaluation:
- concern/ – logging, monitoring, ICDAR evaluation protocols, WebCV server for live visualization.
- assets/ops/dcn/ – custom CUDA extensions for deformable conv/pool operators.
- experiments/ – YAML config files that tie together dataset paths, model settings, hyperparameters.

##### README for additional insights
- The YAML configs (“base_*.yaml” and dataset-specific overrides) define the end-to-end pipeline: data preprocessing, model architecture, training parameters, inference settings, thresholds.
- Installation instructions emphasize building the deformable convolution operator.
- Demo and eval commands illustrate the flow from input images → inference → post-processing → evaluation metrics/visual results.

##### Detail without overthinking
- Break the system into: Data, Model, Training, Inference, Evaluation, Configuration, Custom Ops
- Essential directories as components; show their interactions clearly

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Data Preparation Layer
    subgraph "Data Preparation Layer"
        direction TB
        RawData("Raw Dataset Storage"):::data
        DataModule["data/ Module"]:::data
        DataLoader("DataLoader"):::data
    end

    %% Model Definition Layer
    subgraph "Model Definition Layer"
        direction TB
        Builder["structure/builder.py"]:::model
        ModelDef["structure/model.py"]:::model
        Backbones["backbones/"]:::model
        Decoders["decoders/"]:::model
    end

    %% Custom CUDA Operators
    subgraph "Custom CUDA Operators"
        direction TB
        CustomOps["assets/ops/dcn/"]:::ops
    end

    %% Training Engine
    subgraph "Training Engine"
        direction TB
        TrainScript["train.py"]:::train
        Trainer["trainer.py"]:::train
        TrainingUtils["training/"]:::train
        Checkpoint["training/checkpoint.py"]:::train
        LR["training/learning_rate.py"]:::train
        OptSched["training/optimizer_scheduler.py"]:::train
        Saver["training/model_saver.py"]:::train
    end

    %% Configuration & Orchestration
    subgraph "Configuration & Orchestration"
        direction TB
        ExperimentScript["experiment.py"]:::config
        Experiments["experiments/"]:::config
    end

    %% Inference & Evaluation
    subgraph "Inference & Evaluation"
        direction TB
        DemoScript["demo.py"]:::infer
        EvalScript["eval.py"]:::infer
        Representers["structure/representers/"]:::infer
        Visualizers["structure/visualizers/"]:::infer
        ICDAR["concern/icdar2015_eval/"]:::infer
        WebCV["concern/webcv2/"]:::infer
    end

    %% Model Export
    ConvertONNX["convert_to_onnx.py"]:::config

    %% Connections
    RawData -->|"images & annotations"| DataModule
    DataModule -->|"batches"| DataLoader
    DataLoader -->|"Batch"| TrainScript
    ExperimentScript -->|loads configs| Experiments
    Experiments -.->|YAML configs| ExperimentScript
    ExperimentScript -->|instantiates| TrainScript
    TrainScript -->|calls| Trainer
    Trainer -->|uses| Builder
    Trainer -->|uses| ModelDef
    Trainer -->|uses| Backbones
    Trainer -->|uses| Decoders
    Builder -->|assembles| Backbones
    Builder -->|assembles| Decoders
    ModelDef -->|forward/backward| CustomOps
    Trainer -->|optimizes| Checkpoint
    Trainer -->|adjusts LR| LR
    Trainer -->|schedules| OptSched
    Trainer -->|saves model| Saver
    DemoScript -->|loads weights| ModelDef
    DemoScript -->|runs forward| Builder
    DemoScript -->|outputs| Representers
    Representers -->|to polygons| Visualizers
    EvalScript -->|loads weights| ModelDef
    EvalScript -->|outputs| Representers
    Representers -->|metrics| ICDAR
    Representers -->|live data| WebCV
    ConvertONNX -->|exports| ModelDef

    %% Click Events
    click DataModule "https://github.com/mhliao/db/tree/master/data/"
    click Builder "https://github.com/mhliao/db/blob/master/structure/builder.py"
    click ModelDef "https://github.com/mhliao/db/blob/master/structure/model.py"
    click Backbones "https://github.com/mhliao/db/tree/master/backbones/"
    click Decoders "https://github.com/mhliao/db/tree/master/decoders/"
    click CustomOps "https://github.com/mhliao/db/tree/master/assets/ops/dcn/"
    click TrainScript "https://github.com/mhliao/db/blob/master/train.py"
    click Trainer "https://github.com/mhliao/db/blob/master/trainer.py"
    click TrainingUtils "https://github.com/mhliao/db/tree/master/training/"
    click Checkpoint "https://github.com/mhliao/db/blob/master/training/checkpoint.py"
    click LR "https://github.com/mhliao/db/blob/master/training/learning_rate.py"
    click OptSched "https://github.com/mhliao/db/blob/master/training/optimizer_scheduler.py"
    click Saver "https://github.com/mhliao/db/blob/master/training/model_saver.py"
    click ExperimentScript "https://github.com/mhliao/db/blob/master/experiment.py"
    click Experiments "https://github.com/mhliao/db/tree/master/experiments/"
    click DemoScript "https://github.com/mhliao/db/blob/master/demo.py"
    click EvalScript "https://github.com/mhliao/db/blob/master/eval.py"
    click Representers "https://github.com/mhliao/db/tree/master/structure/representers/"
    click Visualizers "https://github.com/mhliao/db/tree/master/structure/visualizers/"
    click ICDAR "https://github.com/mhliao/db/tree/master/concern/icdar2015_eval/"
    click WebCV "https://github.com/mhliao/db/tree/master/concern/webcv2/"
    click ConvertONNX "https://github.com/mhliao/db/blob/master/convert_to_onnx.py"

    %% Styles
    classDef data fill:#a8d8ff,stroke:#333,stroke-width:1px
    classDef model fill:#a8f7a1,stroke:#333,stroke-width:1px
    classDef train fill:#ffd59e,stroke:#333,stroke-width:1px
    classDef infer fill:#deaaff,stroke:#333,stroke-width:1px
    classDef ops fill:#d3d3d3,stroke:#333,stroke-width:1px
    classDef config fill:#ffe685,stroke:#333,stroke-width:1px
```
