PatchPerPix for Instance Segmentation

This repository is the official implementation of PatchPerPix for Instance Segmentation.

Lisa Mais¹, Peter Hirsch¹, Dagmar Kainmueller, ECCV2020
¹Authors contributed equally, listed in random order

Abstract

We present a novel method for proposal free instance segmentation that can handle sophisticated object shapes that span large parts of an image and form dense object clusters with crossovers. Our method is based on predicting dense local shape descriptors, which we assemble to form instances. All instances are assembled simultaneously in one go. To the best of our knowledge, our method is the first non-iterative method that yields instances that are composed of learnt shape patches. We evaluate our method on a diverse range of data domains, where it defines the new state of the art on four benchmarks, namely the ISBI 2012 EM segmentation benchmark, the BBBC010 C. elegans dataset, and 2d as well as 3d fluorescence microscopy datasets of cell nuclei. We show furthermore that our method also applies to 3d light microscopy data of drosophila neurons, which exhibit extreme cases of complex shape clusters.

Installation

This package requires Python 3 and PyTorch.

Note Previous versions (e.g., for the experiments published in our ECCV 2020 paper) require TensorFlow 1.x. If you want to run older experiments please checkout the respective tag: eccv2020 If you have any questions, please open an issue (and mention that you're running the older code)

The recommended way is to install the package into your conda/python virtual environment. We recommend to use conda to install torch (tested with torch 1.13, but newer versions should work, too). The following instructions were tested on linux/ubuntu 20.04.

conda create --name ppp --yes
conda activate ppp
conda install python=3.9 pytorch-cuda torchvision torchaudio cudatoolkit -c pytorch -c nvidia --yes
git clone https://github.com/Kainmueller-Lab/PatchPerPix.git
cd PatchPerPix
PATH=/usr/local/cuda/bin:$PATH CUDA_ROOT=/usr/local/cuda pip install -e .

Organization

• PatchPerPix: contains the code for our instance assembly pipeline to go from predictions to instances
• experiments: contains the training and prediction code to generate predictions and the main script; contains one sub-folder per application/dataset
  • run_ppp.py:
  • main script to run the experiments
  • command line arguments are used to select the experiment and the sub-task to be executed (training, inference etc, see below for an example)
  • the parameters for the network training and the postprocessing have to be defined in a config file (example config file)
  • flylight: an example experiment for the FlyLight Instances Segmentation Benchmark Dataset
  • setups: here the different experiment setups are placed, the python scripts should not be called manually, but will be called by the main script
    • train.py: trains the network
    • predict_no_gp.py: prediction after training
    • decode.py: if ppp+dec is used, decode the predicted patch encodings to the full patches
    • default.toml: example configuration file
    • default_train_code.toml: example configuration file that uses ppp+dec
    • torch_loss.py: auxiliary file for the loss computation
    • torch_model.py: auxiliary file for the torch model definition

Data preparation

The code expects the data to be in the zarr format (https://zarr.readthedocs.io/en/stable/). It is similar to hdf5, but uses the underlying file system to enable parallel read and write). It expects all used arrays (e.g., raw image data and labels) to be placed in a single zarr file (organized into a hierarchy via groups, see zarr documentation). The names of the arrays have to be set in the config file (e.g., raw_key and gt_key) appropriately (example zarr file).

Usage

The main script run_ppp.py (in the experiments folder) can be used to control all aspects of the experiments.

Example call:

python run_ppp.py --setup setup01 --config flylight/setups/setup01/default_train_code.toml --do train validate_checkpoints predict decode label evaluate --app flylight --root ppp_experiments

With --do TASK you can set the sub-task that should be executed (or all for the whole pipeline), --root PATH sets the output directory, --app APP the experiment (e.g. flylight) and --setup SETUP the specific setup of that experiment (e.g. setup01).

The command above creates a time stamped experiment folder under the path specified by --root. To continue training or for further validation or evaluation adapt the command. Change the --config parameter to point to the config file in the created experiment folder and remove the --root flag and replace it with the -id flag and point it to the created experiment folder. The tasks specified after --do depend on what you want to do:

python run_ppp.py --setup setup01 --config ppp_experiments/flylight_setup01_230614__123456/config.toml --do  validate_checkpoints predict decode label evaluate --app wormbodies -id experiments/flylight_setup01_230614__123456

Available Sub-Tasks

Results

(for more details on the results see PatchPerPix for Instance Segmentation)

BBBC010

(BBBC010: C. elegans live/dead assay)
($S = \frac{TP}{TP+FP+FN}$; TP, FP, FN computed per image; averaged across images; localized using IoU)

[1] results from: Instance Segmentation of Dense and Overlapping Objects via Layering

ISBI2012

(server with leaderboard is down, but data is still available: ISBI 2012 Segmentation Challenge

[2] results from leaderboard (offline, see also The Mutex Watershed: Efficient, Parameter-Free Image Partitioning)

dsb2018

(Kaggle 2018 Data Science Bowl, train/val/test split defined by Cell Detection with Star-convex Polygons)
($S = \frac{TP}{TP+FP+FN}$; TP, FP, FN computed per image; averaged across images; localized using IoU)

[3] results from Cell Detection with Star-convex Polygons

nuclei3d

(https://doi.org/10.5281/zenodo.5942574, train/val/test split defined by Star-convex Polyhedra for 3D Object Detection and Segmentation in Microscopy)
($S = \frac{TP}{TP+FP+FN}$; TP, FP, FN computed per image; averaged across images; localized using IoU)

[4] Large Scale Image Segmentation with Structured Loss based Deep Learning for Connectome Reconstruction, we computed the results
[5] results from Star-convex Polyhedra for 3D Object Detection and Segmentation in Microscopy
[6] results from An Auxiliary Task for Learning Nuclei Segmentation in 3D Microscopy Images

FlyLight

(The FlyLight Instance Segmentation Datset, train/val/test split defined by tba)

(for a precise definition see tba)

Contributing

If you would like to contribute, have encountered any issues or have any suggestions, please open an issue on this GitHub repository.

All contributions are welcome! The content in this repository is licensed under the MIT license.