How alleninstitute/aics-segmentation works
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