# waldstrom/collembot architecture

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

- Interactive diagram: https://gitdiagram.com/waldstrom/collembot
- Repository: https://github.com/waldstrom/collembot

## Overview

COLLEMBOT is a research toolkit for preparing and training Collembola segmentation models, benchmarking alternative backbones, and counting organisms in soil-slide images. The main user workflow runs configured slide images through tiling and filtering, model inference, polygon assembly and fusion, then produces counts, metrics, and visualizations. Training and comparative benchmarking are separate workflows; image upscaling and an interactive Gradio demo are optional capabilities. The inference excerpts are partial, so documented stages are represented, but uncertain internal call links are omitted or marked unverified.

Main entry points: [`scripts/compare_models.py`](https://github.com/waldstrom/collembot/blob/main/scripts/compare_models.py) (Benchmark Runner), [`scripts/train_model.py`](https://github.com/waldstrom/collembot/blob/main/scripts/train_model.py) (Dataset Preparation), [`scripts/run_inference.py`](https://github.com/waldstrom/collembot/blob/main/scripts/run_inference.py) (Tile & Filter), [`scripts/upscale_images.py`](https://github.com/waldstrom/collembot/blob/main/scripts/upscale_images.py) (Image Upscaling)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_inference["Slide Inference"]
  node_inference_config["Inference Settings<br/>[inference.yaml]"]
  node_tile_filter["Tile &amp; Filter<br/>[run_inference.py]"]
  node_yolo_infer["YOLO Inference<br/>[run_inference.py]"]
  node_polygon_assembly["Polygon Assembly<br/>[run_inference.py]"]
  node_fusion["Polygon Fusion<br/>[run_inference.py]"]
  node_metrics_viz["Metrics &amp; Viz<br/>[run_inference.py]"]
end

subgraph group_training["Dataset Training"]
  node_training_config["Training Settings<br/>[train.yaml]"]
  node_label_data["LabelMe Data"]
  node_dataset_prep["Dataset Preparation<br/>[train_model.py]"]
  node_data_splits["Data Splits<br/>[train_model.py]"]
  node_yolo_training["YOLO Training<br/>[train_model.py]"]
  node_model_evaluation["Model Evaluation<br/>[train_model.py]"]
end

subgraph group_benchmark["Model Benchmarking"]
  node_multirun_config["Sweep Settings"]
  node_benchmark_runner["Benchmark Runner<br/>[compare_models.py]"]
  node_detectron_batching["VRAM Batch Sizing"]
end

subgraph group_utilities["Optional Tools"]
  node_upscaler["Image Upscaling<br/>[upscale_images.py]"]
  node_gradio_demo["Gradio Demo<br/>[gradio_app.py]"]
end

node_researcher(("Researcher"))
node_slides["Slide Images"]
node_backbones["Segmentation Backbones"]

node_researcher -->|"runs inference"| node_tile_filter
node_slides -->|"provides images"| node_tile_filter
node_inference_config -->|"configures"| node_tile_filter
node_tile_filter -.->|"selects tiles"| node_yolo_infer
node_yolo_infer -.->|"produces detections"| node_polygon_assembly
node_polygon_assembly -.->|"assembles polygons"| node_fusion
node_fusion -.->|"feeds results"| node_metrics_viz
node_label_data -->|"provides annotations"| node_dataset_prep
node_training_config -->|"configures"| node_dataset_prep
node_researcher -->|"starts training"| node_dataset_prep
node_dataset_prep -->|"prepares samples"| node_data_splits
node_data_splits -.->|"supplies splits"| node_yolo_training
node_yolo_training -->|"evaluates checkpoint"| node_model_evaluation
node_researcher -->|"starts comparison"| node_benchmark_runner
node_multirun_config -->|"configures sweeps"| node_benchmark_runner
node_benchmark_runner -->|"reuses preparation"| node_dataset_prep
node_benchmark_runner -->|"uses batch sizing"| node_detectron_batching
node_benchmark_runner -->|"benchmarks"| node_backbones
node_researcher -->|"optionally upscales"| node_upscaler
node_upscaler -.->|"writes enlarged images"| node_slides
node_researcher -->|"opens demo"| node_gradio_demo

click node_slides "https://github.com/waldstrom/collembot/tree/main/data/inference-examples"
click node_inference_config "https://github.com/waldstrom/collembot/blob/main/configs/inference.yaml"
click node_tile_filter "https://github.com/waldstrom/collembot/blob/main/scripts/run_inference.py"
click node_yolo_infer "https://github.com/waldstrom/collembot/blob/main/scripts/run_inference.py"
click node_polygon_assembly "https://github.com/waldstrom/collembot/blob/main/scripts/run_inference.py"
click node_fusion "https://github.com/waldstrom/collembot/blob/main/scripts/run_inference.py"
click node_metrics_viz "https://github.com/waldstrom/collembot/blob/main/scripts/run_inference.py"
click node_training_config "https://github.com/waldstrom/collembot/blob/main/configs/train.yaml"
click node_label_data "https://github.com/waldstrom/collembot/tree/main/data"
click node_dataset_prep "https://github.com/waldstrom/collembot/blob/main/scripts/train_model.py"
click node_data_splits "https://github.com/waldstrom/collembot/blob/main/scripts/train_model.py"
click node_yolo_training "https://github.com/waldstrom/collembot/blob/main/scripts/train_model.py"
click node_model_evaluation "https://github.com/waldstrom/collembot/blob/main/scripts/train_model.py"
click node_multirun_config "https://github.com/waldstrom/collembot/blob/main/configs/train_multirun.yaml"
click node_benchmark_runner "https://github.com/waldstrom/collembot/blob/main/scripts/compare_models.py"
click node_detectron_batching "https://github.com/waldstrom/collembot/blob/main/scripts/detectron_batching.py"
click node_upscaler "https://github.com/waldstrom/collembot/blob/main/scripts/upscale_images.py"
click node_gradio_demo "https://github.com/waldstrom/collembot/blob/main/scripts/gradio_app.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_inference_config,node_tile_filter,node_yolo_infer,node_polygon_assembly,node_fusion,node_metrics_viz toneBlue
class node_training_config,node_label_data,node_dataset_prep,node_data_splits,node_yolo_training,node_model_evaluation toneAmber
class node_multirun_config,node_benchmark_runner,node_detectron_batching toneMint
class node_upscaler,node_gradio_demo toneRose
class node_researcher,node_backbones toneIndigo
class node_slides toneTeal
```

## Components

### Slide Inference

- [Inference Settings](https://github.com/waldstrom/collembot/blob/main/configs/inference.yaml): `configs/inference.yaml`
- [Tile & Filter](https://github.com/waldstrom/collembot/blob/main/scripts/run_inference.py): `scripts/run_inference.py`
- [YOLO Inference](https://github.com/waldstrom/collembot/blob/main/scripts/run_inference.py): `scripts/run_inference.py`
- [Polygon Assembly](https://github.com/waldstrom/collembot/blob/main/scripts/run_inference.py): `scripts/run_inference.py`
- [Polygon Fusion](https://github.com/waldstrom/collembot/blob/main/scripts/run_inference.py): `scripts/run_inference.py`
- [Metrics & Viz](https://github.com/waldstrom/collembot/blob/main/scripts/run_inference.py): `scripts/run_inference.py`

### Dataset Training

- [Training Settings](https://github.com/waldstrom/collembot/blob/main/configs/train.yaml): `configs/train.yaml`
- [LabelMe Data](https://github.com/waldstrom/collembot/tree/main/data): `data`
- [Dataset Preparation](https://github.com/waldstrom/collembot/blob/main/scripts/train_model.py): `scripts/train_model.py`
- [Data Splits](https://github.com/waldstrom/collembot/blob/main/scripts/train_model.py): `scripts/train_model.py`
- [YOLO Training](https://github.com/waldstrom/collembot/blob/main/scripts/train_model.py): `scripts/train_model.py`
- [Model Evaluation](https://github.com/waldstrom/collembot/blob/main/scripts/train_model.py): `scripts/train_model.py`

### Model Benchmarking

- [Sweep Settings](https://github.com/waldstrom/collembot/blob/main/configs/train_multirun.yaml): `configs/train_multirun.yaml`
- [Benchmark Runner](https://github.com/waldstrom/collembot/blob/main/scripts/compare_models.py): `scripts/compare_models.py`
- [VRAM Batch Sizing](https://github.com/waldstrom/collembot/blob/main/scripts/detectron_batching.py): `scripts/detectron_batching.py`

### Optional Tools

- [Image Upscaling](https://github.com/waldstrom/collembot/blob/main/scripts/upscale_images.py): `scripts/upscale_images.py`
- [Gradio Demo](https://github.com/waldstrom/collembot/blob/main/scripts/gradio_app.py): `scripts/gradio_app.py`

### Other components

- **Researcher**
- [Slide Images](https://github.com/waldstrom/collembot/tree/main/data/inference-examples): `data/inference-examples`
- **Segmentation Backbones**

## Connections

- Researcher → Tile & Filter: runs inference (evidence: `README.md`)
- Slide Images → Tile & Filter: provides images (evidence: `README.md`)
- Inference Settings → Tile & Filter: configures (evidence: `README.md`)
- Tile & Filter → YOLO Inference: selects tiles (evidence: `scripts/run_inference.py`)
- YOLO Inference → Polygon Assembly: produces detections (evidence: `scripts/run_inference.py`)
- Polygon Assembly → Polygon Fusion: assembles polygons (evidence: `scripts/run_inference.py`)
- Polygon Fusion → Metrics & Viz: feeds results (evidence: `scripts/run_inference.py`)
- LabelMe Data → Dataset Preparation: provides annotations (evidence: `README.md`)
- Training Settings → Dataset Preparation: configures (evidence: `README.md`)
- Researcher → Dataset Preparation: starts training (evidence: `README.md`)
- Dataset Preparation → Data Splits: prepares samples (evidence: `scripts/train_model.py`)
- Data Splits → YOLO Training: supplies splits (evidence: `scripts/train_model.py`)
- YOLO Training → Model Evaluation: evaluates checkpoint (evidence: `scripts/train_model.py`)
- Researcher → Benchmark Runner: starts comparison (evidence: `README.md`)
- Sweep Settings → Benchmark Runner: configures sweeps (evidence: `README.md`)
- Benchmark Runner → Dataset Preparation: reuses preparation (evidence: `scripts/compare_models.py`)
- Benchmark Runner → VRAM Batch Sizing: uses batch sizing (evidence: `scripts/compare_models.py`)
- Benchmark Runner → Segmentation Backbones: benchmarks (evidence: `README.md`)
- Researcher → Image Upscaling: optionally upscales (evidence: `README.md`)
- Image Upscaling → Slide Images: writes enlarged images
- Researcher → Gradio Demo: opens demo (evidence: `README.md`)
