# mouseland/cellpose architecture

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

- Interactive diagram: https://gitdiagram.com/mouseland/cellpose
- Repository: https://github.com/mouseland/cellpose

## Overview

##### Project Type & Purpose
- Cellpose is a specialized deep-learning image segmentation tool used primarily for cell and nucleus segmentation with added functionality for image restoration. The README and file layout confirm that it is a research/production hybrid tool with both a graphical user interface (GUI) and command-line interface (CLI), and it supports training, inference, and even distributed segmentation.
- The project also supports various modes (e.g., 2D, 3D segmentation) and human-in-the-loop workflows, meaning the segmentation engine is highly modular and extendable.

##### Analyzing the File Structure
- Top-level directories:
- The “cellpose” directory contains the core modules (e.g., core.py, models.py, transforms.py) and GUI components in “cellpose/gui”.
- “notebooks” provides example usage and interactive demos.
- “paper” holds experimental or supplementary code related to different research versions.
- “pyinstaller” includes files and scripts for building distributable executables.
- “tests” groups unit tests for various components.
- Configuration files such as .github workflows, environment.yml, setup.py, and readthedocs configuration files indicate structured deployment, testing, and documentation practices.
- Architectural patterns are reflected in the separation between UI components, processing/inference modules, training pipelines, and utilities for I/O and metrics.

##### Main Components
a. User Interface Layer:
- GUI: Located in cellpose/gui (includes modules for window layout, menus, training help, etc.).
- CLI/Entry Points: Files like cellpose/__main__.py and cellpose/cli.py that allow execution via command line.
b. Core Processing Engine:
- Core segmentation logic: cellpose/core.py, cellpose/dynamics.py.
- Model Inference: cellpose/models.py, resnet_torch.py, segformer.py – these load pre-trained models and perform predictions.
- Pre-processing & Transformations: modules such as transforms.py and utils.py.
c. Training Pipeline:
- Training-related scripts: cellpose/train.py and additional scripts in the “paper” directories for training variations.
- Human-in-the-loop training flow supported by the GUI and additional helper functions.
d. Data/Input/Output Management:
- I/O Operations: cellpose/io.py and the GUI submodule “io.py” handle image importing, drag-and-drop, and exporting segmentation results.
- External file converters: e.g., imagej_roi_converter.py.
e. Supporting/Extra Components:
- Distributed segmentation: cellpose/contrib/distributed_segmentation.py for handling big data.
- Metrics & plotting: cellpose/metrics.py and cellpose/plot.py for performance and output visualization.
- Testing and configuration: the tests/ folder, GitHub workflows, and environment/configuration files ensure quality and reproducibility.

##### Representing Relationships & Data Flow
- Data input path: From raw image files → Pre-processing (transforms, I/O) → Inference (loaded models) → Post-processing (metrics, plotting) → Output (segmented images, ROIs).

##### Visualizing Technologies & Architectural Patterns
- Top Layer: Frontend / Interaction (GUI and CLI)
- Middle Layer: Business Logic / Core Processing (segmentation engine, pre/post processing, and training logic)
- Bottom Layer: Data Management and External Libraries (file I/O, model management, external dependencies)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Interface Layer
    subgraph "User Interface Layer"
        GUI["GUI (cellpose/gui)"]:::ui
        CLI_Main["CLI (__main__.py)"]:::ui
        CLI_Entry["CLI (cli.py)"]:::ui
    end

    %% Core Processing Engine
    subgraph "Core Processing Engine"
        PreProc["Pre-processing & Transformations (transforms.py & utils.py)"]:::core
        SegLogic["Segmentation Logic (core.py & dynamics.py)"]:::core
        ModelInf["Model Inference (models.py, resnet_torch.py, segformer.py)"]:::core
    end

    %% Training Pipeline
    subgraph "Training Pipeline"
        TrainPipe["Training Pipeline (train.py)"]:::train
        TrainScripts["Training Scripts (paper/1.0, 2.0, 3.0)"]:::train
    end

    %% Data/Input/Output Management
    subgraph "Data/Input/Output Management"
        IOMgmt["I/O Management (io.py, gui/io.py & imagej_roi_converter.py)"]:::io
    end

    %% Distributed Segmentation Support
    subgraph "Distributed Segmentation"
        DistSeg["Distributed Segmentation (contrib/distributed_segmentation.py)"]:::dist
    end

    %% Metrics & Plotting
    subgraph "Metrics & Plotting"
        Metrics["Metrics (metrics.py)"]:::metrics
        Plot["Plotting (plot.py)"]:::metrics
    end

    %% Testing & Configuration
    Testing["Testing & Configuration (tests/ & config files)"]:::test

    %% External Dependencies (represented as a side component)
    ExtDep["External Dependencies (PyTorch, PyQt, NumPy)"]:::ext

    %% Connections: User Interface triggers actions in Core Processing and Training Pipeline
    GUI -->|"triggers"| SegLogic
    CLI_Main -->|"triggers"| SegLogic
    CLI_Entry -->|"triggers"| SegLogic
    GUI -->|"initiates"| TrainPipe
    CLI_Main -->|"initiates"| TrainPipe
    CLI_Entry -->|"initiates"| TrainPipe

    %% Data flow from I/O to Pre-processing then Core Processing
    IOMgmt -->|"provides data"| PreProc
    PreProc -->|"processed data"| SegLogic
    SegLogic -->|"inference results"| ModelInf

    %% Training Pipeline interaction with Core Processing (feedback loop)
    TrainPipe <-->|"updates"| SegLogic
    TrainScripts -->|"supplements"| TrainPipe

    %% Post-processing: Model Inference leads to Metrics and Plotting
    ModelInf -->|"outputs"| Metrics
    ModelInf -->|"outputs"| Plot
    %% Distributed segmentation can augment core processing
    DistSeg -->|"assists"| SegLogic

    %% External dependencies support UI and Core Processing
    ExtDep --- GUI
    ExtDep --- SegLogic

    %% Testing & Configuration monitors the overall system
    Testing --- SegLogic
    Testing --- TrainPipe
    Testing --- IOMgmt

    %% Click Events for Component Mapping
    click GUI "https://github.com/mouseland/cellpose/tree/main/cellpose/gui"
    click CLI_Main "https://github.com/mouseland/cellpose/blob/main/cellpose/__main__.py"
    click CLI_Entry "https://github.com/mouseland/cellpose/blob/main/cellpose/cli.py"
    click SegLogic "https://github.com/mouseland/cellpose/blob/main/cellpose/core.py"
    click SegLogic "https://github.com/mouseland/cellpose/blob/main/cellpose/dynamics.py"
    click ModelInf "https://github.com/mouseland/cellpose/blob/main/cellpose/models.py"
    click ModelInf "https://github.com/mouseland/cellpose/blob/main/cellpose/resnet_torch.py"
    click ModelInf "https://github.com/mouseland/cellpose/blob/main/cellpose/segformer.py"
    click PreProc "https://github.com/mouseland/cellpose/blob/main/cellpose/transforms.py"
    click PreProc "https://github.com/mouseland/cellpose/blob/main/cellpose/utils.py"
    click TrainPipe "https://github.com/mouseland/cellpose/blob/main/cellpose/train.py"
    click TrainScripts "https://github.com/mouseland/cellpose/blob/main/paper/1.0/train_maskrcnn.py"
    click TrainScripts "https://github.com/mouseland/cellpose/blob/main/paper/2.0/train_specialists.py"
    click TrainScripts "https://github.com/mouseland/cellpose/blob/main/paper/2.0/train_subsets.py"
    click TrainScripts "https://github.com/mouseland/cellpose/blob/main/paper/3.0/train_subsets.py"
    click IOMgmt "https://github.com/mouseland/cellpose/blob/main/cellpose/io.py"
    click IOMgmt "https://github.com/mouseland/cellpose/blob/main/cellpose/gui/io.py"
    click IOMgmt "https://github.com/mouseland/cellpose/blob/main/imagej_roi_converter.py"
    click DistSeg "https://github.com/mouseland/cellpose/blob/main/cellpose/contrib/distributed_segmentation.py"
    click Metrics "https://github.com/mouseland/cellpose/blob/main/cellpose/metrics.py"
    click Plot "https://github.com/mouseland/cellpose/blob/main/cellpose/plot.py"
    click Testing "https://github.com/mouseland/cellpose/tree/main/tests/"

    %% Styles
    classDef ui fill:#fff2e6,stroke:#e69500,stroke-width:2px;
    classDef core fill:#e6f7ff,stroke:#0080ff,stroke-width:2px;
    classDef train fill:#e6ffe6,stroke:#33cc33,stroke-width:2px;
    classDef io fill:#f9e6ff,stroke:#cc33ff,stroke-width:2px;
    classDef dist fill:#ffe6f2,stroke:#ff66a3,stroke-width:2px;
    classDef metrics fill:#f2ffe6,stroke:#99cc00,stroke-width:2px;
    classDef test fill:#ffe6cc,stroke:#ff9933,stroke-width:2px;
    classDef ext fill:#e6e6e6,stroke:#808080,stroke-width:2px;
```
