# lhoyer/daformer architecture

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

- Interactive diagram: https://gitdiagram.com/lhoyer/daformer
- Repository: https://github.com/lhoyer/daformer

## Overview

Based on our analysis of the project tree and the README, DAFormer is a deep learning research project focusing on unsupervised domain adaptation (UDA) for semantic segmentation. It builds upon the MMSegmentation framework (and related projects such as SegFormer and DACS) and is structured to support configuration‐driven experiments, dataset preparation and conversion, training/inference pipelines, and model evaluation.

##### Main Components
- Configuration Management – Represent the "configs" directory as the module that sets up all experiments. It contains different base configurations, dataset setups, models, and schedules. This component feeds into every part of the pipeline, ensuring reproducibility and modularity.
- Data Management and Preprocessing – Include modules for dataset handling. Highlight the data directories (data/cityscapes, data/gta, etc.) and conversion scripts found in tools/convert_datasets. This part is responsible for preparing input data (downloading, converting label IDs, and organizing the datasets).
- Model Architecture – Break down the network architecture into its key parts:
⁍ Encoder (Transformer-based “MixTransformer” and other backbones in mmseg/models/backbones).
⁍ Decoder (DAFormer decoder, detailed in mmseg/models/decode_heads/daformer_head.py, which performs multi-level context-aware feature fusion).
⁍ UDA-specific modules (found in mmseg/models/uda; e.g., DACS strategy and related self-training modules using ImageNet Feature Distance).
- Training & Evaluation Pipeline – Represent the training scripts and APIs:
⁍ The training and testing APIs within mmseg/apis (train.py, test.py, inference.py).
⁍ The main driver scripts (run_experiments.py, demo/image_demo.py, test.sh) which invoke the training jobs, experiments, and inference processes.
⁍ Experiment management (experiments.py) for automatic configuration generation.
- Utilities and Core Functions – Include core libraries and shared modules:
⁍ mmseg/core (e.g., data pipelines, sampler modules) and mmseg/utils (logging, metrics collection, environment setup).
⁍ Tools for analyzing logs, converting datasets, or other helper scripts in the tools/ directory.

##### Relationships & Data Flow
- Data Management (the configuration specifies dataset paths and augmentation pipelines).
- Model Construction (configuration details which backbone, decoder, and loss functions to use).
- Training Pipeline (invokes training routines using the APIs in mmseg/apis).
- Training Phase: Configuration → Data Loader → Model (with encoder and decoder) → Optimization (with specific schedulers like AdamW and learning rate warmups as defined in configs/_base_/schedules) → Logging/Evaluation.
- Inference Phase: Trained Model Checkpoint → Test Script / Demo (demo/image_demo or tools/test.py) → Evaluation Metrics (mIoU computation, etc.).

##### Architectural Patterns & Design Principles
- Extension capability:
- That the project supports both UDA and domain generalization (see the additional branches or config files).
- Dependencies on external libraries such as mmcv and mmsegmentation by placing them as external modules feeding into the core system.

##### Technologies, Frameworks, and Libraries
- Python as the primary language, with specific emphasis on PyTorch as the deep learning backend.
- Specialized components like the MiT backbone from SegFormer and the DACS modules for UDA.
- Mention that training uses advanced configurations like learning rate warmup, optimizer schedules (adamw, poly10), and rare class sampling methods.

## Diagram (Mermaid)

```mermaid
flowchart TD
    Ext["External Libraries (mmsegmentation, mmcv)"]:::external

    Config["Configuration Settings (configs)"]:::config

    subgraph "Data Management and Preprocessing"
        DataConfig["Dataset Configurations"]:::data
        DataLoad["Data Loading & Pipelines"]:::data
        DataConvert["Dataset Conversion Scripts"]:::data
    end

    subgraph "Model Architecture"
        Encoder["Encoder (Mix Transformer)"]:::model
        Decoder["Decoder (DAFormer Head)"]:::model
        UDA["UDA Modules"]:::model
    end

    subgraph "Training & Evaluation Pipeline"
        APIs["APIs (train,test,inference)"]:::train
        Driver["Driver Scripts & Experiment Management"]:::train
    end

    subgraph "Utilities and Core Functions"
        Core["Core Modules (Data Pipelines)"]:::util
        Utilities["Utility Libraries (Logging,Metrics)"]:::util
        Helpers["Helper Scripts"]:::util
    end

    %% Connections
    Ext --> Config
    Config --> DataConfig
    Config --> APIs
    Config --> Encoder

    DataConfig --> DataLoad
    DataConvert --> DataLoad
    DataLoad --> Encoder

    Encoder --> Decoder
    Decoder --> UDA
    UDA --> APIs

    APIs --> Driver
    APIs --> Utilities
    Core --> APIs
    Driver --> Helpers

    %% Click Events
    click Config "https://github.com/lhoyer/daformer/tree/master/configs/"
    click DataConfig "https://github.com/lhoyer/daformer/tree/master/configs/_base_/datasets/"
    click DataLoad "https://github.com/lhoyer/daformer/tree/master/mmseg/datasets/"
    click DataConvert "https://github.com/lhoyer/daformer/tree/master/tools/convert_datasets/"
    click Encoder "https://github.com/lhoyer/daformer/blob/master/mmseg/models/backbones/mix_transformer.py"
    click Decoder "https://github.com/lhoyer/daformer/blob/master/mmseg/models/decode_heads/daformer_head.py"
    click UDA "https://github.com/lhoyer/daformer/tree/master/mmseg/models/uda/"
    click APIs "https://github.com/lhoyer/daformer/tree/master/mmseg/apis/"
    click Driver "https://github.com/lhoyer/daformer/blob/master/run_experiments.py"
    click Core "https://github.com/lhoyer/daformer/tree/master/mmseg/core/"
    click Utilities "https://github.com/lhoyer/daformer/tree/master/mmseg/utils/"
    click Helpers "https://github.com/lhoyer/daformer/tree/master/tools/"

    %% Styles
    classDef config fill:#ffcc00,stroke:#333,stroke-width:2px
    classDef data fill:#66ccff,stroke:#333,stroke-width:2px
    classDef model fill:#99ff99,stroke:#333,stroke-width:2px
    classDef train fill:#ff9999,stroke:#333,stroke-width:2px
    classDef util fill:#cccccc,stroke:#333,stroke-width:2px
    classDef external fill:#d1b3ff,stroke:#333,stroke-width:2px
```
