# alleninstitute/aics-segmentation architecture

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

- Interactive diagram: https://gitdiagram.com/alleninstitute/aics-segmentation
- Repository: https://github.com/alleninstitute/aics-segmentation

## Overview

##### Project type and purpose
- This is an open-source Python toolkit (“Allen Cell Structure Segmenter”) for 3D segmentation of intracellular structures in fluorescence microscopy images.
- It provides (a) a classic image segmentation workflow (lookup-table of parameterized algorithms) and (b) human-in-the-loop ground-truth generation for deep learning (separate repo).

##### File structure
- Top-level scripts & configs: setup.py, setup.cfg, build.gradle, Jenkinsfile, .gitignore, LICENSE, README, BUILD.md, CONTRIBUTING.md.
- Core package:
aicssegmentation/
- bin/ – shell & batch wrappers (run_toolkit.sh/.bat, batch_processing.py)
- cli/ – entry-point script(s) (to_analysis.py)
- core/ – segmentation algorithms & utilities (MO_threshold.py, hessian.py, pre_processing_utils.py, output_utils.py, vessel.py, visual.py, etc.)
- structure_wrapper/ – one module per structure type (seg_* files) plus a generic structure_segmenter.py that orchestrates the workflow
- version.py, __init__.py, setting.txt
- Tests: aicssegmentation/tests
- Documentation: docs/ (API, installation, paper supplements)
- Demo data & notebooks: demo_data/ & lookup_table_demo/

##### README for additional insights
- Describes a 3-step classic workflow: preprocess → segment → postprocess
- Points at a “lookup table” of 20 representative workflows (in docs/toolkit_paper_*.pdf) and Jupyter notebooks for experimentation
- Highlights human-in-the-loop curation for iterative model building (outside this repo)
- Emphasizes visualization via itk-jupyter-widgets

##### Main components & their interactions
a. User Interface
– CLI script (aicssegmentation/cli/to_analysis.py)
– Batch script (aicssegmentation/bin/batch_processing.py)
– Jupyter notebooks (lookup_table_demo/) for interactive exploration
b. Core Engine
– Preprocessing utilities (core/pre_processing_utils.py)
– Segmentation algorithms (core/MO_threshold.py, core/hessian.py, core/seg_dot.py, core/vessel.py, etc.)
– Post-processing & output (core/output_utils.py, core/utils.py, core/visual.py)
c. Structure-specific wrappers
– A wrapper for each subcellular structure (structure_wrapper/seg_*.py) implements the 3-step workflow by composing core functions
– structure_segmenter.py loads the correct wrapper based on user input or lookup table
d. Data & Configuration
– Demo microscopy files (demo_data/)
– Parameters & lookup tables in setting.txt, docs/toolkit_paper_*.pdf
e. Visualization & Analysis Bridge
– itk-jupyter-widgets for 3D rendering in notebooks
– object_identification utilities (docs/object_identification.md)

##### Architectural patterns & design principles
- Modular plugin/strategy pattern: each structure_wrapper module adheres to the same interface (preprocess, segment, postprocess) and can be discovered/selected at runtime
- Separation of concerns: CLI & batch scripts orchestrate workflows; core/ contains pure algorithmic logic; structure_wrapper/ binds algorithms with parameters
- Configurable & extensible: setting.txt and lookup tables allow new workflows to be added without changing core code

##### Detail level
- Every major directory/module as a component
- Call out the plugin discovery mechanism in structure_segmenter

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Interfaces
    subgraph "User Interfaces"
        CLI["CLI: to_analysis.py"]:::ui
        Batch["Batch Script: batch_processing.py"]:::ui
        ShellSh["run_toolkit.sh"]:::ui
        ShellBat["run_toolkit.bat"]:::ui
        Notebook["Jupyter Notebook Playground"]:::ui
    end

    %% Structure Wrappers
    subgraph "Structure Wrappers (Plugins)"
        SS["structure_segmenter"]:::plugin
        seg_actb["seg_actb.py"]:::plugin
        seg_npm1["seg_npm1.py"]:::plugin
        seg_others["...seg_*.py"]:::plugin
    end

    %% Core Engine
    subgraph "Core Engine"
        Pre["Preprocessor"]:::core
        Alg1["MO_threshold"]:::core
        Alg2["hessian"]:::core
        Alg3["seg_dot"]:::core
        Alg4["vessel"]:::core
        Post["Postprocessor"]:::core
        Out["Output Utils"]:::core
        Utils["utils.py"]:::core
    end

    %% Data & Config
    subgraph "Data & Config"
        Demo["Demo Data"]:::data
        Setting["setting.txt"]:::data
        PDF1["toolkit_paper_lookup_table_20181206.pdf"]:::data
        PDF2["toolkit_paper_SI_vFinalForBioRxiv.pdf"]:::data
    end

    %% Visualization & Analysis
    subgraph "Visualization & Analysis"
        viz["itk-jupyter-widgets"]:::viz
        ObjId["object_identification.md"]:::viz
    end

    %% Output Store
    Disk(["Output Files"]):::data

    %% Connections
    CLI --> SS
    Batch --> SS
    ShellSh --> SS
    ShellBat --> SS
    Notebook --> SS

    SS --> Pre
    SS -.->|discovers| seg_actb
    SS -.->|discovers| seg_npm1
    SS -.->|discovers| seg_others

    Pre --> Alg1
    Pre --> Alg2
    Pre --> Alg3
    Pre --> Alg4

    Alg1 --> Post
    Alg2 --> Post
    Alg3 --> Post
    Alg4 --> Post

    Post --> Out
    Out --> Disk

    Notebook --> viz
    Notebook --> ObjId

    %% Click Events
    click CLI "https://github.com/alleninstitute/aics-segmentation/blob/master/aicssegmentation/cli/to_analysis.py"
    click Batch "https://github.com/alleninstitute/aics-segmentation/blob/master/aicssegmentation/bin/batch_processing.py"
    click ShellSh "https://github.com/alleninstitute/aics-segmentation/blob/master/aicssegmentation/bin/run_toolkit.sh"
    click ShellBat "https://github.com/alleninstitute/aics-segmentation/blob/master/aicssegmentation/bin/run_toolkit.bat"
    click Pre "https://github.com/alleninstitute/aics-segmentation/blob/master/aicssegmentation/core/pre_processing_utils.py"
    click Alg1 "https://github.com/alleninstitute/aics-segmentation/blob/master/aicssegmentation/core/MO_threshold.py"
    click Alg2 "https://github.com/alleninstitute/aics-segmentation/blob/master/aicssegmentation/core/hessian.py"
    click Alg3 "https://github.com/alleninstitute/aics-segmentation/blob/master/aicssegmentation/core/seg_dot.py"
    click Alg4 "https://github.com/alleninstitute/aics-segmentation/blob/master/aicssegmentation/core/vessel.py"
    click Out "https://github.com/alleninstitute/aics-segmentation/blob/master/aicssegmentation/core/output_utils.py"
    click Utils "https://github.com/alleninstitute/aics-segmentation/blob/master/aicssegmentation/core/utils.py"
    click seg_actb "https://github.com/alleninstitute/aics-segmentation/blob/master/aicssegmentation/structure_wrapper/seg_actb.py"
    click seg_npm1 "https://github.com/alleninstitute/aics-segmentation/blob/master/aicssegmentation/structure_wrapper/seg_npm1.py"
    click SS "https://github.com/alleninstitute/aics-segmentation/blob/master/aicssegmentation/structure_wrapper/structure_segmenter.py"
    click Demo "https://github.com/alleninstitute/aics-segmentation/tree/master/demo_data/"
    click Setting "https://github.com/alleninstitute/aics-segmentation/blob/master/aicssegmentation/setting.txt"
    click PDF1 "https://github.com/alleninstitute/aics-segmentation/blob/master/docs/toolkit_paper_lookup_table_20181206.pdf"
    click PDF2 "https://github.com/alleninstitute/aics-segmentation/blob/master/docs/toolkit_paper_SI_vFinalForBioRxiv.pdf"
    click ObjId "https://github.com/alleninstitute/aics-segmentation/blob/master/docs/object_identification.md"

    %% Styles
    classDef ui fill:#a2fca2,stroke:#333,stroke-width:1px
    classDef core fill:#a2d0f7,stroke:#333,stroke-width:1px
    classDef plugin fill:#f7c877,stroke:#333,stroke-width:1px
    classDef data fill:#d3d3d3,stroke:#333,stroke-width:1px
    classDef viz fill:#c0c0ff,stroke:#333,stroke-width:1px
```
