# cviu-csu/hrdecoder architecture

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

- Interactive diagram: https://gitdiagram.com/cviu-csu/hrdecoder
- Repository: https://github.com/cviu-csu/hrdecoder

## Overview

##### Project Type and Purpose
- The project is a full-stack research implementation focused on high‐resolution decoding for lesion segmentation in fundus images.
- It integrates custom segmentation algorithms (HRDecoder/Efficient-HRDecoder) within the MMsegmentation framework, leveraging PyTorch and domain-specific data (IDRiD and DDR).
- The README details not only algorithm differences (e.g., feature compression with a 1×1 convolution) but also instructions for preparing datasets, training, and testing.

##### File Structure to Identify Architectural Components
- Top-level Directories:
– configs: Contains configuration files with subdirectories that separate base configurations (datasets, model architectures, schedules) and custom “lesion” configs for segmentation experiments.
– mmseg: The core segmentation framework. It includes submodules for APIs (training, testing, inference), core operations (evaluation, distributed training wrappers, and segmentation utilities), datasets and pipelines for data preprocessing, model backbones, decode heads, necks, loss functions, and various utilities.
– tools: Houses training, testing, dataset conversion (scripts converting .tif labels to .png), log analysis, and model evaluation scripts.
– (Though data is not present in the file tree, the README outlines that a “data” directory (with IDRiD and DDR datasets organized by images and labels) should exist in the final project structure.)
– Other files such as requirements.txt and README.md complete the overall project setup.

##### Main Components to Highlight
a. Data Sources and Preprocessing:
– External datasets (IDRiD and DDR segmentation parts) that are preprocessed and organized into images and labels.
– Data conversion tools under tools/convert_dataset (idrid.py, ddr.py) used to convert ground-truth formats.
– Data pipelines defined in mmseg/datasets and mmseg/datasets/pipelines that perform loading, formatting, transformations, and augmentation.

b. Configuration and Setup Layer:
– The configs directory holds separate configurations for datasets, models, and training schedules. Base configurations in configs/_base_ define templates (default runtime configurations, dataset specifics, and model architecture parameters), while the lesion-specific configs in configs/lesion define experiments.
– This layer informs model building, dataset loader settings, and training hyper-parameters.

c. Model Architecture and Components:
– The backbone architectures (HRNet, Mit, ResNet, etc.) found in mmseg/models/backbones.
– HRDecoder and Efficient-HRDecoder models implemented in mmseg/models/segmentors, with additional modules for decode heads (mmseg/models/decode_heads) and necks (mmseg/models/necks).
– The interplay between the backbone, HR representation learning module, and HR fusion module. In Efficient-HRDecoder, the use of a 1×1 convolution for feature compression is a key component.

d. Training and Evaluation Layer:
– Training scripts under tools (e.g., dist_train.sh) invoke training routines provided by mmseg/apis/train.py.
– Distributed training utilities and evaluation hooks found in mmseg/core (e.g., ddp_wrapper, evaluation).
– Testing routines and metric computations (like mIoU) under mmseg/apis/test.py and mmseg/core/evaluation.
– Model checkpoints are stored in work_dirs.

e. Supporting Utilities and Frameworks:
– External libraries including PyTorch, mmcv, and MMsegmentation (the backbone of the project).
– Tools for environments, debugging, and performance analysis (mmseg/utils/logger.py, get_flops.py in tools).

##### Relationships and Interactions
– External image/label data → Data conversion scripts → Preprocessed “data” directory.
– Configurations (configs) → Model and dataset setups → mmseg core APIs: they initialize and configure the dataset pipelines (mmseg/datasets) and model architecture (mmseg/models).
– Model training is initiated via tools/dist_train.sh that calls mmseg/apis/train.py, which in turn loads configurations and instantiates the model components.
– During inference/testing, tools/dist_test.sh invokes mmseg/apis/test.py; evaluation components in mmseg/core/evaluation process performance metrics.
– The interactions between the backbone, HR representation module, and HR fusion module form the internal data path within the network.
– Data flow from datasets → preprocessors → model inputs.
– Dependency from configuration files to both model and training pipeline.
– Connection between training scripts and distributed training APIs.

##### Architectural Patterns
- The project employs a modular design, inspired by MMsegmentation:
– Separation of concerns: configuration, data preprocessing, model construction, training, and evaluation.
– Use of a configuration‐driven setup that allows swapping or extending models and data pipelines.
– Reusability via shared modules (e.g., backbone definitions and decode heads).
- Emphasis on scalability with distributed training support (ddp_wrapper, multiple GPU settings).

- Start at the periphery with external data sources (IDRiD and DDR) and move inward through the data processing pipeline.
- Follow with the configuration layer that appropriately sets up both the model and training pipeline.
- Finally, capture the training and evaluation loops as the system’s final stage, with outputs (work_dirs storing models and logs).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Data Input & Preprocessing Layer
    subgraph "Data Input & Preprocessing"
        ExternalData["IDRiD & DDR Datasets"]:::external
        subgraph "Data Conversion Tools"
            ddr["DDR Conversion Script"]:::tool
            idrid["IDRiD Conversion Script"]:::tool
        end
        DataPipelines["Data Pipelines"]:::pipeline
        LesionLoader["Lesion Dataset Loader"]:::loader
    end

    %% Configuration & Setup Layer
    subgraph "Configuration & Setup"
        BaseConfigs["Base Configs"]:::config
        LesionConfigs["Lesion-specific Configs"]:::config
    end

    %% Model Architecture Layer
    subgraph "Model Architecture"
        Backbone["Model Backbone"]:::model
        subgraph "HRDecoder Models"
            HRDecoder["HRDecoder/Efficient-HRDecoder Segmentor"]:::model
            hrConfig["HRDecoder Config"]:::config
            efficientConfig["Efficient-HRDecoder Config"]:::config
        end
        DecodeHeads["Decode Heads"]:::model
        Necks["Necks"]:::model
    end

    %% Training, Testing & Evaluation Layer
    subgraph "Training, Testing & Evaluation"
        subgraph "Training Engine"
            TrainScript["Training Script"]:::control
            TrainAPI["Train API"]:::control
        end
        subgraph "Testing & Evaluation Engine"
            TestScript["Testing Script"]:::control
            TestAPI["Test API"]:::control
            Evaluation["Evaluation Components"]:::control
        end
        DDP["Distributed Training Utilities"]:::util
    end

    %% Supporting Utilities
    subgraph "Supporting Utilities"
        Utilities["Utilities & Logger"]:::util
    end

    %% External Libraries
    subgraph "External Libraries"
        Libraries["PyTorch, mmcv, MMsegmentation"]:::external
    end

    %% Data Flow Connections
    ExternalData --> ddr
    ExternalData --> idrid
    ddr --> DataPipelines
    idrid --> DataPipelines
    DataPipelines --> LesionLoader

    %% Link from Data Preprocessing to Configuration
    LesionLoader --> BaseConfigs
    LesionLoader --> LesionConfigs

    %% Configuration to Model Architecture
    BaseConfigs --> Backbone
    BaseConfigs --> HRDecoder
    LesionConfigs --> HRDecoder
    Backbone --> HRDecoder
    HRDecoder --> DecodeHeads
    HRDecoder --> Necks

    %% HRDecoder Configurations to HRDecoder Node
    hrConfig --> HRDecoder
    efficientConfig --> HRDecoder

    %% Model to Training Engine
    HRDecoder --> TrainScript
    HRDecoder --> TrainAPI

    %% Training Engine to Distributed Utilities and Testing/Evaluation
    TrainScript --> DDP
    TrainAPI --> DDP
    TrainScript --> TestScript
    TrainAPI --> TestAPI

    %% Testing & Evaluation Connections
    TestScript --> Evaluation
    TestAPI --> Evaluation

    %% Supporting Utilities influence Training and Testing
    Utilities --> TrainScript
    Utilities --> TestScript

    %% External Libraries support core modules
    Libraries --> BaseConfigs
    Libraries --> Backbone
    Libraries --> TrainScript

    %% Click Events for Component Mappings
    click ddr "https://github.com/cviu-csu/hrdecoder/blob/main/tools/convert_dataset/ddr.py"
    click idrid "https://github.com/cviu-csu/hrdecoder/blob/main/tools/convert_dataset/idrid.py"
    click DataPipelines "https://github.com/cviu-csu/hrdecoder/tree/main/mmseg/datasets/pipelines"
    click LesionLoader "https://github.com/cviu-csu/hrdecoder/blob/main/mmseg/datasets/lesion_dataset.py"
    click BaseConfigs "https://github.com/cviu-csu/hrdecoder/tree/main/configs/_base_"
    click LesionConfigs "https://github.com/cviu-csu/hrdecoder/tree/main/configs/lesion"
    click Backbone "https://github.com/cviu-csu/hrdecoder/tree/main/mmseg/models/backbones"
    click hrConfig "https://github.com/cviu-csu/hrdecoder/blob/main/configs/_base_/models/hrdecoder_fcn_hr18.py"
    click efficientConfig "https://github.com/cviu-csu/hrdecoder/blob/main/configs/_base_/models/efficient-hrdecoder_fcn_hr48.py"
    click HRDecoder "https://github.com/cviu-csu/hrdecoder/blob/main/mmseg/models/segmentors/HRDecoder.py"
    click DecodeHeads "https://github.com/cviu-csu/hrdecoder/tree/main/mmseg/models/decode_heads"
    click Necks "https://github.com/cviu-csu/hrdecoder/tree/main/mmseg/models/necks"
    click TrainScript "https://github.com/cviu-csu/hrdecoder/blob/main/tools/dist_train.sh"
    click TrainAPI "https://github.com/cviu-csu/hrdecoder/blob/main/mmseg/apis/train.py"
    click TestScript "https://github.com/cviu-csu/hrdecoder/blob/main/tools/dist_test.sh"
    click TestAPI "https://github.com/cviu-csu/hrdecoder/blob/main/mmseg/apis/test.py"
    click Evaluation "https://github.com/cviu-csu/hrdecoder/tree/main/mmseg/core/evaluation"
    click DDP "https://github.com/cviu-csu/hrdecoder/blob/main/mmseg/core/ddp_wrapper.py"
    click Utilities "https://github.com/cviu-csu/hrdecoder/blob/main/mmseg/utils/logger.py"

    %% Styles
    classDef external fill:#f9e79f,stroke:#b9770e,stroke-width:2px;
    classDef tool fill:#aed6f1,stroke:#2471a3,stroke-width:2px;
    classDef pipeline fill:#abebc6,stroke:#1e8449,stroke-width:2px;
    classDef loader fill:#f5cba7,stroke:#935116,stroke-width:2px;
    classDef config fill:#d7bde2,stroke:#6c3483,stroke-width:2px;
    classDef model fill:#fad7a0,stroke:#d35400,stroke-width:2px;
    classDef control fill:#d5f5e3,stroke:#27ae60,stroke-width:2px;
    classDef util fill:#d6eaf8,stroke:#2e86c1,stroke-width:2px;
```
