Difference between revisions of "Interactive Watershed"

(User Interface)
(Scripting: Embed code from github repository)
Line 102: Line 102:
In ImageJ macro language one can perform a H-Watershed segmentation with the following command:
In ImageJ macro language one can perform a H-Watershed segmentation with the following command:
<source lang="java">
hMin = 500;
thresh = 500;
peakFlooding = 80;
run("HWatershed", "impin=2DEmbryoSection_Mette.tif hmin="+hMin+" thresh="+thresh+" peakflooding="+peakFlooding);
In a Jython script the H-Watershed segmentation could be called as follows:
In a Jython script the H-Watershed segmentation could be called as follows:
<source lang="python">
#@ImageJ ij
from ij import IJ
imp =IJ.getImage();
hMin = 500
thresh = 500
peakFlooding = 80
result = ij.op().run("HWatershed", imp, hMin, thresh, peakFlooding );
The run commands are also recorded by the macro recorder when exporting a label map.
The run commands are also recorded by the macro recorder when exporting a label map.

Revision as of 08:52, 6 May 2017

Interactive H-Watershed (ImageJ/Fiji)
Author Benoit Lombardot
Maintainer Benoit Lombardot
File soon on SCF-MPI-CBG update site
Source https://github.com/mpicbg-scicomp/Interactive-H-Watershed
Initial release 05 May 2017
Category Plugins, Segmentation
InteractiveWatershed illustration.PNG
Figure 1 Illustration of the interactive watershed plugin. Showing the plugin control panel in from of a segmentation overlaying raw microspy data. The raw data shows a section of a platynereis organism during its early development. Data were acquired by Mette Handberg-Thorsager (Tomancak lab, MPI-CBG, Dresden)


Watershed [ref Soille] is a common tool to segment objects in an 2D and 3D images. It is relatively fast and can provides understandable and robust results which can be used for image analysis.

Creating a good segmentation however requires some expertise and can be time consuming. One has to determine the right threshold to stop the watershed. Meaningful local extrema have to be selected to initiate the algorithm. And once a result is obtained the segmentation has to be compared to the original data. That process can then be iterated till satisfying parameters are found. That procedure can be very time consuming if not provided with practicle tools, especially when image are large and a single watershed can take minutes.

The interactive Watershed plugin provides an interactive way to explore local minima (maxima) and threshold, updating the resulting watershed on the fly. This is possible by calculating the watershed only once at plugin initialization. Further when Threshold or maxima selection are updated this initial segmentation is reused to generate the new segmentation instantly. In order to ease quality assessment the results directly overlaid to the data.

The 2 following subsection gives additionnal details on watershed working principle and on the strategy used in the plugin for local maxima detection: H-Maxima

Watershed principle

If we interpret images as landscapes of hills and valleys, the watershed algorithm gradually flood the valleys starting from their lowest points (the image local minima). When the flooding of two minima meet at a sadle their remain distinct as each minima region is labelled with a distinct value. The flooding is stopped when all the image is flooded. As object don't always covers the whole image a threshold can be set stoping region evolution before the entire flooding. Alternatively the flooding can be started from local maxima. Image 2 shows the flooding of 3 peaks for different value of the treshold parameter.

Figure Watershed.PNG
Figure 2 The figure illustrates the flooding of an image by the watershed algorithm. First row shows the the flooding of a 2D image while 2nd row illustrate the process in a 1D image (section along the red cut in the 1st row). 1st column shows the orginal image. 2nd column show with spot the detection of local minima. Column 3,4,5 show the flooding of the image. If no stopping criteria is used the entire image is flooded.

H-Maxima amd H-Watershed

An image local maximum (minimum) is a region in the image for which all neighboring pixels have a lower (higher) value. A lot of maxima in an image are simply cause by noise and are not meaningful. If one can select more significant maxima corresponding to objects They could be used to initiate a watershed segmentation of the these objects.

There exist many different way of detecting local maxima. H-maxima focus on maxima robustness. It has one paramter, H, that can be compared to the intensity of the noise in the image. H-Maxima selects all maxima which are still maxima when there value is decreased by H. When H is increased less maxima are selected but they end being more robust to noise. Image 3 shows the maxima selected in a sample image for different H values.

We call H-Watershed the segmentation obtained by flooding the H-Maxima of an image. Such segmentation has 2 parameters. The Threshold, T, that stops the flooding of the image and the H-maxima robustness, H, that indicate where the flooding is initiated.


Figure HMax HWatershed v3.PNG
Figure 3 The figure illustrates the detection of H-Maxima for in 2D, 1D and the resulting 2D watershed (repectively row 1, 2 and 3). The 1st column show the original data, whereas column 2, 3 and 4 show the maxima and H-Watershed respectively for H value 0, 10 and 40. The threshold value 100 was used for the H-Watershed on row 3. The image used for the illustration is crop of the blobs image available from Fiji sample image.



To install the plugin in your ImageJ or Fiji installation. Add the update site SCF-MPI-CBG. Java8 update site should also be installed it is not there yet. The procedure to follow an update site can be found there.

Once the update site is intalled, restart ImageJ. A new menu SCF-MPI-CBG should be there. The Interactive Watershed plugin can be found in the menu SCF-MPI-CBG>Labelling>Interactive H-Watershed.

User Interface

To use the Interactive Watershed plugin.

  1. Open an image to analyze. If the image has multiple channel or time dimensions crop a single channel 2D or 3D image for the analysis.
  1. In the menu SCF-MPI-CBG>Labelling click the Item Interactive H-Watershed. the pluginwill be initialized with the image that was in focus. A full watershed of the image is performed. If that step seem to be too last a while a process dialog will open indicating the remaining processing time. If the process is too long it can be interupted and restarted with a smaller volume.
  1. When the initialization is finished 2 window will popup the interactive watershed image and a control panel. When the control panel is updated the image window is updated on the fly. When satisified with the segmentation a label map can be exported with the export button at the bottom right of the control panel.

In this paragraph we will now describes the role and usage of the control panel item:

  • Analyzed image:
  • Seed dynamics:
  • intensity threshold:
  • peak flooding:
  • Display style:
  • Slicing axis:
  • View Image:
  • Export:

Figure IWS controlPanel.PNG
Figure 4 shows the user interface of the Interactive Watershed plugin for 2D image (Left) and 3D image (Right). On the top it shows the name of the analyzed image (Red). Below are parameters input, H value (Green), watershed threshold, T,(Blue) and peak Flooding (Orange). Then one can control segmentation display parameter: display style(Light purple) and the image displayed in the background of the segmentation (Yellow). Finally the export button (Lilac) exports a label map corresponding to the current parameter H,T and peak flooding. User interface for 3D images also allow to select the orientation of the plane displayed (Pink). XY, XZ or YZ planes can then be navigated directly with the slider of the image stack.

Figure IWS visualisationMode.PNG
Figure 5 is illustrating the way the segmentation can be displayed. The second row shows a close up (red region fom the first row). The raw data (1st column) are segmented by the Interactive Watershed plugin and can be displayed as a label map (2nd column), the segments contour overlaid on aw data (column 3), transparent solid segment overlaid on raw data (column 4).

Figure IWS sideViews v2.PNG
Figure 6: In 3D images a good assessment of segmentation requires to observe data under different angles. Beside the usual XY view of the data (Left), the Interactive Watershed plugin can display YZ sections (Center panel, section along the red line in the left panel) and XZ sections (Right panel, section along the green line in the left panel). If the data are not istropic the views a resampled to remove distortion that makes the inspection effortless.

Figure IWS customBgImage.PNG
Figure 7 Illustrates the ability to overlay the segmentation to an image different from the one segmented. When performing a segmentation on a filtered image (Left panel), One can select a view image different from the view image (Center Panel), for instance to assess the segmentation against the raw data (Right Panel). in that case the segmentation could be imporved by a preliminary filtering while not hurt too much final segment shape.


In ImageJ macro language one can perform a H-Watershed segmentation with the following command:


hMin = 20;
thresh = 100;
peakFlooding = 90;
run("H_Watershed", "impin=["+getTitle()+"] hmin="+hMin+" thresh="+thresh+" peakflooding="+peakFlooding + " outputmask=true allowsplitting=false");

In a Jython script the H-Watershed segmentation could be called as follows:


# @ImagePlus imp
# @OpService ops
# @UIService ui

# The parameters "Seed Dynamics", "Intensity threshold" and "peak flooding" can be made optional
# function Signature
# 	resultImage = op.run("H_Watershed", inputImage, hMin, threshold, peakFlooding, outputMask, allowSplitting)
#	all parameters beyond inputImage are optionnal mean they can be replaced by null or if at the end of the
#	list they can be remove completely. if the parameter is detected as missing a sensible default is used
#	hMin = 5(max-min)/100
#	threshold = min
# 	peakflooding = 100
#	outputMask = false (default is to output a label image)
#	allowsplitting = true (default is to allow threshold to create new peaks)

hMin = 0
thresh = 100
peakFlooding = 50

result0 = ops.run("H_Watershed", imp)

result1 = ops.run("H_Watershed", imp, hMin)

result2 = ops.run("H_Watershed", imp, hMin, thresh)

outputMask = True
allowSplit = False
result3 = ops.run("H_Watershed", imp, hMin, thresh, peakFlooding, outputMask, allowSplit )


The run commands are also recorded by the macro recorder when exporting a label map.

Methods and Implementation

principle: Build a Hierarchy of segments that allow to build all H-Watershed without reprocessing the watershed

Cite paper Najman (initial paper, equivalence to hierarchy), Abealez (ultrametric), Lotufo (IFT watershed)


[ref Soille]

[ref Najman 1996]

[ref Najman 2010]

[ref Arbealez 1996]

[ref Lotufo]