ImageJ

{{Infobox
| name                   = MorphoLibJ
| software               = IJPB-plugins
| update site            = IJPB-plugins
| author                  = [https://github.com/dlegland David Legland], {{Person|Iarganda}}
| maintainer             = [https://github.com/dlegland David Legland], {{Person|Iarganda}}
| source                 = {{GitHub|org=ijpb|repo=MorphoLibJ}}
| released               = July 3<sup>rd</sup>, 2014
| latest version         = October 23<sup>rd</sup>, 2018 ([[MorphoLibJ]] v1.4.0)
| status                 = stable, active
| category               = [[:Category:Analysis|Analysis]], [[:Category:Filtering|Filtering]], [[:Category:Segmentation|Segmentation]], [[:Category:Mathematical_morphology|Mathematical morphology]]
}}MorphoLibJ is a collection of [[wikipedia:Mathematical morphology|mathematical morphology]] methods and '''plugins''' for ImageJ, created at [http://www-ijpb.versailles.inra.fr/en/bc/equipes/modelisation-imagerie/ INRA-IJPB Modeling and Digital Imaging lab].

The library implements several functionalities that were missing in ImageJ, and that were not or only partially covered by other plugins. Namely:

* '''Morphological filtering''' for 2D/3D and binary or grey level images: erosion & dilation, closing & opening, morphological gradient & Laplacian, top-hat...

* '''Morphological reconstruction''', for 2D/3D and binary or grey level images, allowing fast detection of regional or extended extrema, removing of borders, hole filling, attribute filtering...

* '''Watershed segmentation''' + GUI, making it possible to segment 2D/3D images of (for instance) cell tissues.

* '''2D/3D measurements''': photometric (intensity) and morphometric measurements such as volume, surface area, inertia ellipse/ellipsoid...

* '''Binary / label images utilities''' for removing or keeping largest connected component, perform size opening, fill holes, kill borders...

== Morphological filters ==
Morphological filters are very common filters that can be combined together to provide a large variety of solutions. They are local filters, in the sense that they consider the neighborhood of each pixel/voxel.

Morphological filters are defined according to a '''structuring element''' of a given size and
shape. Common structuring element include squares, discrete disks and octogons. Linear structuring element of various orientations may also be used to assess local orientation of the
structures.

=== Principles ===
The original idea was to define a methodology to describe shapes by using another shape as test probe (Serra, 1982<ref name="Serra1982>{{ cite book
| title = Image Analysis and Mathematical Morphology. Volume 1
| author = Serra, Jean
| publisher                = Academic Press
| year                     = 1982
| doi = 10.1002/cyto.990040213
}}</ref>; Serra ''et al.'', 1992<ref name="Serra1992>{{ cite journal
| title =  An overview of morphological filtering
| author = Serra, Jean and Vincent, Luc
| journal = Circuits, Systems and Signal Processing
| volume = 11
| number = 1
| pages= 47-108
| year = 1992
| publisher = Springer
| doi = 10.1007/BF01189221
}}</ref>). The most basic morphological filters are the '''morphological dilation''' and the '''morphological erosion'''. The principle of morphological dilation is to test for each point of the plane, if the structuring element centered on this point '''intersects''' the structure of interest (see figure below). It results in a set larger than the original set. 
The principle of morphological erosion is to test for each point of the plane if the structuring element centred on this point '''is contained''' within the original set. It results in a set smaller than original set.

[[Image:Principle-of-morphological-dilation-and-erosion.png|thumb|700px|center|Principle of morphological dilation and erosion on a binary set, using a disk-shaped structuring element.]]

Morphological dilation and erosion change the size and the resulting set. It may also change its topology: after a dilation, components may merge and holes be filled. After an erosion, components may disappear, or components be separated into several parts.

===Grayscale morphological filters===
==== Grayscale erosion and dilation ====
Morphological erosion and dilation may also be applied on grayscale images. In that case, the morphological dilation computes for each pixel the maximum within its neighborhood (defined by the structuring element), whereas the morphological erosion considers the minimum value within the neighborhood.
[[Image:MorphoLibJ-grains-dilation-erosion.png|thumb|center|700px|Some examples of morphological filters on a grey level image. From left to right: original image, result of dilation with a square structuring element, and result of erosion with the same structuring element.]]
Applying a  dilation or an erosion changes the size of the structures in the image: the grains in the result of the dilated image are larger. Morphological erosion can also be used on binary images to help separating touching particles.

==== Opening and closing ====
Morphological dilation and erosion are often used in combination. For example, the result of a dilation followed by an erosion is called a '''morphological closing''', and removes dark structures smaller than the structuring element. It can also connect bright structures that were separated by a thin dark space.

In a symmetric way, the result of an erosion followed by a dilation is called a '''morphological opening''', and removes bright structures smaller than the structuring element.

[[Image:MorphoLibJ-grains-closing-opening.png|thumb|480px|center|Some examples of composed morphological filters. From left to right: morphological closing, and morphological opening.]]

Note that even if opening and closing better preserve the size of the structures in the original image, the shape is slightly altered. For example, the result of morphological closing on the figure above creates artificial connections between grains. Choosing the best size for the structuring element is often a compromise between noise removal and preservation of structure shape.

==== Morphological gradients ====
More complicated combinations of elementary operations can be used. The '''morphological gradient''', computed as the difference of the result of a morphological dilation with the
result of a morphological erosion, reveals the '''boundaries''' of the structures within the image. The '''morphological Laplacian''' is defined as half the sum of a morphological
dilation and a morphological erosion with the same structuring element, minus the original
image. It results in enhancing the edges of the image.

==== Top-hats ====
The '''white top-hat''' first computes a morphological opening (resulting in removing bright structures smaller than structuring elements), and removes the result from the original image. When applied with a large structuring element, the result is an homogenization of the background, making bright structures easier to segment. Similarly, the '''dark top-hat''' can be used to enhance dark structures observed on an non-homogeneous background.
[[Image:MorphoLibJ-grains-gradient-Laplacian-whiteTopHat.png|thumb|center|700px|More examples of composed morphological filters. From left to right: morphological gradient, morphological Laplacian, morphological white top-hat.]]

===Directional filters===
For images containing very thin curvilinear structures (for example blood vessels, cell wall sections...), the application of common filters may be difficult due to the small size of the structures. Even for small structuring elements, the application of a morphological opening or closing let the structure disappear. Moreover, it may be difficult to preserve the whole thickness of the structure.

[[Image:MorphoLibJ-directional-filtering-example.png|thumb|700px|center|Filtering of a thin structure. (a) Original image representing apple cells observed with confocal microscopy. The application of a Gaussian filter (b) or median filter (c) results in noise reduction, but also in a loss of the signal along the cell walls. The directional filtering (d) better preserves the thickness of the structure.]]

An alternative is to apply directional filtering. The principle is to consider an oriented structuring element such as a line segment of a given length, and to perform morphological operations for various orientations of the structuring element (Soille ''et al.'', 2001<ref name="Soille2001">{{ cite journal
| title = Directional morphological filtering
| author = Soille, Pierre and Talbot, Hugues
| publisher = IEEE
| year = 2001
| volume = 23
| number = 11
| pages = 1313-1329
| journal =IEEE Transactions on Pattern Analysis and Machine Intelligence
| doi = 10.1109/34.969120
}}</ref>; Heneghan ''et al.'', 2002<ref name="Heneghan2002">{{ cite journal
| title =  Characterization of changes in blood vessel width and tortuosity in retinopathy of prematurity using image analysis
| author = Conor Heneghan and John Flynn and Michael O Keefe and Mark Cahill
| journal = Medical Image Analysis
| volume = 6
| number = 4
| pages= 407-429
| year = 2002
| publisher = Elsevier
| doi = 10.1016/S1361-8415(02)00058-0
}}</ref>; Hendriks ''et al.'', 2003<ref name="Hendriks2003">{{ cite conference
| title =  Discrete Morphology with Line Structuring Elements
| author = Hendriks, CL Luengo and van Vliet, Lucas J
| booktitle = International Conference on Computer Analysis of Images and Patterns
| pages = 722-729
| year = 2003
| organization = Springer
| doi = 10.1007/978-3-540-45179-2_88
}}</ref>). For example, applying a median filter or a morphological opening with horizontal direction results in the enhancement of horizontal parts of bright structures. Similarly, using a vertical structuring element results in the enhancement of the vertical portions of the structures.

[[Image:MorphoLibJ-directional-filtering-principle.png|thumb|700px|center|Principle of directional filtering of a thin structure. (a) and (b): result of median filter using an horizontal and a vertical linear structuring element. (c) and (d): combination of the results obtained from two directions (horizontal and vertical) and four directions (by adding diagonal directions).]]

The results of oriented filters for each direction can be combined by computing the maximum value over all orientations. The figure above shows the results obtained when combining two or four directions. Here, 32 orientations of line with length 25 were used. This results in the enhancement of the image while preserving the thickness of the bright structures.

Similar results may be obtained for enhancing dark curvilinear structures, by using morphological closing or median filters, and combining the results by computing the minimum over all directions.

=== Plugin Usage ===
[[Image:MorphoLibJ-mosaic-filters.png|right|thumb|550px|MorphoLibJ filter examples: DAPI stained nuclei image and the result of applying different morphological filters with an octagon of radius 5 as structuring element.]]
The collection of morphological filters is available in the {{bc | Plugins | MorphoLibJ}} menu. Filters are '''implemented both for 2D and 3D images''', and work for binary, gray level or color (RGB) images.
==== Planar images ====
Morphological filters for planar images are available {{bc | Plugins | MorphoLibJ | Morphological filters}}. The dialog let the user choose the structuring element shape, radius, and eventually preview the result. The following list of operations can be chosen:
* '''erosion''' keeps the minimum value within the neighborhood defined by the structuring element.

* '''dilation''' keeps the maximum value within the neighborhood defined by the structuring element.

* '''closing''' consists in the succession of a dilation with an erosion. Morphological closing makes dark structures smaller than the structuring element disappear.

* '''opening''' consists in the succession of an erosion with a dilation. Morphological opening makes bright structures smaller than the structuring element disappear.

* '''morphological gradient''' is defined as the difference of a morphological dilation and a morphological erosion with the same structuring element, and enhances edges of the original images.

* '''morphological Laplacian''' is defined as half the sum of a morphological dilation and a morphological erosion with the same structuring element, minus the original image, and enhances edges of the image.

* '''black top-hat''' consists in subtracting the original image from the result of a morphological closing, and results in the enhancement of dark structures smaller than structuring element.

* '''white top-hat''' consists in subtracting the result of a morphological opening from the original image, and results in the enhancement of bright structures smaller than structuring element.

The following structuring elements can be used for 2D images:

* disk 
* square
* octagon
* diamond
* line with angle of 0, 90, 45 or 135 degrees

==== 3D images ====
Morphological filters for 3D images are available under {{bc | Plugins | MorphoLibJ | Morphological filters (3D)}}. The dialog let the user choose the structuring element shape and radius. The same list of operations as for planar images is provided. Planar structuring elements can be used (the operation is simply repeated on each slice), as well as a cubic or spherical structuring element. For most structuring elements, the size can be chosen for each direction.

====Directional Filters====
Directional filtering is available from {{bc | Plugins | MorphoLibJ | Directional Filtering}}. It requires a planar image. 

The parameters are:
* '''Type''': to specify how to combine the results for each oriented filter
* '''Operation''': the operation to apply using each oriented structuring element
* '''Line Length''': the approximated length of the structuring element. 
* '''Direction Number''': the number of oriented structuring elements to consider. To be increased if the length of line is large.

== Connected components operators ==
The “classical” morphological filters presented in the previous section transform an input image by using the values of pixels or voxels located in a close neighborhood, defined by the structuring element. Such filters can be seen as “local”, as the result in a given position does not depend on image values located at a sufficient distance. 

Connected components operators are more general as they propagate information within the image based on connectivity between pixels or voxels. More details can be found in the review of Breen ''et al.'' (1996)<ref name="Breen1996">{{cite conference 
| title = Attribute Opening, Thinnings, and Granulometries
| author = Edmond J. Breen and Ronald Jones
| journal                  = Computer Vision and Image Understanding
| year                     = 1996
| month                    = Nov.
| number                   = 3
| pages                    = 377--389
| volume                   = 64
| doi                      = 10.1006/cviu.1996.0066
| url                      = http://www.sciencedirect.com/science/article/pii/S1077314296900661}}</ref>. Connected components operators encompass powerful operators, such as '''morphological reconstruction''' that allows to reconstruct a marker image by constraining it to a mask. An extension of morphological reconstruction is the detection of '''extended minima and maxima''', that can be useful as marker detection for segmentation. Finally, '''attribute opening and filtering''' algorithms can filter images based on size or range properties, with better preservation of edges than classical filtering. 
=== Morphological reconstruction ===
The morphological reconstruction is at the basis of many useful algorithms, such as border removing, hole filling, or detection of regional minima or maxima in grayscale images.
==== Principle ====
The principle of geodesic reconstruction is to repeat '''conditional dilations or erosions''' until idempotence. Conditional dilation is the result of a dilation, combined with a mask image using a logical operation. Conditional dilations are repeated until no more modification occur (idempotence condition).

The following figure shows several steps of a geodesic reconstruction by dilation on a pair of binary images. The mask image is shown in gray, and the marker image is shown in black on the first image. The reconstructed images at each step are shown in black. The markers propagates within the mask until they fill the chosen regions.
[[Image:MorphoLibJ-geodesic-reconstruction.png|thumb|center|750px|Principle of the geodesic reconstruction algorithm. From left to right: original image in gray with marker superimposed in black, and result of conditional dilations with increasing sizes.]]

==== Applications to binary images ====
By choosing the marker image, several operations may be automatized. For example, computing geodesic reconstruction with image of borders, and combining with original image will '''remove particles or regions touching the borders'''. In a similar way, computing geodesic reconstruction by using the border of the complement of the image makes it possible to '''fill holes''' that may appear in particles.
[[Image:MorphoLibJ-kill-borders-fill-holes.png|thumb|400px|center|Some applications of geodesic reconstruction. From left to right: original image, result of kill borders, result of fill holes.]]
==== Applications to grey level images ====
Geodesic reconstructions can be applied to grey level images. By manually choosing binary markers such that they overlay specific structures, and after applying a geodesic reconstruction by dilation, it is possible to obtain a grey level image containing only the chosen structures. The '''border kill''' operation can also be applied on grey level images, making possible to rapidly remove structures touching the image borders.
[[Image:MorphoLibJ-grains-markers-reconstruction-by-dilation-border-kill.png|thumb|700px|center|Some applications of geodesic reconstruction on grey level images. From left to right: original image with superimposed markers, result of geodesic reconstruction by dilation, result of border kill operation.]]
==== Usage ====
The geodesic reconstruction algorithm is often used within other operators. In MorphoLibJ, it is however provided as a plugin to allow its inclusion in user-designed macros or plugins:
* '''Geodesic Reconstruction''': compute the geodesic reconstruction by erosion or dilation using a marker image and a mask image, and a specified connectivity.
* '''Interactive Geodesic Reconstruction''': compute the geodesic reconstruction by erosion or dilation taking the current 2D image as mask image, creating the marker image out of user-defined ROIs (for example with the point selection tool).and using a specified connectivity. The plugin allows previewing the result. 
* '''Geodesic Reconstruction 3D''': compute the geodesic reconstruction by erosion or dilation on a 3D image.
* '''Interactive Geodesic Reconstruction 3D''': compute the geodesic reconstruction by erosion or dilation on using the current 3D image as mask and creating the marker image from the user-defined point selections.
The kill borders and fill holes operations are also provided as plugins. Both work for 2D and 3D images of 8, 16 or 32 bits.
* '''Kill Borders''': remove the particles touching the border of a binary or grayscale image.
* '''Fill Holes''' remove holes inside particles in binary images, or remove dark regions surrounded by bright crests in grayscale images.

=== Regional and extended extrema ===
'''Regional minima''' are defined as connected regions of elements (pixels or voxels) with the same value, and whose neighboring elements all have values greater than that of the region. Similarly, '''regional maxima''' are regions of connected pixels or voxels with same value, whose neighbors all have smaller value.

One problem arising with regional minima or maxima is that they are very sensitive to noise. It is often more convenient to use so-called extended extrema. The principle is to define a tolerance value for filtering the extrema. For example, '''extended maxima''' are defined as a connected region containing elements such that the difference of the value of each element within the region with the maximal value within the region is lower than the tolerance, and such that the neighbors of the regions all have values smaller than the maximum within the region minus the tolerance. This definition allows the identification of larger extrema, that better takes into account the noise within the image. The '''extended minima''' are defined in a similar way, and are efficiently used as pre-processing step for watershed segmentation.

Both extended maxima and minima are computed using the geodesic reconstruction algorithm. More details can be found in the book of Soille (2003).
[[Image:MorphoLibJ-grains-regional-and-extended-maxima.png|thumb|700px|center|Regional and extended maxima on a grey-level image. Left: original image. Middle: result of regional maxima. Right: result of extended maxima.]]

The following operations are available in the {{bc | Plugins | MorphoLibJ}} menu:
* '''Regional Min / Max''': compute regional minima or extrema in grey level or binary image, with specified connectivity.
* '''Regional Min / Max 3D''': compute regional minima or extrema in 3D grey level or binary image, with specified connectivity.
* '''Extended Min / Max''': compute extended minima or extrema in grey level image, with specified connectivity.
* '''Extended Min / Max 3D''': compute extended minima or extrema in 3D grey level or binary image, with specified connectivity.
* '''Impose Min / Max''': impose minima or maxima on a grey level image.
* '''Impose Min / Max 3D''': impose minima or maxima on a 3D grey level image.

=== Attribute filtering ===
Attribute filters aim at removing components of an image based on a certain size criterion, rather than on intensity. The most common and useful criterion is the number of pixels/voxels (i.e., the area or volume). For example, a morphological size opening operation with a threshold value of 20 will remove all blobs containing fewer than 20 voxels. The length of the diagonal of the bounding box can also be of interest to discriminate elongated versus round component shapes.
==== Application to binary images ====
When applied to a binary image, attribute opening consists in identifying each connected component, computing the attribute measurement of each component, and retain only the connected components whose measurement is above a specified value. This kind of processing is often used to clean-up segmentation results.
[[Image:MorphoLibJ-binary-area-opening.png|thumb|700px|center|Example of area opening on a binary image. Left: original binary image. Middle: identification of connected components. Right: only the connected components with a sufficient size (defined by the area), have been retained.]]

==== Application to grayscale images ====
When applied to a grayscale image, attribute opening consists in generating a series of binary images by thresholding at each distinct gray level in the image. The binary attribute opening described above is then applied independently to each binary image and the grayscale output is computed as the union of the binary results. The final output is a grayscale image whose bright structures with the attribute below a given value have disappeared. A great advantage of this filter is that the contours of the structures area better preserved than opening with a structuring element.

[[Image:MorphoLibJ-grayscale-area-opening.png|thumb|700px|center|Example of area opening on a grayscale image. Left: original grayscale image of a leaf (image courtesy of Eric Biot, INRA Versailles). Middle: grayscale size opening making bright spots disappear. Right: comparison with morphological closing with square structuring element of radius 1: bright spots are removed, but some veins also disappear.]]

As for classical morphological filters, grayscale attribute closing or tophat can be defined. Grayscale attribute closing consists in removing dark connected components whose size is smaller than a specified value. White [resp. Black] Attribute Top-Hat considers the difference of the attribute opening [resp. closing] with the original image, and can help identifying bright [resp. dark] structures with small size.
==== Usage ====

So far, the following attribute filtering plugins are available within MorphoLibJ (under {{bc | Plugins | MorphoLibJ}}):

* '''Gray Scale Attribute Filtering''': opens a dialog to perform between attribute opening, closing, and black or white top-hat on a planar (2D) grayscale image. Two size criteria can be used: the area (number of pixels), or the diameter (length of the diagonal of the bounding box).

* '''Gray Scale Attribute Filtering 3D''': opens a dialog to perform between attribute opening, closing, and black or white top-hat on a 3D grayscale image. The size criterion is the number of voxels.

== Watershed segmentation ==
[[Image:Classic-Watershed-lines-blur-blobs.png|thumb|200px|Overlay of watershed lines on blurred blobs.]] The watershed algorithm assimilates the grey level image to a digital elevation model, and aims at detecting the different catchment basins. In the grey-level image, the catchment basins correspond to dark regions surrounded by bright structures (the "crests"). It is a very popular technique specially used to segment touching objects. The MorphoLibJ suite contains several implementations of the algorithm and plugins that make use of it:

* [[Classic Watershed]], plugin implementing the original watershed algorithm by Pierre Soille and Luc M. Vincent (1990)<ref name="Soille1990>{{ cite conference
| title =  Determining watersheds in digital pictures via flooding simulations
| author = Soille, Pierre and Vincent, Luc M
| booktitle = Proc. SPIE
| volume = 1360
| pages = 240-250
| year = 1990
| organization = International Society for Optics and Photonics
| doi = 10.1117/12.24211
| url = http://dx.doi.org/10.1117/12.24211
}}</ref> to segment 2D/3D grayscale images.
* [[Marker-controlled Watershed]], a plugin to perform watershed in 2D/3D images by flooding from specific seed points or markers by Meyer and Beucher (1990)<ref name="Meyer1990>{{ cite journal
| title = Morphological segmentation
| author = F. Meyer and S. Beucher
| journal = Journal of Visual Communication and Image Representation
| volume = 1
| number = 1
| pages = 21-46
| year = 1990
| doi = 10.1016/1047-3203(90)90014-M
| url = http://www.sciencedirect.com/science/article/pii/104732039090014M
}}</ref>.
* [[Interactive Marker-controlled Watershed]], a plugin to perform watershed in 2D/3D images by flooding from specific seed points or markers introduced interactively by the user.
* [[Morphological Segmentation]], a plugin with a graphical user interface to segment 2D/3D images based on morphological operations and the watershed algorithm.
* [[Distance Transform Watershed]], two plugins (2D and 3D) that work on binary images and allow to separate touching objects by combining the distance transform and watershed methods.

== Measurements ==
[[MorphoLibJ]] contains several tools for quantifying the size, the shape, or the spatial organization, from '''binary or label''' 2D and 3D images. The aim is to facilitate the management of label images, contrary to the built-in “Analyze Particles...” function that operates directly on a grayscale image. 
=== Region analysis ===
This section describes the methods implemented in MorphoLibJ for describing individual regions, represented as label images (one label for each region). We first define and describe the implemented features, then we present the plugins that integrate them.
==== Intrinsic volumes ====
[[Image:MorphoLibJ-Euler-number.png|thumb|400px|Illustration of Euler Number definition. Left: three particles with Euler numbers equal to 1, 0 and -1, respectively. Right: example of a 3D particle with an Euler number equal to -1, corresponding to the subtraction of 1 connected components minus two handles.]]The intrinsic volumes are a set of features with interesting mathematical properties that are commonly used for describing individual particles as well as binary microstructrues. In the planar case, they correspond to the area, the perimeter and the Euler number. The Euler number is a topological characteristic that equals the number of connected components minus the number of holes.

For 3D particles, intrinsic volumes correspond to the volume, the surface area, the mean breadth (a quantity proportional to the integral of the mean curvature over the surface) and the Euler number. In 3D the Euler number equals the number of connected components minus the number of "handles" or "tunnels" through the structure, plus the number of bubbles within the particles (Serra, 1982<ref name="Serra1982></ref>; Ohser ''et al.'', 2009<ref name="Osher2009>{{ cite conference
| booktitle = 3D Images of Materials Structures: processing and analysis
| title = Image Processing
| author = Joachim Ohser and Katja Schladitz
| publisher = Wiley-VCH Verlag GmbH & Co. KGaA
| year = 2009
| doi = 10.1002/9783527628308.ch4
| url = http://dx.doi.org/10.1002/9783527628308.ch4
}}</ref>).

=====Estimation from 2D or 3D images=====
In image analysis, the '''estimation of area''' of 2D particles and of '''volume of 3D particles''' simply consists in counting the number of pixels or voxels that constitute it, weighted by the area of an individual pixel or the volume of an individual voxel. 

The implemented method for '''perimeter measurement''' aims at providing a better estimate of the perimeter than traditional boundary pixel count. The principle is to consider a set of lines with various orientations, and to count the number of intersections with the region(s) of interest (see figure on the right). The number of intersections is proportional to the perimeter (Serra, 1982<ref name="Serra1982></ref>; Legland ''et al.'', 2007<ref name="Legland2007">
{{cite conference
|title = Computation of Minkowski measures on 2D and 3D binary images
|author = Legland, David and Kiêu, Kiên and Devaux, Marie-Françoise
|journal = Image Analysis and Stereology
|year = 2007
|month                    = June
|number                   = 6
|pages                    = 83-92
|volume                   = 26
|doi                      = 10.5566/ias.v26.p83-92
|url                      = http://www.ias-iss.org/ojs/IAS/article/view/811
}}</ref>;  Ohser ''et al.'', 2009<ref name="Osher2009></ref>). By averaging over all possible directions, the estimate is unbiased.

Perimeter can be estimated using either two directions (horizontal and vertical), or four directions (by adding the diagonals). Restricting the number of directions introduces an estimation bias, with known theoretical bounds (Moran, 1966<ref name="Moran1966">
{{cite conference
|title = Measuring the length of a curve
|author = Moran, PAP
|journal = Biometrika
|year = 1966
|volume = 53 
|number = 3-4
|pages = 359-364
|doi = 10.1093/biomet/53.3-4.359
|URL = http://biomet.oxfordjournals.org/content/53/3-4/359.abstract
}}</ref>;  Legland ''et al.'', 2007<ref name="Legland2007"></ref>), that is usually better than boundary pixel count (Lehmann ''et al.'', 2012<ref name="Lehmann2012">
{{cite journal
|title = Efficient N-Dimensional surface estimation using [[wikipedia:Crofton formula|Crofton formula]] and run-length encoding
|author = Lehmann, Gaetan and Legland, David
|journal = Insight Journal
|year = 2012
|pages                    = 1-11
|url = http://hdl.handle.net/10380/3342
}}</ref>).

The '''estimation of surface area''' follows the same principle. The number of directions is typically chosen equal to 3 (the three main axes in image), or 13 (by considering also diagonals). As for perimeter estimation, surface area estimation in usually biased, but is usually more precise than measuring the surface area of the polygonal mesh reconstructed from binary images (Lehmann ''et al.'', 2012<ref name="Lehmann2012"></ref>).

=====Euler number=====
The measurement of Euler number depends on the choice of the connectivity. For planar images, typical choices are the 4-connectivity, corresponding to the orthogonal neighbors, and the 8-connectivity, that also considers the diagonal neighbors. In 3D, the 6-connectivity considers the neighbors in the three main directions within the image, whereas the 26 connectivity also considers the diagonals. Other connectivities have been proposed but are not implemented in MorphoLibJ (Ohser ''et al.'', 2009<ref name="Osher2009></ref>).

In the current implementation in MorphoLibJ, the Euler number is not taken into account for intersection of particles with image borders. This may result in non-integer result if the particle(s) of interest touches the image border.

=====Shape factors=====
Intrinsic volumes characterize the size of the particles, from different points of view. Several indices are sometimes used to describe the shape of the particles, independently of their size.

In 2D, the '''isoperimetric deficit index''' (or "shape factor", or "circularity") is defined as the ratio of area over the square of the perimeter, normalized such that the value for a disk equals one:

::::::::<math>circularity=4\pi\frac{A}{P^{2}}</math>

While values of circularity range theoretically within the interval <math>[0;1]</math>, the measurements errors of the perimeter may produce circularity values above 1 (Lehmann ''et al.'', 2012<ref name="Lehmann2012"></ref>). The MorphoLibJ library also considers the inverse of the circularity, referred to as "elongation index". The values of elongation range from 1 for round particles and increase for elongated particles.

::::::::<math>elongation	=	\frac{P^{2}}{4\pi\cdot A}</math>

In 3D, the '''sphericity index''' can be defined as the ratio of the squared volume over the cube of the surface area, normalized such that the value for a ball equals one:

::::::::<math>sphericity	=	36\pi\frac{V^{2}}{S^{3}}</math>

====Inertia ellipse and ellipsoid====
A binary particle may be described mathematically by its moments which corresponds to an integral of its indicator function, with various degrees along the directions. The first moment corresponds to the area or to the volume of the particle. The normalization of the first-order indicator functions leads to the 2D or 3D centroid of the particle. The second order moments can be used to compute the equivalent inertia ellipse or ellipsoid.

====Geodesic measurements====
[[Image:MorphoLibJ-perimiter-geodesic-diameter-computation.png|thumb|right|400px|Computation of perimeter and geodesic diameter. Left: principle of perimeter estimation by counting intersections with set of lines. Right: illustration of the geodesic diameter measured on a non convex particle.]]For particles with complex shapes, the geodesic diameter may be of interest. It corresponds of the largest geodesic distance between two points within a region, the geodesic distance being the length of the shortest path joining the two points while staying inside the region (Lantuejoul ''et al.'', 1981<ref name="Lantuejoul1981">{{cite conference
| title                    = On the use of geodesic metric in image analysis
| author                   = Lantuejoul, C. and Beucher, S.
| journal                  = Journal of Microscopy
| year                     = 1981
| month                    = Jan.
| number                   = 1,
| pages                    = 39-40
| volume                   = 121
| doi = 10.1111/j.1365-2818.1981.tb01197.x
| url = http://dx.doi.org/10.1111/j.1365-2818.1981.tb01197.x
}}</ref>).
====Plugins====
Most MorphoLibJ plugins consider the current image as input, that must be either binary (only one region is considered), or label (typically the result of a connected components labeling, see [[MorphoLibJ#Utilities_for_binary_images|Utilities for binary images]]). The output is a results table (ImageJ [https://imagej.nih.gov/ij/docs/guide/146-22.html Results table]) containing one row for each label actually present within the image. The spatial calibration of the image is taken into account in all measurements. All plugins can be found under the {{bc |Plugins | MorphoLibJ | Analyze}} menu.

===== Global geometry =====
The '''global geometry''' of particles in 2D images can be characterized with the Region Morphometry plugin (under {{bc | Plugins | MorphoLibJ | Analyze | Region Morphometry}}). For 2D particles, the area, the perimeter and derived features are implemented. The columns of the results table are:

* '''Label''': the label of the particle measured on the current line (it can be different from the row number if some labels do no exist in original image).
* '''Area''': the number of pixels within each region, multiplied by the area of each pixel.
* '''Perimeter''': an estimate of the perimeter, using the [[wikipedia:Crofton formula|Crofton formula]].
* '''Circularity''' the normalized ratio of area by the square of the perimeter: <math>4\pi\cdot A/p^{2}</math>. The value should be comprised between 0 (very elongated) and 1 (close to circular). Values superior to 1 may appear due to discretization effect.
* '''Elongation''': the normalized ratio of the square of the perimeter by the area : <math>p^{2}/\left(4\pi\cdot A\right)</math>, corresponding to the inverse of the circularity. The values range from 1 (round), and increase with elongation of the particle.
===== Largest inscribed circle or ball=====
This plugin computes for each label the largest disk that can be enclosed within the corresponding particle. The plugin opens a dialog that allows to choose the label image to characterize, the choice of the method for computing distance, and eventually the image on which overlaid circles can be drawn. The output of the plugin includes the following information:

* '''Label''': the label of the particle measured on the current line.
* '''xi''': the x-coordinate of the inscribed circle.
* '''yi''': the y-coordinate of the inscribed circle.
* '''radius''': the radius of the inscribed circle.
[[Image:Longest-geodesic-path-DRIVE.png|thumb|300px|right|Computation of the geodesic diameter on a segmented image from the DRIVE database (Staal ''et al''., 2004<ref name="Staal2004">{{ cite journal
|title                    = Ridge based vessel segmentation in color images of the retina
| author                   = J.J. Staal and M.D. Abramoff and M. Niemeijer and M.A. Viergever and B. van Ginneken
|  journal                  = IEEE Transactions on Medical Imaging
|  year                     = 2004
|  pages                    = 501-509
|  volume                   = 23
| doi = 10.1109/TMI.2004.825627
}}</ref>). Each connected component was associated to a label, then the longest geodesic path within each connected component was computed and displayed as red overlay.]]
=====Geodesic diameter=====
This plugin computes several geodesic measures for each particle in a label image. The result of the plugin comprises the following features:

* '''Label''': the label of the particle measured on the current line.
* '''Geod. Diam.''': the value of the geodesic diameter.
* '''Radius''': the radius of the largest inscribed circle, which is computed during the algorithm.
* '''Geod. Elong.''': the ratio of geodesic diameter over the diameter of the largest inscribed circle. The values range from 1 for nearly round particles and increases for elongated particles.
* '''xi, yi''': coordinates of the largest inscribed circle.
* '''x1, y1''': coordinates of one of the geodesic extremities of the particle.
* '''x2, y2''': coordinates of another geodesic extremity of the particle.

===== Region Analysis 3D =====
The plugin calculating these measurements is found under {{bc | Plugins | MorphoLibJ | Analyze | Region Analysis 3D}}. The results are provided in an ImageJ Results table, whose name contains the name of the original image.

* '''Label''': the label of the particle measured on the current line (it can be different from the row number if some labels do no exist in original image).
* '''Bounding box''': the minimal and maximal coordinates in each direction for each label.
* '''Volume''': computes the number of voxels comprising the particle, multiplied by the volume of an individual voxel.
* '''Surface area''': the surface area computed using a discretized version of the [[wikipedia:Crofton_formula|Crofton formula]], that computes intersections with line grids of various orientations (currently either 3 or 13).
* '''Sphericity index''': defined as <math>36\pi V^{2}/S^{3}</math>.
* '''Inertia ellipse / ellipsoid''': returns the centroid (center of gravity) as well as the size and the orientation of the inertia ellipse or ellipsoid of each particle. Radii are sorted in decreasing order. Angles are given in degrees, and correspond to the azimut ("yaw"), the elevation ("pitch"), and the roll around the main axis.

=== Intensity measurements ===

Other measurements are provided for pairs of grayscale and label 2D or 3D images ({{bc | Plugins | MorphoLibJ | Analyze | Intensity Measurements 2D/3D}}). The label image can correspond to a segmented particle, or to a more generic region of interest. 

The plugin calculates the '''mean''', '''standard deviation''', '''maximum''', '''minimum''', '''median''', '''mode''', '''skewness''' and '''kurtosis''' of the intensity value distribution of each labeled region in the grayscale image. The results are displayed as well in an ImageJ ''ResultsTable''.

=== Label Overlap Measures ===
Given two label images, there are different measures that allow us to evaluate the overlap
agreement (or error) between the labels. Following Tustison & Gee (2009)<ref name="Tustison2009>{{ cite journal
| title =  Introducing Dice, Jaccard, and other label overlap measures to ITK
| author = Tustison, NJ and Gee, JC
| journal = The Insight Journal
| pages = 1-4
| issue = July-December
| year = 2009
| doi = 10.1007/BF01189221
}}</ref>, and given a
source image <math>S</math> and a target image <math>T</math>, this plugin (under {{bc | Plugins | MorphoLibJ | Analyze | Label Overlap Measures}}) provides the following overlap measurements in two different result tables (one with the total values for all labels and one with values for individual labels):
* Target Overlap for each individual labeled region <math>r</math>:
:<math>TO_{r}=\frac{|S_{r}\cap T_{r}|}{|T_{r}|}</math>
* Total Overlap (for all regions):
:<math>TO=\frac{\sum_{r}{|S_{r}\cap T_{r}|}}{\sum_{r}{|T_{r}|}}</math>
* [https://en.wikipedia.org/wiki/Jaccard_index Jaccard Index] or Union Overlap for each individual labeled region <math>r</math>:
:<math>UO_{r}=\frac{|S_{r}\cap T_{r}|}{|S_{r}\cup T_{r}|}</math>
* [https://en.wikipedia.org/wiki/Jaccard_index Jaccard Index] or Union Overlap for all regions:
:<math>UO=\frac{\sum_{r}|S_{r}\cap T_{r}|}{\sum_{r}|S_{r}\cup T_{r}|}</math>
* [https://en.wikipedia.org/wiki/S%C3%B8rensen%E2%80%93Dice_coefficient Dice Coefficient] or Mean Overlap for each individual labeled region <math>r</math>:
:<math>MO_{r}=2\frac{|S_{r}\cap T_{r}|}{|S_{r}|+|T_{r}|}</math>
* [https://en.wikipedia.org/wiki/S%C3%B8rensen%E2%80%93Dice_coefficient Dice Coefficient] or Mean Overlap for all regions:
:<math>MO=2\frac{\sum_{r}|S_{r}\cap T_{r}|}{\sum_{r}\left(|S_{r}|+|T_{r}|\right)}</math>
* Volume Similarity for each individual labeled region <math>r</math>:
:<math>VS_{r}=2\frac{|S_{r}|-|T_{r}|}{|S_{r}|+|T_{r}|}</math>
* Volume Similarity for all regions:
:<math>VS=2\frac{\sum_{r}\left(|S_{r}|-|T_{r}|\right)}{\sum_{r}\left(|S_{r}|+|T_{r}|\right)}</math>
* False Negative Error for each individual labeled region <math>r</math>:
:<math>FN_{r}=\frac{|T_{r}\setminus S_{r}|}{|T_{r}|}</math>
* False Negative Error for all regions:
:<math>FN=\frac{\sum_{r}|T_{r}\setminus S_{r}|}{\sum_{r}|T_{r}|}</math>
* False Positive Error for each individual labeled region <math>r</math>:
:<math>FP_{r}=\frac{|S_{r}\setminus T_{r}|}{|S_{r}|}</math>
* False Positive Error for all regions:
:<math>FP=\frac{\sum_{r}|S{}_{r}\setminus T{}_{r}|}{\sum_{r}|S_{r}|}</math>

=== Spatial organization ===
The region adjacency graph plugin gives access to the neighborhood relationship between adjacent regions. This can be particularly informative for exploring collections of cells within cellular tissues (Florindo ''et al.'', 2016<ref name="Florindo2016">{{cite conference
| title                    = Identifying plant species using architectural features in leaf microscopy images
| author                   = Joao Batista Florindo and Odemir Martinez Bruno and Davi Rodrigo Rossatto and Rosana Marta Kolb and Maria Cecilia Gomez and Gabriel Landini
| journal                  = Botany
| year                     = 2016
|  number                   = 1
|  pages                    = 15-21
|  volume                   = 94
|  doi                      = 10.1139/cjb-2015-0075
|  url                      =  http://dx.doi.org/10.1139/cjb-2015-0075
}}</ref>).

[[Image:MorphoLibJ-region-adjacency-graph.png|thumb|500px|center|Computation of the Region Adjacency Graph on a microscopy image of plant tissue. Left: original image. Middle: result of watershed segmentation. Right: overlay of edges representing adjacent regions.]]

The plugin (under {{bc | Plugins | MorphoLibJ | Analyze | Region Adjacency Graph}}) works for both 2D and 3D images, and requires a label image as input. A typical input is the result of a watershed segmentation (see [[MorphoLibJ#Watershed_segmentation|Watershed Segmentation]]), eventually followed by [[MorphoLibJ#Label_Edition_plugin|manual edition of the labels]]. The output of the plugin is a results table with as many rows as the number of pairs of adjacent regions, containing the labels of the two adjacent regions.

==Binary and label image utilities==
The MorphoLibJ library provides several utility functions for the processing and the management of binary and label images. All methods of this section are available as plugins under {{bc | Plugins | MorphoLibJ | Binary Images}} or {{bc | Plugins | MorphoLibJ | Label Images}}.

===Distances for binary images===
====Distance transform====
When analyzing images, it is often necessary to compute distances to a particular structure or position. A convenient operator for binary images is the '''distance transform'''. Its principle is to compute, for each foreground pixel, the distance to the nearest background pixel. The result is commonly referred to as '''Distance Map'''.

[[Image:MorphoLibJ-distance-transform-on-binary-leaf.png|thumb|700px|center|Binary image, and result of computation of the distance transform.]]

Several methods exist for computing distance maps. The MorphoLibJ library implements distance transforms based on chamfer distances, that approximate Euclidean distances but are simpler to compute.

* '''Chamfer Distance Map''' computes an approximate distance map from a binary image between each foreground pixel to the nearest background pixel.
* '''Chamfer Distance Map 3D''' computes an approximate distance map from a 3D binary image between each foreground voxel to the nearest background voxel.

====Geodesic distance transform====

In some cases it may be useful to restrict the propagation of distances to a specific region or mask. For example, one may be interested in the distance between two points in a vasculature network, while staying within the network. The '''geodesic distance transform''' consists in computing the distance from a given binary marker, while constraining the propagation of the distance within a binary mask. An illustration is given in the figure below:

[[Image:MorphoLibJ-geodesic-distance-example.png|thumb|500px|center|Computation of the geodesic distance map on a binary image from the DRIVE database (Staal ''et al.'', 2004<ref name="Staal2004" />). Left: original image with marker superimposed in red. Right: result of geodesic distance map, hot colors correspond to large distances, cold colors correspond to small distances.]]

* '''Geodesic Distance Map''' computes the geodesic distance between each foreground pixel of a binary mask image to the closest pixel of a marker image, while staying within the particle represented by the mask image.
* '''Interactive Geodesic Distance Map''' computes the geodesic distance between each foreground pixel of a the currently selected image (considered the mask image) to the closest pixel of a marker image defined by the user ROIs, while staying within the particle represented by the mask image.

===Label images===
When several structures or components are present within an image, it may be more convenient to work with label images. Each pixel or voxel of a label image corresponds to the integer index of the particle it belongs to. The value 0 is assumed to correspond to the background. The number of labels that can be represented depends on the image type: 255 for byte images, 65535 for short images...

Label images can be represented either using shades of gray, or using color maps to better distinguish the different regions. 

====Connected component labeling====
The different structures within a binary images can be labeled by using a connected component labeling algorithm. Each label will correspond to a set of connected pixels or voxels. 

[[Image:MorphoLibJ-grains-binary-label-distance.png|thumb|700px|right|Binary image, result of connected components labeling, and computation of distance map on the complement of binary image.]]

Different connectivities may be chosen. For planar images, the most current ones are the 4-connectivity, that consider only orthogonal neighbors of a given pixel, and the 8-connectivity, that also considers the diagonals. For 3D images, the 6-connectivity considers only orthogonal neighbors in the three main directions, whereas the 26-connectivity considers all the direct neighbors of a given voxel.

* '''Connected Components Labeling''' transforms the binary image into a label image by assigning a specific number (label) to each connected component.

====Label image representation====
Several plugins allow to control the appearance of label images. It is possible to choose a given color map, or to transform a label image into a color image. In both cases, the background color can be specified, and the color order can be shuffled to facilitate the discrimination of neighbor regions with similar labels.

[[Image:MorphoLibJ-grains-labels-assign-measure.png|thumb|480px|center|Assign result of a measurement to a label image. In this example, the elongation is represented using a color code, between dark purple (circular) to yellow (very elongated).]]

* '''Assign Measure To Label''' combines a label image with a results table, and creates a new image for which each pixel/voxel is assigned the measurement value corresponding to the label it belongs to.
* '''Set Label Map''' allows to choose the color map used to display a label image. In particular, shuffling the color map and/or choosing a specific color for background allows better visualization that only grey levels.
* '''Label To RGB''' converts a label image to true RGB image. Similar to ImageJ native conversion, but this plugin avoids confusion between background pixels and regions with low labels.

===Region and labels selection===
The MorphoLibJ library offers several tools for automatically select binary regions or labels based on size or position criteria.
====Binary images====
* '''Keep / Remove Largest Region''' identifies the largest connected component, and keeps it or removes it.
* '''Size Opening''' computes the size (area in 2D, volume in 3D) of each connected component, and remove all particles whose size is below the value specified by the user.

Algorithms work for both 2D or 3D images. Default connectivity 4 (resp. 6) is used for 2D (resp. 3D) images.

====Label images====
[[Image:MorphoLibJ-grains-binary-label-remove-border-largest-size-opening.png|thumb|700px|center|MorphoLibJ utilities for label images. From left to right: original label image, remove border labels, remove largest region, apply size opening for keeping only regions with at least 150 pixels.]]

* '''Remove Border Labels''' is similar to "kill borders" function, but operates faster as no morphological reconstruction is required.
* '''Select Label(s)''' enters a set of labels, and creates a new label image containing only the selected labels.
* '''Crop Label''' creates a new binary image containing only the label specified by the user. The size of the new image is fitted to the region.
* '''Replace/Remove Label(s)''' replaces the value of a region by another value. Can be used to “clear” a label, by replacing its value by 0, or to merge to adjacent regions.
* '''Label Boundaries''' creates a new binary image containing value 255 for pixels/voxels having a neighbour with a different value.
* '''Keep / Remove Largest Label''' identifies the largest label, and keeps it or removes it.
* '''Label Size Opening''' computes the size (area in 2D, volume in 3D) of each region, and removes all labels whose size is below the value specified by the user.

=== Label Edition plugin ===
[[Image:Label-Edition-plugin.png|thumb|right|500px|Label Edition plugin overview.]]To ease the processing of label images, [[MorphoLibJ]] provides the Label Edition plugin (available under {{bc | Plugins | MorphoLibJ | Labels | Label Edition}}). This plugin contains a graphical user interface (GUI) where the users can perform the following set of editing tasks:

* Manually merge labels after their selection using the point selection tool (in 2D and 3D).
* Apply morphological erosion, dilation, opening and closing with a square/cube of radius 1 as structuring element.
* Remove labels by area or volume (size opening operation), largest size, manual selection or border location.

All operations are performed “in place”, i.e., the input image gets directly modified. However, the initial status of the label image can be recovered by clicking on “Reset”.

== Library interoperability ==
A key design concept of MorphoLibJ was the modularity of the implementation to facilitate its reusability.
Three layers with different programming abstraction can be identified:
* For final users, plugins provide graphical display and intuitive tuning of parameters. Such plugins can easily be incorporated into a macro:
<source lang="java">
// Calls the Regional Min/Max plugin on current ImagePlus instance
run("Regional Min & Max", "operation=[Regional Maxima] connectivity=4");
</source>
* For plugin developers, operators are available through collections of static methods, making it possible to apply most operations with a single line of code. Example:
<source lang="java">
// Computes regional maxima using the 4-connectivity
ImageProcessor maxima = MinimaAndMaxima.regionalMaxima(image, 4);
</source>
* For core developers, algorithms are implementations of abstract interfaces, making it possible to choose or develop the most appropriate one, and to monitor execution events. For example:
<source lang="java">
// choose and setup the appropriate algorithm
RegionalExtremaAlgo algo = new RegionalExtremaByFlooding();
algo.setExtremaType(ExtremaType.MAXIMA);
algo.setConnectivity(4);
// add algorithm monitoring
algo.addAlgoListener(new DefaultAlgoListener());
// compute result on a given ImageProcessor
ImageProcessor result = algo.applyTo(image);
</source>

In total, the library provides nearly two hundred classes and interfaces.

===Library organization===
The library follows a logic structure of folders divided by topics aiming at their re-usability from other plugins or scripts, among others:
* <code>inra.ijpb.data</code> contains generic data structures for manipulating 2D or 3D images
* <code>inra.ijpb.binary</code> contains the set of utilities for working on binary images (connected component labeling, distance transform, geodesic distance transform...)
* <code>inra.ijpb.label</code> contains the utilities for label images (cropping, size opening, remove border labels, etc)
* <code>inra.ijpb.measure</code> contains the tools for geometric and grey level characterization of 2D or 3D images
* <code>inra.ijpb.morphology</code> contains the collection of mathematical morphology operators
* <code>inra.ijpb.watershed</code> contains the classes implementing the different versions of the watershed algorithm
* <code>inra.ijpb.plugins</code> contains the set of plugins that is accessible from ImageJ/Fiji Plugins menu

All major methods have a general class with '''static methods''' that allow calling the methods on 2D and 3D images in a transparent way.

=== Scripting MorphoLibJ ===
One advantage of this organization of the library and the use of public static methods is that it allows very easy and fast prototyping of morphological algorithms and pipelines.
==== Segmentation pipeline prototype====
Let's see an example in a complete [[BeanShell_Scripting|Beanshell script]] that takes the active 2D or 3D image and finds a reasonable segmentation combining a set of morphological operations (gradient, extended minima and watershed):

<source lang="java">
#@ ImagePlus(label="Input image",description="Image to segment") imp
#@ Integer(label="Gradient radius",description="Radius of the morphological gradient",value=2) radius
#@ Integer(label="Tolerance",description="Local extrema dynamic",value=3) tolerance
#@ String(label="Connectivity",description="Local connectivity", choices={"6","26"}) strConn
#@ Boolean(label="Calculate dams",description="Flag to use dams in watershed",value=true) dams
#@OUTPUT ImagePlus resultImage
  
// ImageJ imports
import ij.IJ;
import ij.ImagePlus;
import ij.ImageStack;
// MorphoLibJ imports
import inra.ijpb.binary.BinaryImages;
import inra.ijpb.morphology.MinimaAndMaxima3D;
import inra.ijpb.morphology.Morphology;
import inra.ijpb.morphology.Strel3D;
import inra.ijpb.watershed.Watershed;
import inra.ijpb.data.image.Images3D;

// convert connectivity string to int
conn = Integer.parseInt( strConn );

image = null;
if( radius != 0 )
{
	// create structuring element (cube of radius 'radius')
	strel = Strel3D.Shape.CUBE.fromRadius( radius );
	// apply morphological gradient to input image
	image = Morphology.gradient( imp.getImageStack(), strel );

}
else
	image = imp.getImageStack();
// find regional minima on gradient image with dynamic value of 'tolerance' and 'conn'-connectivity
regionalMinima = MinimaAndMaxima3D.extendedMinima( image, tolerance, conn );
// impose minima on gradient image
imposedMinima = MinimaAndMaxima3D.imposeMinima( image, regionalMinima, conn );
// label minima using connected components (32-bit output)
labeledMinima = BinaryImages.componentsLabeling( regionalMinima, conn, 32 );
// apply marker-based watershed using the labeled minima on the minima-imposed 
// gradient image (the last value indicates the use of dams in the output)
resultStack = Watershed.computeWatershed( imposedMinima, labeledMinima, conn, dams );
   
// create image with watershed result
resultImage = new ImagePlus( "watershed", resultStack );
// assign right calibration
resultImage.setCalibration( imp.getCalibration() );
// optimize display range
Images3D.optimizeDisplayRange( resultImage );
// set same slice as input
resultImage.setSlice( imp.getCurrentSlice() );
</source>

==== Label visualization in 3D viewer ====
Making use of MorphoLibJ's label methods and the [[3D_Viewer|ImageJ 3D Viewer]]'s visualization tools it is quite simple to create a script to display each label of an image as 3D surfaces of the corresponding colors provided by the image look-up table:

<source lang="java">
#@ ImagePlus imp

import inra.ijpb.label.LabelImages;
import ij3d.Image3DUniverse;
import ij3d.ContentConstants;
import org.scijava.vecmath.Color3f;
import ij.IJ;
import isosurface.SmoothControl;

// set to true to display messages in log window
verbose = false;

// set display range to 0-255 so the displayed colors
// correspond to the LUT values
imp.setDisplayRange( 0, 255 );
imp.updateAndDraw();

// calculate array of all labels in image
labels = LabelImages.findAllLabels( imp );

// create 3d universe
univ = new Image3DUniverse();
univ.show();

// read LUT from input image
lut = imp.getLuts()[0];

// add all labels different from zero (background)
// to 3d universe
for( i=0; i<labels.length; i++ )
{	
	if( labels[ i ] > 0 )
	{
		labelToKeep = new int[ 1 ];
		labelToKeep[ 0 ] = labels[ i ];
		if( verbose )
			IJ.log( "Reconstructing label " + labels[ i ] + "..." );
		// create new image containing only that label
		labelImp = LabelImages.keepLabels( imp, labelToKeep );
		// convert image to 8-bit
		IJ.run( labelImp, "8-bit", "" );
		
		// use LUT label color
		color = new Color3f( new java.awt.Color( lut.getRed( labels[ i ] ),
			lut.getGreen( labels[ i ] ),
			lut.getBlue( labels[ i ] ) ) );
			
		if ( verbose )
			IJ.log( "RGB( " + lut.getRed( labels[ i ] ) +", " 
				+ lut.getGreen( labels[ i ] )
				+ ", " + lut.getBlue( labels[ i ] ) + ")" );

		channels = new boolean[3];
		channels[ 0 ] = false;
		channels[ 1 ] = false;
		channels[ 2 ] = false;
		
		// add label image with corresponding color as an isosurface
		univ.addContent( labelImp, color, "label-"+labels[i], 0, channels, 2, ContentConstants.SURFACE);
	}
}

// launch smooth control
sc = new SmoothControl( univ );
</source>
At the end of the script a dialog is shown to smooth the surfaces at will. Each label is added to the 3D scene independently with the nanme "label-X" where X is its label value.
[[Image:MorphoLibJ-visualize-labels-in-3d-viewer.png|thumb|center|750px|From left to right: input label image, script output, smoothed label surfaces and example of individually translated surfaces in the 3D viewer.]]

== Documentation ==
Each [https://github.com/ijpb/MorphoLibJ/releases released version of MorphoLibJ] comes with a [https://github.com/ijpb/MorphoLibJ/releases/download/v1.4.0/MorphoLibJ-manual-v1.4.0.pdf User Manual in PDF format].

The main source code directory is on GitHub under [http://github.com/ijpb/MorphoLibJ/tree/master/src/main/java/inra/ijpb src/main/java/inra/ijpb].

You can browse the [http://ijpb.github.io/MorphoLibJ/javadoc/ javadoc] for more information about its API.

== Installation ==

* In [[ImageJ 1.x]], download the [https://github.com/ijpb/MorphoLibJ/releases latest released jar] into the ''plugins'' folder.
* In [[ImageJ2]] (including [[Fiji]]), you just need to [[How_to_follow_a_3rd_party_update_site#Add_update_sites | add]] the IJPB-plugins site to your list of update sites:
*# Select {{bc | Help | Update...}} from the menu to start the [[updater]].
*# Click on ''Manage update sites''. This brings up a dialog where you can activate additional update sites.
*# Activate the IJPB-plugins update site and close the dialog. Now you should see an additional jar file for download.
*# Click ''Apply changes'' and restart ImageJ.

== Citation ==
Please note that [[MorphoLibJ]] is based on a publication. If you use it successfully for your research please be so kind to cite our work:
* {{Publication | MorphoLibJ}}

[[MorphoLibJ]]'s code repository has its own [https://zenodo.org/badge/latestdoi/21349/ijpb/MorphoLibJ DOI].

== References ==
<references />
== License ==
This program is '''free software'''; you can redistribute it and/or modify it under the terms of the '''GNU General Public License''' as published by the Free Software Foundation ([http://www.gnu.org/licenses/gpl.txt http://www.gnu.org/licenses/gpl.txt]).

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License for more details. 

[[Category:Plugins]]
[[Category:Analysis]]
[[Category:Filtering]]
[[Category:Segmentation]]
[[Category:Mathematical_morphology]]
[[Category:Citable]]