# chenliu-1996/cuts architecture

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

- Interactive diagram: https://gitdiagram.com/chenliu-1996/cuts
- Repository: https://github.com/chenliu-1996/cuts

## Overview

##### Project Type & Purpose
- Type: Research-driven full-stack deep-learning pipeline for unsupervised (and optionally supervised) medical image segmentation.
- Core Purpose:
– Stage 1: Train a convolutional encoder under the CUTS framework (unsupervised).
– Stage 2: (Optional) Train supervised UNet/nnUNet models for benchmark comparison.
– Stage 3: Run comparative SOTA methods (DFC, STEGO, SAM variants).
– Stage 4: Generate segmentations via k-means and diffusion condensation, plot results, and compute metrics.

##### High-Level Component Breakdown
a. Data Layer
– “data” directory: raw/preprocessed image archives (berkeley_natural_images.zip, brain_tumor.zip, etc.)
– “src/datasets” & “src/data_utils”: PyTorch Dataset classes + utilities for data loading, splitting, patch sampling.
– Configured by YAML files under “config/” (dataset paths, hyperparameters, random seeds).

b. Core Model Training
– src/main.py: unsupervised training controller
– src/main_supervised.py: supervised training controller
– src/model/CUTS_model.py: implements convolutional encoder + topological diffusion condensation logic
– src/utils: shared helpers (loss functions, schedulers, logging, metrics)

c. Checkpointing & Logging
– “checkpoints/”: serialized model weights
– “logs/”: training/test logs
– “results/”: segmentation outputs, figures, intermediate arrays

d. Comparative Methods
– “comparison/DFC”, “comparison/STEGO”, “comparison/SAM”, “comparison/MedSAM”, “comparison/SAM_Med2D”
– Each contains scripts to prepare data, train or infer, and produce SOTA method results

e. Analysis & Visualization
– src/scripts_analysis:
· generate_kmeans.py, generate_diffusion.py, generate_baselines.py
· plot_paper_figure_main.py: final figure generation
· run_metrics.py: quantitative evaluation
– Assets: architecture.png under “assets/”

f. Environment & Dependencies
– environment.yml, requirements.txt: Conda/Pip for reproducibility
– External services/libraries: PyTorch, monai, phate, multiscale-phate, CATCH, OpenCV, etc.

##### Relationships & Data Flow
- Control plane: main.py / main_supervised.py reads a config → spawns training/test runs → writes logs & checkpoints
- Comparison plane: comparison/* scripts share the same config input → write their own results in results/
- Analysis plane: scripts_analysis read results/ + config → generate visualizations → write to results/figures
- Metric plane: run_metrics reads results/ + ground-truth from data → writes metrics table

##### Architectural Patterns & Design Principles
- Modular, configuration-driven pipeline (YAML + CLI arguments)
- Separation of concerns: data ingestion, model definition, training loop, evaluation, visualization
- Plug-and-play comparison modules—each SOTA method is isolated under comparison/
- Reproducibility via environment files, logs, and consistent directory conventions

##### Detailed Component Callouts
- Config server: Single node that reads YAMLs and spins up each stage
- Data ingestion: src/data_utils/prepare_dataset.py + src/datasets/*
- CUTS encoder: src/model/CUTS_model.py + utils/diffusion_condensation.py
- Supervised models: src/main_supervised.py + model definitions inside src/model (if any)
- Checkpoint manager: Checkpoints folder, integrated with training loops
- Comparison runners: Step scripts in comparison/STEGO, DFC, SAM variants
- Visualization engine: scripts_analysis + matplotlib/seaborn components in utils

##### Final Touches
– Ensure every component block carries a clear name and technology stack note (e.g., “Model Training – PyTorch 1.12.1 + CUDA 11.3”).
– Annotate any loops (e.g., training loops, iterative diffusion condensation).

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Control Plane
    subgraph "Control Plane"
        style ControlPlane fill:#CCCCCC,stroke:#333,stroke-width:1px
        UnsupCtrl["Unsupervised Controller\n(src/main.py)"]:::control
        SupCtrl["Supervised Controller\n(src/main_supervised.py)"]:::control
        CompRunners["Comparison Runners\n(comparison/*)"]:::control
    end

    %% Data Layer
    subgraph "Data Layer"
        style DataLayer fill:#BBE1FA,stroke:#333,stroke-width:1px
        RawData["Raw/Preprocessed Archives\ndata/"]:::data
        DatasetClasses["Dataset Classes\n(src/datasets/)"]:::data
        DataUtils["Data Utilities\n(src/data_utils/)"]:::data
        ConfigFiles["Config Files\n(config/)"]:::data
    end

    %% Model Training
    subgraph "Model Training"
        style ModelTrain fill:#A8E6CF,stroke:#333,stroke-width:1px
        CUTSModel["CUTS Model\n(src/model/CUTS_model.py)"]:::model
        DiffusionUtils["Diffusion Utils\n(src/utils/diffusion_condensation.py)"]:::model
        subgraph "Shared Utilities"
            style SharedUtils fill:#A8E6CF,stroke:#333,stroke-width:1px
            Losses["Losses\n(src/utils/losses.py)"]:::model
            MetricsUtil["Metrics\n(src/utils/metrics.py)"]:::model
            Scheduler["Scheduler\n(src/utils/scheduler.py)"]:::model
            LogUtil["Log Util\n(src/utils/log_util.py)"]:::model
            OutputSaver["Output Saver\n(src/utils/output_saver.py)"]:::model
            EarlyStop["Early Stop\n(src/utils/early_stop.py)"]:::model
            Seed["Seed Setter\n(src/utils/seed.py)"]:::model
            Parse["Config Parser\n(src/utils/parse.py)"]:::model
            AttrHash["Attr Hashmap\n(src/utils/attribute_hashmap.py)"]:::model
            SegmentationUtil["Segmentation Util\n(src/utils/segmentation.py)"]:::model
        end
    end

    %% Storage
    subgraph "Storage & Logging"
        style Storage fill:#E0E0E0,stroke:#333,stroke-width:1px
        Checkpoints["Checkpoints\n(checkpoints/)"]:::storage
        Logs["Logs\n(logs/)"]:::storage
        Results["Results\n(results/)"]:::storage
    end

    %% Comparison Suite
    subgraph "Comparison Suite"
        style Comparison fill:#FFD3B6,stroke:#333,stroke-width:1px
        DFC["DFC\n(comparison/DFC/)"]:::comparison
        STEGO["STEGO\n(comparison/STEGO/)"]:::comparison
        SAM["SAM\n(comparison/SAM/)"]:::comparison
        MedSAM["MedSAM\n(comparison/MedSAM/)"]:::comparison
        SAMMed2D["SAM_Med2D\n(comparison/SAM_Med2D/)"]:::comparison
    end

    %% Analysis & Visualization
    subgraph "Analysis & Visualization"
        style Analysis fill:#D3B5E5,stroke:#333,stroke-width:1px
        AnalysisScripts["Analysis Scripts\n(src/scripts_analysis/)"]:::analysis
        ArchAsset["Architecture Asset\n(assets/architecture.png)"]:::analysis
    end

    %% Metrics
    RunMetrics["Metrics Engine\n(run_metrics)"]:::analysis

    %% External Dependencies
    subgraph "External Dependencies"
        style External fill:#cccccc,stroke:#999,stroke-dasharray: 5 5
        PyTorch["PyTorch"]:::external
        MONAI["MONAI"]:::external
        PHATE["PHATE/Multiscale-PHATE"]:::external
        CATCH["CATCH"]:::external
        OpenCV["OpenCV"]:::external
    end

    %% Environment
    EnvYml["environment.yml"]:::external
    ReqTxt["requirements.txt"]:::external
    SupYAML["Supervised YAMLs\n(config/supervised_*.yaml)"]:::external

    %% Connections
    UnsupCtrl -->|reads| ConfigFiles
    SupCtrl -->|reads| SupYAML
    UnsupCtrl -->|uses| DataUtils
    SupCtrl -->|uses| DatasetClasses
    DataUtils -->|loads| RawData
    DatasetClasses -->|provides| DataUtils
    DataUtils -->|batches| CUTSModel
    CUTSModel -->|calls| DiffusionUtils
    CUTSModel -->|uses| Losses
    CUTSModel -->|logs| LogUtil
    CUTSModel -->|saves| OutputSaver
    DiffusionUtils -->|iterates| CUTSModel
    CUTSModel -->|writes weights| Checkpoints
    CUTSModel -->|writes logs| Logs
    CUTSModel -->|writes outputs| Results

    CompRunners -->|runs| DFC
    CompRunners -->|runs| STEGO
    CompRunners -->|runs| SAM
    CompRunners -->|runs| MedSAM
    CompRunners -->|runs| SAMMed2D
    DFC -->|writes| Results
    STEGO -->|writes| Results
    SAM -->|writes| Results
    MedSAM -->|writes| Results
    SAMMed2D -->|writes| Results

    Results -->|inputs| AnalysisScripts
    AnalysisScripts -->|generates| ArchAsset
    Results -->|inputs| RunMetrics
    RawData -->|ground truth| RunMetrics
    RunMetrics -->|outputs metrics| Results

    %% Dependencies links
    CUTSModel --> PyTorch
    CUTSModel --> MONAI
    DiffusionUtils --> PHATE
    AnalysisScripts --> OpenCV

    %% Click Events
    click RawData "https://github.com/chenliu-1996/cuts/tree/main/data/"
    click DatasetClasses "https://github.com/chenliu-1996/cuts/tree/main/src/datasets/"
    click DataUtils "https://github.com/chenliu-1996/cuts/tree/main/src/data_utils/"
    click ConfigFiles "https://github.com/chenliu-1996/cuts/tree/main/config/"
    click UnsupCtrl "https://github.com/chenliu-1996/cuts/blob/main/src/main.py"
    click SupCtrl "https://github.com/chenliu-1996/cuts/blob/main/src/main_supervised.py"
    click CUTSModel "https://github.com/chenliu-1996/cuts/blob/main/src/model/CUTS_model.py"
    click DiffusionUtils "https://github.com/chenliu-1996/cuts/blob/main/src/utils/diffusion_condensation.py"
    click Losses "https://github.com/chenliu-1996/cuts/blob/main/src/utils/losses.py"
    click MetricsUtil "https://github.com/chenliu-1996/cuts/blob/main/src/utils/metrics.py"
    click Scheduler "https://github.com/chenliu-1996/cuts/blob/main/src/utils/scheduler.py"
    click LogUtil "https://github.com/chenliu-1996/cuts/blob/main/src/utils/log_util.py"
    click OutputSaver "https://github.com/chenliu-1996/cuts/blob/main/src/utils/output_saver.py"
    click EarlyStop "https://github.com/chenliu-1996/cuts/blob/main/src/utils/early_stop.py"
    click Seed "https://github.com/chenliu-1996/cuts/blob/main/src/utils/seed.py"
    click Parse "https://github.com/chenliu-1996/cuts/blob/main/src/utils/parse.py"
    click AttrHash "https://github.com/chenliu-1996/cuts/blob/main/src/utils/attribute_hashmap.py"
    click SegmentationUtil "https://github.com/chenliu-1996/cuts/blob/main/src/utils/segmentation.py"
    click Checkpoints "https://github.com/chenliu-1996/cuts/tree/main/checkpoints/"
    click Logs "https://github.com/chenliu-1996/cuts/tree/main/logs/"
    click Results "https://github.com/chenliu-1996/cuts/tree/main/results/"
    click DFC "https://github.com/chenliu-1996/cuts/tree/main/comparison/DFC/"
    click STEGO "https://github.com/chenliu-1996/cuts/tree/main/comparison/STEGO/"
    click SAM "https://github.com/chenliu-1996/cuts/tree/main/comparison/SAM/"
    click MedSAM "https://github.com/chenliu-1996/cuts/tree/main/comparison/MedSAM/"
    click SAMMed2D "https://github.com/chenliu-1996/cuts/tree/main/comparison/SAM_Med2D/"
    click AnalysisScripts "https://github.com/chenliu-1996/cuts/tree/main/src/scripts_analysis/"
    click ArchAsset "https://github.com/chenliu-1996/cuts/blob/main/assets/architecture.png"
    click EnvYml "https://github.com/chenliu-1996/cuts/blob/main/environment.yml"
    click ReqTxt "https://github.com/chenliu-1996/cuts/blob/main/requirements.txt"
    click SupYAML "https://github.com/chenliu-1996/cuts/blob/main/config/supervised_*.yaml"

    %% Styles
    classDef data fill:#BBE1FA,stroke:#333;
    classDef model fill:#A8E6CF,stroke:#333;
    classDef comparison fill:#FFD3B6,stroke:#333;
    classDef analysis fill:#D3B5E5,stroke:#333;
    classDef storage fill:#E0E0E0,stroke:#333;
    classDef control fill:#CCCCCC,stroke:#333;
    classDef external fill:#EEEEEE,stroke:#666,stroke-dasharray: 5 5;
```
