# digitalpathologybern/hover_next_inference architecture

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

- Interactive diagram: https://gitdiagram.com/digitalpathologybern/hover_next_inference
- Repository: https://github.com/digitalpathologybern/hover_next_inference

## Overview

##### Project type and purpose
- This is a Python‐based, command‐line inference pipeline (not a web app) for nuclei segmentation and classification in whole‐slide and image files (JPEG/PNG/NPY/ZARR).
- It’s organized as an open‐source tool, with a single “main.py” entry point driving a modular, multi‐stage processing pipeline.

##### File structure
Top‐level:
- main.py      – CLI launcher that parses arguments (input path, model checkpoint, TTA, workers, tiling, etc.)
- environment.yml, requirements.txt, setup.py – Conda/Pip environment definitions, packaging info
- sample_analysis.ipynb – downstream‐analysis example using pipeline outputs
- .github/workflows/build.yml – CI for building/testing
- LICENSE, README.md

src/ (core pipeline modules):
- data_utils.py – implements data loaders for WSI (OpenSlide), image, NPY, custom datatypes
- spatial_augmenter.py, augmentations.py – test‐time augmentation (TTA) and other transforms
- multi_head_unet.py – defines the segmentation/classification model architecture (U-Net variant)
- inference.py – orchestrates batched/TTA inference on patches, manages GPU workers
- post_process.py, post_process_utils.py – merges tile predictions, instance‐map generation, class lookup table, export TSVs
- viz_utils.py – visualization helpers for debugging or output previews
- constants.py – shared config values (tile sizes, class labels, etc.)

##### Key README insights
- Supports auto‐download of pretrained weights from Zenodo
- CLI flags split pre-processing (tiling), inference (GPU), post-processing (CPU/multi-machine)
- Slurm support via “--only_inference” for GPU utilization
- Docker/Singularity container instructions

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% CLI Stage
    CLI["CLI Interface\n(main.py)"]:::io
    CLI -->|"input path, flags"| InputMgr

    %% Input Stage
    InputMgr["Input Manager\n(File Type Detector)"]:::io
    InputMgr -->|"SVS/PNG/NPY/ZARR"| StorageIn
    StorageIn[(Input Files)]:::storage
    InputMgr -->|"delegates"| DataLoaders

    %% Pre-processing Stage
    subgraph "Pre-processing Module"
        direction TB
        Tiling["Tiling Engine\n(src/spatial_augmenter.py)"]:::compute
        Augment["Spatial Augmentations\n(src/augmentations.py)"]:::compute
        Tiling -->|"patches\n(tile size)"| Augment
    end
    DataLoaders["DataLoaders\n(src/data_utils.py)"]:::io
    DataLoaders -->|"raw arrays"| Tiling

    %% Inference Stage
    subgraph "Inference Engine"
        direction TB
        ModelLoader["Model Loader\n(src/multi_head_unet.py)"]:::compute
        GPUPool["GPU Worker Pool\n(src/inference.py)"]:::compute
        ModelLoader -->|"model weights"| GPUPool
        Augment -->|"16 inf_workers\npatches"| GPUPool
    end

    %% Post-processing Stage
    subgraph "Post-processing Module"
        direction TB
        Merger["Tile Merger & Instance Map\n(src/post_process.py)"]:::post
        Utils["Post-process Utils\n(src/post_process_utils.py)"]:::post
        GPUPool -->|"predictions"| Merger
        Merger -->|"LUT, TSV"| Utils
    end

    %% Output Stage
    Utils -->|"exports\nTSV, images, Zarr"| StorageOut
    StorageOut[(Output Folder)]:::storage

    %% Visualization & Config
    Viz["Visualization Helpers\n(src/viz_utils.py)"]:::io
    Const["Constants\n(src/constants.py)"]:::io

    Merger -->|"debug previews"| Viz
    CLI -->|"reads flags"| Const
    Utils -->|"reads config"| Const

    %% External Services
    Zenodo["Zenodo Weight Repo"]:::ext
    Docker["Docker/Singularity"]:::ext
    Slurm["Slurm Scheduler"]:::ext

    ModelLoader -->|"auto-download"| Zenodo
    CLI -->|"optional container runtime"| Docker
    CLI -->|"--only_inference"| Slurm

    %% Storage Paths
    StorageIn --> StorageOut

    %% Legend
    subgraph Legend
        direction TB
        IO["I/O Modules"]:::io
        Compute["Compute Modules"]:::compute
        Post["Post-processing"]:::post
        Ext["External Services"]:::ext
        Stor["Storage"]:::storage
    end

    %% Click Events
    click CLI "https://github.com/digitalpathologybern/hover_next_inference/blob/main/main.py"
    click DataLoaders "https://github.com/digitalpathologybern/hover_next_inference/blob/main/src/data_utils.py"
    click Tiling "https://github.com/digitalpathologybern/hover_next_inference/blob/main/src/spatial_augmenter.py"
    click Augment "https://github.com/digitalpathologybern/hover_next_inference/blob/main/src/augmentations.py"
    click ModelLoader "https://github.com/digitalpathologybern/hover_next_inference/blob/main/src/multi_head_unet.py"
    click GPUPool "https://github.com/digitalpathologybern/hover_next_inference/blob/main/src/inference.py"
    click Merger "https://github.com/digitalpathologybern/hover_next_inference/blob/main/src/post_process.py"
    click Utils "https://github.com/digitalpathologybern/hover_next_inference/blob/main/src/post_process_utils.py"
    click Viz "https://github.com/digitalpathologybern/hover_next_inference/blob/main/src/viz_utils.py"
    click Const "https://github.com/digitalpathologybern/hover_next_inference/blob/main/src/constants.py"

    %% Styles
    classDef io fill:#a6cee3,stroke:#333,stroke-width:1px
    classDef compute fill:#b2df8a,stroke:#333,stroke-width:1px
    classDef post fill:#fdbf6f,stroke:#333,stroke-width:1px
    classDef ext fill:#fb9a99,stroke:#333,stroke-width:1px
    classDef storage fill:#cab2d6,stroke:#333,stroke-width:1px
```
