# rosalindfranklininstitute/volume-segmantics architecture

> Architecture diagram of the GitHub repository rosalindfranklininstitute/volume-segmantics, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/rosalindfranklininstitute/volume-segmantics
- Repository: https://github.com/rosalindfranklininstitute/volume-segmantics

## Overview

Volume Segmantics trains 2D segmentation models from labeled 3D volumes, then applies those models to segment new volumes. Training slices and augments data, configures a model and optional multitask heads, and optimizes it; prediction runs across configured axes and rotations, assembles results, and writes volume outputs. The README also documents 2.5D slicing, DINO encoders, and configurable multitask training. Some subsystem links are dashed because their implementation was not sampled.

Main entry points: [`volume_segmantics/model/operations/vol_seg_2d_trainer.py`](https://github.com/rosalindfranklininstitute/volume-segmantics/blob/main/volume_segmantics/model/operations/vol_seg_2d_trainer.py) (2D trainer), [`volume_segmantics/api.py`](https://github.com/rosalindfranklininstitute/volume-segmantics/blob/main/volume_segmantics/api.py) (Prediction API), [`volume_segmantics/model/model_2d.py`](https://github.com/rosalindfranklininstitute/volume-segmantics/blob/main/volume_segmantics/model/model_2d.py) (Segmentation models), [`volume_segmantics/data/dataloaders.py`](https://github.com/rosalindfranklininstitute/volume-segmantics/blob/main/volume_segmantics/data/dataloaders.py) (Data loaders)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_data["Data preparation"]
  node_slicer["Volume slicer<br/>[slicers.py]"]
  node_dataloaders["Data loaders<br/>[dataloaders.py]"]
  node_pipeline_data["Pipeline dataset"]
  node_targets["Target generation"]
end

subgraph group_training["Model training"]
  node_train_cli["Training command<br/>[train_2d_model.py]"]
  node_trainer["2D trainer"]
  node_model_manager["Model manager"]
  node_model["Segmentation models<br/>[model_2d.py]"]
  node_dino["DINO encoder<br/>[dino_encoder.py]"]
  node_heads["Multitask heads"]
  node_losses["Loss functions<br/>[trainer_losses.py]"]
  node_semi_supervised["Semi-supervised training<br/>[mean_teacher.py]"]
end

subgraph group_prediction["Volume prediction"]
  node_predict_api["Prediction API<br/>[api.py]"]
  node_predictor["2D predictor"]
  node_prediction_manager["Prediction manager"]
  node_inference_modes["Inference modes<br/>[inference_modes.py]"]
  node_per_axis["Per-axis prediction"]
  node_writer["Volume writer<br/>[writer.py]"]
end

subgraph group_assembly["Result assembly"]
  node_assembly_base["Assembly interface<br/>[base.py]"]
  node_prediction_bundle["Prediction bundle"]
  node_watershed["Watershed assembly<br/>[watershed_3d.py]"]
  node_usegment["uSegment3D assembly<br/>[usegment3d.py]"]
end

subgraph group_shared["Configuration and utilities"]
  node_pipeline_config["Pipeline configuration<br/>[pipeline_loader.py]"]
  node_registry["Pipeline registries"]
  node_io_utils["Volume I/O<br/>[base_data_utils.py]"]
  node_settings["Runtime settings<br/>[config.py]"]
end

node_researcher(("Researcher"))

node_researcher -->|"starts training"| node_train_cli
node_train_cli -->|"invokes"| node_trainer
node_trainer -->|"loads batches"| node_dataloaders
node_trainer -->|"configures model"| node_model_manager
node_trainer -->|"uses losses"| node_losses
node_trainer -->|"supports training"| node_semi_supervised
node_trainer -->|"loads configuration"| node_pipeline_config
node_model_manager -->|"creates model"| node_model
node_model -->|"selects encoder"| node_dino
node_model -->|"builds heads"| node_heads
node_pipeline_config -->|"resolves components"| node_registry
node_pipeline_data -->|"generates targets"| node_targets
node_pipeline_data -->|"uses configuration"| node_pipeline_config
node_researcher -->|"requests prediction"| node_predict_api
node_predict_api -->|"invokes"| node_predictor
node_predictor -->|"loads slices"| node_dataloaders
node_prediction_manager -->|"delegates prediction"| node_predictor
node_predict_api -->|"supports axis prediction"| node_per_axis
node_predict_api -->|"builds bundle"| node_prediction_bundle
node_per_axis -->|"uses assembly"| node_assembly_base
node_usegment -->|"implements interface"| node_assembly_base
node_usegment -->|"consumes bundle"| node_prediction_bundle
node_watershed -->|"implements interface"| node_assembly_base
node_predict_api -.->|"writes output"| node_writer
node_writer -.->|"serializes volume"| node_io_utils
node_predict_api -.->|"selects prediction mode"| node_inference_modes
node_dataloaders -.->|"uses volume slices"| node_slicer
node_researcher -->|"provides settings"| node_settings

click node_train_cli "https://github.com/rosalindfranklininstitute/volume-segmantics/blob/main/volume_segmantics/scripts/train_2d_model.py"
click node_trainer "https://github.com/rosalindfranklininstitute/volume-segmantics/blob/main/volume_segmantics/model/operations/vol_seg_2d_trainer.py"
click node_slicer "https://github.com/rosalindfranklininstitute/volume-segmantics/blob/main/volume_segmantics/data/slicers.py"
click node_dataloaders "https://github.com/rosalindfranklininstitute/volume-segmantics/blob/main/volume_segmantics/data/dataloaders.py"
click node_pipeline_data "https://github.com/rosalindfranklininstitute/volume-segmantics/blob/main/volume_segmantics/data/pipeline_dataset.py"
click node_pipeline_config "https://github.com/rosalindfranklininstitute/volume-segmantics/blob/main/volume_segmantics/data/pipeline_loader.py"
click node_targets "https://github.com/rosalindfranklininstitute/volume-segmantics/tree/main/volume_segmantics/data/targets"
click node_registry "https://github.com/rosalindfranklininstitute/volume-segmantics/blob/main/volume_segmantics/data/pipeline_registry.py"
click node_model_manager "https://github.com/rosalindfranklininstitute/volume-segmantics/blob/main/volume_segmantics/model/operations/trainer_model_manager.py"
click node_model "https://github.com/rosalindfranklininstitute/volume-segmantics/blob/main/volume_segmantics/model/model_2d.py"
click node_dino "https://github.com/rosalindfranklininstitute/volume-segmantics/blob/main/volume_segmantics/model/encoders/dino_encoder.py"
click node_heads "https://github.com/rosalindfranklininstitute/volume-segmantics/tree/main/volume_segmantics/model/heads"
click node_losses "https://github.com/rosalindfranklininstitute/volume-segmantics/blob/main/volume_segmantics/model/operations/trainer_losses.py"
click node_semi_supervised "https://github.com/rosalindfranklininstitute/volume-segmantics/blob/main/volume_segmantics/model/training/mean_teacher.py"
click node_predict_api "https://github.com/rosalindfranklininstitute/volume-segmantics/blob/main/volume_segmantics/api.py"
click node_predictor "https://github.com/rosalindfranklininstitute/volume-segmantics/blob/main/volume_segmantics/model/operations/vol_seg_2d_predictor.py"
click node_prediction_manager "https://github.com/rosalindfranklininstitute/volume-segmantics/blob/main/volume_segmantics/model/operations/vol_seg_prediction_manager.py"
click node_inference_modes "https://github.com/rosalindfranklininstitute/volume-segmantics/blob/main/volume_segmantics/prediction/inference_modes.py"
click node_per_axis "https://github.com/rosalindfranklininstitute/volume-segmantics/blob/main/volume_segmantics/prediction/per_axis_instances.py"
click node_assembly_base "https://github.com/rosalindfranklininstitute/volume-segmantics/blob/main/volume_segmantics/inference/instance_assembly/base.py"
click node_prediction_bundle "https://github.com/rosalindfranklininstitute/volume-segmantics/blob/main/volume_segmantics/inference/instance_assembly/prediction_bundle.py"
click node_watershed "https://github.com/rosalindfranklininstitute/volume-segmantics/blob/main/volume_segmantics/inference/instance_assembly/watershed_3d.py"
click node_usegment "https://github.com/rosalindfranklininstitute/volume-segmantics/blob/main/volume_segmantics/inference/instance_assembly/usegment3d.py"
click node_writer "https://github.com/rosalindfranklininstitute/volume-segmantics/blob/main/volume_segmantics/prediction/writer.py"
click node_io_utils "https://github.com/rosalindfranklininstitute/volume-segmantics/blob/main/volume_segmantics/utilities/base_data_utils.py"
click node_settings "https://github.com/rosalindfranklininstitute/volume-segmantics/blob/main/volume_segmantics/utilities/config.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_slicer,node_dataloaders,node_pipeline_data,node_targets toneBlue
class node_train_cli,node_trainer,node_model_manager,node_model,node_dino,node_heads,node_losses,node_semi_supervised toneAmber
class node_predict_api,node_predictor,node_prediction_manager,node_inference_modes,node_per_axis,node_writer toneMint
class node_assembly_base,node_prediction_bundle,node_watershed,node_usegment toneRose
class node_pipeline_config,node_registry,node_io_utils,node_settings,node_researcher toneIndigo
```

## Components

### Data preparation

- [Volume slicer](https://github.com/rosalindfranklininstitute/volume-segmantics/blob/main/volume_segmantics/data/slicers.py): `volume_segmantics/data/slicers.py`
- [Data loaders](https://github.com/rosalindfranklininstitute/volume-segmantics/blob/main/volume_segmantics/data/dataloaders.py): `volume_segmantics/data/dataloaders.py`
- [Pipeline dataset](https://github.com/rosalindfranklininstitute/volume-segmantics/blob/main/volume_segmantics/data/pipeline_dataset.py): `volume_segmantics/data/pipeline_dataset.py`
- [Target generation](https://github.com/rosalindfranklininstitute/volume-segmantics/tree/main/volume_segmantics/data/targets): `volume_segmantics/data/targets`

### Model training

- [Training command](https://github.com/rosalindfranklininstitute/volume-segmantics/blob/main/volume_segmantics/scripts/train_2d_model.py): `volume_segmantics/scripts/train_2d_model.py`
- [2D trainer](https://github.com/rosalindfranklininstitute/volume-segmantics/blob/main/volume_segmantics/model/operations/vol_seg_2d_trainer.py): `volume_segmantics/model/operations/vol_seg_2d_trainer.py`
- [Model manager](https://github.com/rosalindfranklininstitute/volume-segmantics/blob/main/volume_segmantics/model/operations/trainer_model_manager.py): `volume_segmantics/model/operations/trainer_model_manager.py`
- [Segmentation models](https://github.com/rosalindfranklininstitute/volume-segmantics/blob/main/volume_segmantics/model/model_2d.py): `volume_segmantics/model/model_2d.py`
- [DINO encoder](https://github.com/rosalindfranklininstitute/volume-segmantics/blob/main/volume_segmantics/model/encoders/dino_encoder.py): `volume_segmantics/model/encoders/dino_encoder.py`
- [Multitask heads](https://github.com/rosalindfranklininstitute/volume-segmantics/tree/main/volume_segmantics/model/heads): `volume_segmantics/model/heads`
- [Loss functions](https://github.com/rosalindfranklininstitute/volume-segmantics/blob/main/volume_segmantics/model/operations/trainer_losses.py): `volume_segmantics/model/operations/trainer_losses.py`
- [Semi-supervised training](https://github.com/rosalindfranklininstitute/volume-segmantics/blob/main/volume_segmantics/model/training/mean_teacher.py): `volume_segmantics/model/training/mean_teacher.py`

### Volume prediction

- [Prediction API](https://github.com/rosalindfranklininstitute/volume-segmantics/blob/main/volume_segmantics/api.py): `volume_segmantics/api.py`
- [2D predictor](https://github.com/rosalindfranklininstitute/volume-segmantics/blob/main/volume_segmantics/model/operations/vol_seg_2d_predictor.py): `volume_segmantics/model/operations/vol_seg_2d_predictor.py`
- [Prediction manager](https://github.com/rosalindfranklininstitute/volume-segmantics/blob/main/volume_segmantics/model/operations/vol_seg_prediction_manager.py): `volume_segmantics/model/operations/vol_seg_prediction_manager.py`
- [Inference modes](https://github.com/rosalindfranklininstitute/volume-segmantics/blob/main/volume_segmantics/prediction/inference_modes.py): `volume_segmantics/prediction/inference_modes.py`
- [Per-axis prediction](https://github.com/rosalindfranklininstitute/volume-segmantics/blob/main/volume_segmantics/prediction/per_axis_instances.py): `volume_segmantics/prediction/per_axis_instances.py`
- [Volume writer](https://github.com/rosalindfranklininstitute/volume-segmantics/blob/main/volume_segmantics/prediction/writer.py): `volume_segmantics/prediction/writer.py`

### Result assembly

- [Assembly interface](https://github.com/rosalindfranklininstitute/volume-segmantics/blob/main/volume_segmantics/inference/instance_assembly/base.py): `volume_segmantics/inference/instance_assembly/base.py`
- [Prediction bundle](https://github.com/rosalindfranklininstitute/volume-segmantics/blob/main/volume_segmantics/inference/instance_assembly/prediction_bundle.py): `volume_segmantics/inference/instance_assembly/prediction_bundle.py`
- [Watershed assembly](https://github.com/rosalindfranklininstitute/volume-segmantics/blob/main/volume_segmantics/inference/instance_assembly/watershed_3d.py): `volume_segmantics/inference/instance_assembly/watershed_3d.py`
- [uSegment3D assembly](https://github.com/rosalindfranklininstitute/volume-segmantics/blob/main/volume_segmantics/inference/instance_assembly/usegment3d.py): `volume_segmantics/inference/instance_assembly/usegment3d.py`

### Configuration and utilities

- [Pipeline configuration](https://github.com/rosalindfranklininstitute/volume-segmantics/blob/main/volume_segmantics/data/pipeline_loader.py): `volume_segmantics/data/pipeline_loader.py`
- [Pipeline registries](https://github.com/rosalindfranklininstitute/volume-segmantics/blob/main/volume_segmantics/data/pipeline_registry.py): `volume_segmantics/data/pipeline_registry.py`
- [Volume I/O](https://github.com/rosalindfranklininstitute/volume-segmantics/blob/main/volume_segmantics/utilities/base_data_utils.py): `volume_segmantics/utilities/base_data_utils.py`
- [Runtime settings](https://github.com/rosalindfranklininstitute/volume-segmantics/blob/main/volume_segmantics/utilities/config.py): `volume_segmantics/utilities/config.py`

### Other components

- **Researcher**

## Connections

- Researcher → Training command: starts training (evidence: `README.md`)
- Training command → 2D trainer: invokes
- 2D trainer → Data loaders: loads batches (evidence: `volume_segmantics/model/operations/vol_seg_2d_trainer.py`)
- 2D trainer → Model manager: configures model (evidence: `volume_segmantics/model/operations/vol_seg_2d_trainer.py`)
- 2D trainer → Loss functions: uses losses (evidence: `volume_segmantics/model/operations/vol_seg_2d_trainer.py`)
- 2D trainer → Semi-supervised training: supports training (evidence: `volume_segmantics/model/operations/vol_seg_2d_trainer.py`)
- 2D trainer → Pipeline configuration: loads configuration (evidence: `volume_segmantics/model/operations/vol_seg_2d_trainer.py`)
- Model manager → Segmentation models: creates model (evidence: `volume_segmantics/model/operations/trainer_model_manager.py`)
- Segmentation models → DINO encoder: selects encoder (evidence: `volume_segmantics/model/model_2d.py`)
- Segmentation models → Multitask heads: builds heads (evidence: `volume_segmantics/model/model_2d.py`)
- Pipeline configuration → Pipeline registries: resolves components (evidence: `volume_segmantics/data/pipeline_loader.py`)
- Pipeline dataset → Target generation: generates targets (evidence: `volume_segmantics/data/pipeline_dataset.py`)
- Pipeline dataset → Pipeline configuration: uses configuration (evidence: `volume_segmantics/data/pipeline_dataset.py`)
- Researcher → Prediction API: requests prediction (evidence: `README.md`)
- Prediction API → 2D predictor: invokes (evidence: `volume_segmantics/api.py`)
- 2D predictor → Data loaders: loads slices (evidence: `volume_segmantics/model/operations/vol_seg_2d_predictor.py`)
- Prediction manager → 2D predictor: delegates prediction (evidence: `volume_segmantics/model/operations/vol_seg_prediction_manager.py`)
- Prediction API → Per-axis prediction: supports axis prediction (evidence: `volume_segmantics/api.py`)
- Prediction API → Prediction bundle: builds bundle (evidence: `volume_segmantics/api.py`)
- Per-axis prediction → Assembly interface: uses assembly (evidence: `volume_segmantics/prediction/per_axis_instances.py`)
- uSegment3D assembly → Assembly interface: implements interface (evidence: `volume_segmantics/inference/instance_assembly/usegment3d.py`)
- uSegment3D assembly → Prediction bundle: consumes bundle (evidence: `volume_segmantics/inference/instance_assembly/usegment3d.py`)
- Watershed assembly → Assembly interface: implements interface (evidence: `volume_segmantics/inference/instance_assembly/watershed_3d.py`)
- Prediction API → Volume writer: writes output
- Volume writer → Volume I/O: serializes volume
- Prediction API → Inference modes: selects prediction mode
- Data loaders → Volume slicer: uses volume slices
- Researcher → Runtime settings: provides settings (evidence: `README.md`)
