EMsegment

A Python package for 3D electron microscopy (EM) image segmentation using deep learning.

Implements a pipeline based on the local shape descriptor (LSDs) library.

See original scripts here: https://github.com/funkelab/lsd/tree/master/lsd/tutorial/scripts

This project is based on scripts by the Funke lab. Also see Acknowledgements section.

Installation

First, clone the repository locally

git clone https://github.com/Heinze-lab/EMsegment.git

Create a new environment and activate it (here using conda)

conda create -n myenv python=3.12
conda activate myenv

Install dependencies and package

pip install -r requirements.txt
pip install -e .

Alternatively, create the environment using the provided environment.yml directly

conda env create --n myenv --file=environment.yml

Installation was tested on Ubuntu 20.04 with Python 3.12.

Requirements

• Python 3.12
• CUDA-capable GPU(s) for prediction
• MongoDB instance for progress tracking

Quick Start

Full Pipeline

python emsegment/Segment.py \
  -p /path/to/project_dir \
  -prefix my_project \
  -i /path/to/input.zarr \
  -m emsegment/config/model_config.json \
  -c 8 \
  --GPU 0 1 \
  --seg-config emsegment/seg_config.json

Key Parameters

Parameter	Description
--GPU	CUDA device ID(s) for prediction
-c	Number of CPU workers for fragments/agglomeration
--chunk-voxel-size	Block size [Z,Y,X] in voxels. Default: [100,500,500]
--roi-start/--roi-size	Process subset of a volume (in world unit)
--continue-previous	Resume interrupted job using the highest ID
--start-over	Clear progress and restart
--todo	Stages of the pipeline to go through (predict, fragment, agglomerate). Default: all stages

For a description of all parameters, run --help.

Configuration

Model Configuration (model_config.json)

The model configuration contains information necessary to build the model and load a trained state.

{
  "model_path": "/path/to/trained_model.pt",
  "num_fmaps": 12,
  "output_shape": [40, 200, 200],
  "padding": [20, 100, 100]
}

Segmentation Configuration (seg_config.json)

The segmentation configuration contains parameters used for each stage of the segmentation pipeline.

{
  "pred_config": {
    "models_per_gpu": 1,
    "num_cache_workers": 4,
    "write_affs": true,
    "write_lsds": false
  },
  "frag_config": {
    "context_px": [10, 50, 50],
    "fragments_in_xy": true,
    "epsilon_agglomerate": 0,
    "filter_fragments": 0,
    "min_seed_distance": 5
  },
  "agglo_config": {
    "threshold": 0.5,
    "edges_collection_basename": "edges",
    "merge_function": "hist_quant_25"
  }
}

Data Format

• Input: Zarr containers with raw EM data
• Predictions: 4D arrays (channels, z, y, x) - 3 channels for affinities, 10 for LSDs
• Fragments: 3D uint64 label arrays
• Agglomeration: Weighted edges stored in MongoDB

Acknowledgments

Built on tools from the Funke Lab:

• lsd - Local shape descriptors
• daisy - Distributed processing
• funlib.persistence - Interface with zarr containers
• funlib.geometry - Coordinates and roi operations

License

MIT License