# saltoricristiano/cosmix-uda architecture

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

- Interactive diagram: https://gitdiagram.com/saltoricristiano/cosmix-uda
- Repository: https://github.com/saltoricristiano/cosmix-uda

## Overview

##### Project Type and Purpose
- This is a research‐oriented, full‐stack Python application for Unsupervised and Semi-Supervised Domain Adaptation (UDA/SSDA) in 3D LiDAR semantic segmentation.
- It implements the CoSMix approach: a two-branch network that mixes source (synthetic) and target (real) point cloud samples during training to reduce domain shift.

##### Top-Level Components
- Entry-point Scripts
- train_source.py – warm-up pre-training on source data
- adapt_cosmix_uda.py – UDA adaptation stage
- adapt_cosmix_ssda.py – SSDA adaptation stage
- finetune_ssda.py – one-shot target fine-tuning
- eval.py – evaluation/inference
- Configuration Layer
- configs/ – YAML files for all experiments (source, UDA, SSDA, finetuning)
- Data Handling
- utils/datasets/ – dataset classes for SynLiDAR, SemanticKITTI, SemanticPOSS
- utils/sampling/ – voxelizer, SSDA samplers
- utils/collation/ – custom collate functions
- Core Pipelines
- utils/pipelines/masked_simm_pipeline.py – UDA mixing pipeline
- utils/pipelines/masked_ssda_pipeline.py – SSDA mixing pipeline
- utils/pipelines/trainer_lighting.py – PyTorch Lightning trainer wrapper
- Model Definitions
- utils/models/ – MinkUNet, ResNet backbones, integration with NVIDIA’s MinkowskiEngine
- Loss Computation
- utils/losses/losses.py – segmentation and mix losses
- External Services & Assets
- WandB for logging
- Docker images (crissalto/online-adaptation-mink)

##### Interactions & Data Flow
- Each script parses command‐line args → reads one or more YAML config files → instantiates a config object.
- Config object selects which pipeline to use.
- Pipeline constructs two DataLoader streams (source & target), applying voxelization, sampling, and mixing transforms.
- Mixed batches feed into the two-branch network (teacher & student) built from utils/models.
- Losses computed via utils/losses → backpropagation through PyTorch Lightning engine.
- Checkpoints, metrics, and visualizations are logged to WandB and saved to disk.
- eval.py reloads a saved checkpoint, runs forward passes on source/target data, optionally saves predictions.

##### Architectural Patterns
- Modular layering: Config → Pipeline → Dataset → Model → Loss → Trainer → Logger
- Two-branch, teacher-student domain adaptation
- Sample-mixing at point-cloud level for domain invariance
- Use of PyTorch Lightning for training orchestration

##### Key Technologies & Frameworks
- Python 3.8, PyTorch 1.8, PyTorch Lightning 1.4.1
- NVIDIA MinkowskiEngine for sparse 3D CNNs
- Open3D for point-cloud handling
- WandB for experiment tracking
- tqdm for progress bars; Docker for environment reproducibility

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "Entry-Point Scripts"
        TS["train_source.py"]:::orchestration
        AU["adapt_cosmix_uda.py"]:::orchestration
        AS["adapt_cosmix_ssda.py"]:::orchestration
        FT["finetune_ssda.py"]:::orchestration
        EV["eval.py"]:::orchestration
    end

    subgraph "Configuration Layer"
        CfgLoader["config.py"]:::config
        CfgYAML["Experiment YAMLs"]:::config
    end

    subgraph "Core Pipelines"
        UDA["masked_simm_pipeline.py"]:::compute
        SSDA["masked_ssda_pipeline.py"]:::compute
        TrainerWrap["trainer_lighting.py"]:::compute
    end

    subgraph "Data Handling"
        DSyn["synlidar.py"]:::data
        DSK["semantickitti.py"]:::data
        DSP["semanticposs.py"]:::data
        DCommon["dataset.py\nconcat_dataset.py"]:::data
        Coll["collation.py"]:::data
        Vox["voxelizer.py"]:::data
        SSA["ssda.py"]:::data
    end

    subgraph "Model & Loss"
        Mink["minkunet.py\n(MinkowskiEngine)"]:::compute
        ResNet["resnet.py"]:::compute
        Loss["losses.py"]:::compute
    end

    PL["PyTorch Lightning\n(Training Engine)"]:::orchestration

    subgraph "External Services"
        WandB["WandB"]:::external
        Assets["assets/"]:::external
        Docker["Docker Registry"]:::external
    end

    %% Flow
    TS --> CfgLoader
    AU --> CfgLoader
    AS --> CfgLoader
    FT --> CfgLoader
    EV --> CfgLoader

    CfgLoader --> UDA
    CfgLoader --> SSDA
    CfgLoader --> TrainerWrap

    UDA --> DSyn
    UDA --> DSK
    UDA --> DSP
    SSDA --> DSyn
    SSDA --> DSK
    SSDA --> DSP

    DSyn --> Coll
    DSK --> Coll
    DSP --> Coll

    Coll --> Vox
    Vox --> SSA
    SSA --> Mink
    SSA --> ResNet

    Mink --> Loss
    ResNet --> Loss
    Loss --> PL

    TrainerWrap --> PL
    PL --> WandB
    PL --> Assets
    PL --> Docker

    %% Click Events
    click TS "https://github.com/saltoricristiano/cosmix-uda/blob/main/train_source.py"
    click AU "https://github.com/saltoricristiano/cosmix-uda/blob/main/adapt_cosmix_uda.py"
    click AS "https://github.com/saltoricristiano/cosmix-uda/blob/main/adapt_cosmix_ssda.py"
    click FT "https://github.com/saltoricristiano/cosmix-uda/blob/main/finetune_ssda.py"
    click EV "https://github.com/saltoricristiano/cosmix-uda/blob/main/eval.py"
    click CfgLoader "https://github.com/saltoricristiano/cosmix-uda/blob/main/configs/config.py"
    click CfgYAML "https://github.com/saltoricristiano/cosmix-uda/tree/main/configs/"
    click UDA "https://github.com/saltoricristiano/cosmix-uda/blob/main/utils/pipelines/masked_simm_pipeline.py"
    click SSDA "https://github.com/saltoricristiano/cosmix-uda/blob/main/utils/pipelines/masked_ssda_pipeline.py"
    click TrainerWrap "https://github.com/saltoricristiano/cosmix-uda/blob/main/utils/pipelines/trainer_lighting.py"
    click DSyn "https://github.com/saltoricristiano/cosmix-uda/blob/main/utils/datasets/synlidar.py"
    click DSK "https://github.com/saltoricristiano/cosmix-uda/blob/main/utils/datasets/semantickitti.py"
    click DSP "https://github.com/saltoricristiano/cosmix-uda/blob/main/utils/datasets/semanticposs.py"
    click DCommon "https://github.com/saltoricristiano/cosmix-uda/blob/main/utils/datasets/dataset.py"
    click Coll "https://github.com/saltoricristiano/cosmix-uda/blob/main/utils/collation/collation.py"
    click Vox "https://github.com/saltoricristiano/cosmix-uda/blob/main/utils/sampling/voxelizer.py"
    click SSA "https://github.com/saltoricristiano/cosmix-uda/blob/main/utils/sampling/ssda.py"
    click Mink "https://github.com/saltoricristiano/cosmix-uda/blob/main/utils/models/minkunet.py"
    click ResNet "https://github.com/saltoricristiano/cosmix-uda/blob/main/utils/models/resnet.py"
    click Loss "https://github.com/saltoricristiano/cosmix-uda/blob/main/utils/losses/losses.py"

    %% Styles
    classDef orchestration fill:#FFA500,stroke:#333,stroke-width:1px
    classDef config fill:#DDA0DD,stroke:#333,stroke-width:1px
    classDef data fill:#87CEEB,stroke:#333,stroke-width:1px
    classDef compute fill:#90EE90,stroke:#333,stroke-width:1px
    classDef external fill:#D3D3D3,stroke:#333,stroke-width:1px
    class PL external
    class WandB,Docker,Assets external
    class Loss compute
    class Mink,ResNet compute
    class TS,AU,AS,FT,EV orchestration
    class CfgLoader,CfgYAML config
    class DSyn,DSK,DSP,DCommon,Coll,Vox,SSA data
    class UDA,SSDA,TrainerWrap compute
```
