# rikixy/virtual-staining architecture

> Architecture diagram of the GitHub repository rikixy/virtual-staining, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/rikixy/virtual-staining
- Repository: https://github.com/rikixy/virtual-staining

## Overview

Virtual Staining is a reproducible histopathology image-translation framework. Users configure a run, prepare slide sets into patches, train Pix2Pix or CycleGAN, generate images, then evaluate or compare results. It also supports single-image and directory inference, TIFF conversion, comparison panels, run organization, and queued staged runs. The graph reflects the sampled pipeline, inference, and metadata code plus README-documented capabilities; unsampled subsystem wiring is left unspecified.

Main entry points: [`virtual_staining/applications/pipeline.py`](https://github.com/rikixy/virtual-staining/blob/main/virtual_staining/applications/pipeline.py) (Stage Orchestrator), [`virtual_staining/inference/runner.py`](https://github.com/rikixy/virtual-staining/blob/main/virtual_staining/inference/runner.py) (Inference Runner), [`virtual_staining/applications/evaluate.py`](https://github.com/rikixy/virtual-staining/blob/main/virtual_staining/applications/evaluate.py) (Run Evaluation), [`virtual_staining/methods`](https://github.com/rikixy/virtual-staining/tree/main/virtual_staining/methods) (Translation Methods)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workflow["Run Workflow"]
  node_pipeline["Stage Orchestrator<br/>[pipeline.py]"]
  node_config["Run Configuration<br/>[run.py]"]
  node_preparation["Dataset Preparation<br/>[prepare.py]"]
  node_data["Slide Data Processing"]
  node_experiment[("Run Session<br/>[session.py]")]
end

subgraph group_translation["Translation Runtime"]
  node_training["Model Training<br/>[train.py]"]
  node_trainer["Training Runtime<br/>[trainer.py]"]
  node_methods["Translation Methods"]
  node_models["Network Components"]
  node_checkpoints["Checkpoint Selection"]
  node_inference["Run Inference<br/>[infer.py]"]
  node_inference_runtime["Inference Runner<br/>[runner.py]"]
  node_single_inference["Image Inference<br/>[single.py]"]
  node_artifacts["Generated Artifacts<br/>[outputs.py]"]
end

subgraph group_analysis["Evaluation"]
  node_evaluation["Run Evaluation<br/>[evaluate.py]"]
  node_metrics["Image Metrics<br/>[metrics.py]"]
  node_reports["Evaluation Reports<br/>[reports.py]"]
  node_comparison["Run Comparison<br/>[compare.py]"]
end

subgraph group_utilities["Run Utilities"]
  node_conversion["TIFF Conversion<br/>[convert.py]"]
  node_panels["Comparison Panels<br/>[compare_panels.py]"]
  node_organization["Output Organization<br/>[organize.py]"]
  node_queue["Queued Runs<br/>[run_queue.py]"]
  node_status["Dependency Status<br/>[status.py]"]
end

node_user(("User"))

node_user -->|"runs stages"| node_pipeline
node_pipeline -->|"loads config"| node_config
node_pipeline -->|"dispatches prepare"| node_preparation
node_pipeline -->|"dispatches train"| node_training
node_pipeline -->|"dispatches infer"| node_inference
node_pipeline -->|"dispatches evaluate"| node_evaluation
node_preparation -->|"builds patches"| node_data
node_training -->|"starts training"| node_trainer
node_trainer -->|"uses method"| node_methods
node_methods -->|"constructs networks"| node_models
node_inference -->|"runs inference"| node_inference_runtime
node_inference_runtime -->|"selects checkpoint"| node_checkpoints
node_inference_runtime -->|"builds predictor"| node_methods
node_inference_runtime -->|"writes outputs"| node_artifacts
node_user -->|"infers images"| node_single_inference
node_single_inference -->|"writes outputs"| node_artifacts
node_evaluation -->|"computes metrics"| node_metrics
node_evaluation -->|"writes reports"| node_reports
node_user -->|"compares runs"| node_comparison
node_user -->|"converts TIFFs"| node_conversion
node_user -->|"builds panels"| node_panels
node_user -->|"organizes outputs"| node_organization
node_user -->|"queues runs"| node_queue
node_queue -->|"dispatches stages"| node_pipeline
node_user -->|"checks dependencies"| node_status

click node_pipeline "https://github.com/rikixy/virtual-staining/blob/main/virtual_staining/applications/pipeline.py"
click node_config "https://github.com/rikixy/virtual-staining/blob/main/virtual_staining/config/run.py"
click node_preparation "https://github.com/rikixy/virtual-staining/blob/main/virtual_staining/applications/prepare.py"
click node_data "https://github.com/rikixy/virtual-staining/tree/main/virtual_staining/data"
click node_training "https://github.com/rikixy/virtual-staining/blob/main/virtual_staining/applications/train.py"
click node_trainer "https://github.com/rikixy/virtual-staining/blob/main/virtual_staining/training/trainer.py"
click node_methods "https://github.com/rikixy/virtual-staining/tree/main/virtual_staining/methods"
click node_models "https://github.com/rikixy/virtual-staining/tree/main/virtual_staining/models"
click node_checkpoints "https://github.com/rikixy/virtual-staining/blob/main/virtual_staining/checkpoint_selection.py"
click node_inference "https://github.com/rikixy/virtual-staining/blob/main/virtual_staining/applications/infer.py"
click node_inference_runtime "https://github.com/rikixy/virtual-staining/blob/main/virtual_staining/inference/runner.py"
click node_single_inference "https://github.com/rikixy/virtual-staining/blob/main/virtual_staining/inference/single.py"
click node_artifacts "https://github.com/rikixy/virtual-staining/blob/main/virtual_staining/inference/outputs.py"
click node_experiment "https://github.com/rikixy/virtual-staining/blob/main/virtual_staining/experiment/session.py"
click node_evaluation "https://github.com/rikixy/virtual-staining/blob/main/virtual_staining/applications/evaluate.py"
click node_metrics "https://github.com/rikixy/virtual-staining/blob/main/virtual_staining/metrics.py"
click node_reports "https://github.com/rikixy/virtual-staining/blob/main/virtual_staining/evaluation/reports.py"
click node_comparison "https://github.com/rikixy/virtual-staining/blob/main/virtual_staining/applications/compare.py"
click node_conversion "https://github.com/rikixy/virtual-staining/blob/main/virtual_staining/applications/convert.py"
click node_panels "https://github.com/rikixy/virtual-staining/blob/main/virtual_staining/applications/compare_panels.py"
click node_organization "https://github.com/rikixy/virtual-staining/blob/main/virtual_staining/applications/organize.py"
click node_queue "https://github.com/rikixy/virtual-staining/blob/main/virtual_staining/applications/run_queue.py"
click node_status "https://github.com/rikixy/virtual-staining/blob/main/virtual_staining/applications/status.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_pipeline,node_config,node_preparation,node_data,node_experiment,node_user toneBlue
class node_training,node_trainer,node_methods,node_models,node_checkpoints,node_inference,node_inference_runtime,node_single_inference,node_artifacts toneAmber
class node_evaluation,node_metrics,node_reports,node_comparison toneMint
class node_conversion,node_panels,node_organization,node_queue,node_status toneRose
```

## Components

### Run Workflow

- [Stage Orchestrator](https://github.com/rikixy/virtual-staining/blob/main/virtual_staining/applications/pipeline.py): `virtual_staining/applications/pipeline.py`
- [Run Configuration](https://github.com/rikixy/virtual-staining/blob/main/virtual_staining/config/run.py): `virtual_staining/config/run.py`
- [Dataset Preparation](https://github.com/rikixy/virtual-staining/blob/main/virtual_staining/applications/prepare.py): `virtual_staining/applications/prepare.py`
- [Slide Data Processing](https://github.com/rikixy/virtual-staining/tree/main/virtual_staining/data): `virtual_staining/data`
- [Run Session](https://github.com/rikixy/virtual-staining/blob/main/virtual_staining/experiment/session.py): `virtual_staining/experiment/session.py`

### Translation Runtime

- [Model Training](https://github.com/rikixy/virtual-staining/blob/main/virtual_staining/applications/train.py): `virtual_staining/applications/train.py`
- [Training Runtime](https://github.com/rikixy/virtual-staining/blob/main/virtual_staining/training/trainer.py): `virtual_staining/training/trainer.py`
- [Translation Methods](https://github.com/rikixy/virtual-staining/tree/main/virtual_staining/methods): `virtual_staining/methods`
- [Network Components](https://github.com/rikixy/virtual-staining/tree/main/virtual_staining/models): `virtual_staining/models`
- [Checkpoint Selection](https://github.com/rikixy/virtual-staining/blob/main/virtual_staining/checkpoint_selection.py): `virtual_staining/checkpoint_selection.py`
- [Run Inference](https://github.com/rikixy/virtual-staining/blob/main/virtual_staining/applications/infer.py): `virtual_staining/applications/infer.py`
- [Inference Runner](https://github.com/rikixy/virtual-staining/blob/main/virtual_staining/inference/runner.py): `virtual_staining/inference/runner.py`
- [Image Inference](https://github.com/rikixy/virtual-staining/blob/main/virtual_staining/inference/single.py): `virtual_staining/inference/single.py`
- [Generated Artifacts](https://github.com/rikixy/virtual-staining/blob/main/virtual_staining/inference/outputs.py): `virtual_staining/inference/outputs.py`

### Evaluation

- [Run Evaluation](https://github.com/rikixy/virtual-staining/blob/main/virtual_staining/applications/evaluate.py): `virtual_staining/applications/evaluate.py`
- [Image Metrics](https://github.com/rikixy/virtual-staining/blob/main/virtual_staining/metrics.py): `virtual_staining/metrics.py`
- [Evaluation Reports](https://github.com/rikixy/virtual-staining/blob/main/virtual_staining/evaluation/reports.py): `virtual_staining/evaluation/reports.py`
- [Run Comparison](https://github.com/rikixy/virtual-staining/blob/main/virtual_staining/applications/compare.py): `virtual_staining/applications/compare.py`

### Run Utilities

- [TIFF Conversion](https://github.com/rikixy/virtual-staining/blob/main/virtual_staining/applications/convert.py): `virtual_staining/applications/convert.py`
- [Comparison Panels](https://github.com/rikixy/virtual-staining/blob/main/virtual_staining/applications/compare_panels.py): `virtual_staining/applications/compare_panels.py`
- [Output Organization](https://github.com/rikixy/virtual-staining/blob/main/virtual_staining/applications/organize.py): `virtual_staining/applications/organize.py`
- [Queued Runs](https://github.com/rikixy/virtual-staining/blob/main/virtual_staining/applications/run_queue.py): `virtual_staining/applications/run_queue.py`
- [Dependency Status](https://github.com/rikixy/virtual-staining/blob/main/virtual_staining/applications/status.py): `virtual_staining/applications/status.py`

### Other components

- **User**

## Connections

- User → Stage Orchestrator: runs stages
- Stage Orchestrator → Run Configuration: loads config
- Stage Orchestrator → Dataset Preparation: dispatches prepare
- Stage Orchestrator → Model Training: dispatches train
- Stage Orchestrator → Run Inference: dispatches infer
- Stage Orchestrator → Run Evaluation: dispatches evaluate
- Dataset Preparation → Slide Data Processing: builds patches
- Model Training → Training Runtime: starts training
- Training Runtime → Translation Methods: uses method
- Translation Methods → Network Components: constructs networks
- Run Inference → Inference Runner: runs inference
- Inference Runner → Checkpoint Selection: selects checkpoint
- Inference Runner → Translation Methods: builds predictor
- Inference Runner → Generated Artifacts: writes outputs
- User → Image Inference: infers images
- Image Inference → Generated Artifacts: writes outputs
- Run Evaluation → Image Metrics: computes metrics
- Run Evaluation → Evaluation Reports: writes reports
- User → Run Comparison: compares runs
- User → TIFF Conversion: converts TIFFs
- User → Comparison Panels: builds panels
- User → Output Organization: organizes outputs
- User → Queued Runs: queues runs
- Queued Runs → Stage Orchestrator: dispatches stages
- User → Dependency Status: checks dependencies