How chenliu-1996/cuts works
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).