Toolbox of Watershed Transform

This page is the main resource of information on the toolbox of watershed transform developed using Adessowiki. Here it is provided the list of different implementations of the watershed transform, documentation and examples of use. The source code is embedded with each of these functions.

This toolbox was developed together with the Msc. Thesis of André Körbes. As a consequence, the users of it may also refer to that work to find further information. The thesis is available here.

Please refer to the following citations when making reference to this work:

  • KÖRBES, A. ; LOTUFO, R. . Analysis of the watershed algorithms based on the Breadth-First and Depth-First exploring methods. In: Brazilian Symposium on Computer Graphics and Image Processing, 2009, Rio de Janeiro. Proceedings of the XXII Brazilian Symposium on Computer Graphics and Image Processing, 2009. p. 133-140.
  • KÖRBES, A.. Análise de Algoritmos da Transformada Watershed. M.Sc. thesis. Faculty of Electrical and Computer Engineering, University of Campinas, Brazil, 2010.


The watershed transform toolbox depends on two other projects. The famous numpy, used for dealing with arrays, and the IPDP project, used for abstracting common image processing problems.

The Image Processing Design Patterns (IPDP) project aims on developing common tools to allow users to deal more easily with common image processing implementation problems. This project is under construction, and more features may be found on its own page hosted also here in Adessowiki. The features of it used on the watershed toolbox are:

  • Abstraction of image dimension
  • Border treatment
  • Domain iteration
  • Neighbourhood visitation
  • Data structures

Using these features, the source code in python becomes highly legible and very close to its representation on pseudo-code.


The toolbox in python was designed to not care about how many dimensions the input image or the neighbourhood have. This is mainly due to numpy capabilities of dealing with N-dimensional arrays and reshaping those correctly.

However, the most common use of such functions is with 2D images. On this case, the recommended usage is with rows on the last dimension (row major layout) of the numpy array. Please see the example for details.

The neighbourhood element is defined as an array MxN. The M lines of it are the number of neighbours that will be considered. The N columns are the N dimensions of the image. For example, a N4 neighbourhood, for a 2D image is:

-1 0
0 1
1 0
0 -1

Or, in python code:

N4 = array([[-1,0],[0,1],[1,0],[0,-1]])

With such representation, the neighbourhood is easily definable, and very extensible.

The only restriction applied here, is that neighbourhoods MUST be symmetric on each axis. However, symmetry as a whole is not enforced, so neighbourhoods such as a line are allowed.

To see the neighbourhood elements defined on IPDP, please visit ipdp:neighbourhood.


If looking for the fastest watershed algorithms, please visit the benchmark page.


All the watershed functions work the same way. The input is composed of two parameters: the image and the neighbourhood. The output is an image of labels. This was designed so that users can interchange between functions without problems.

  1. The simplest possible example