Need help or advice ? Come to the Icy club ! - Every Wenesday morning from 9h30 to 12h30 - Francois Jacob Building - Main hall - Pasteur

User reviews

5 star
4 star
3 star
2 star
1 star
average rating: 4

Please log-in to post a review
04 Aug 2016 10:36
Great plugin, with good documentation and well commented source code. 5* if option is added to exclude edge objects.

Label Extractor

by Alexandre Dufour

Extracts labeled objects from a binary or labeled image into ROI using connected component analysis

Publication Id
See technical details
View complete changelog
Tag: roi


The plugin performs a connected component analysis of a given image or sequence, and produces as many ROI as there are components in the input data. ImageJ users will be familiar with this tool, known as "Analyze particles".

Note that this plugin supersedes the former "Connected Components" plugin, fixing an issue in the extraction algorithm and simplifying its use and its graphical interface.


The principle of component analysis is to extract packs of pixels in an image with a given value (also called "label") such that all pixels of a component are spatially connected within the image (e.g. in 2D: pixels touching horizontally, vertically or diagonally). Traditionally, the input for such analysis is a binary image (0 in the background, and 1 in the foreground), in which case all pixels with label 1 will be extracted and grouped into components (and eventually into regions of interest) based on ther connectivity. However, this tool will also work on "labeled" data (hence its name), such that it is possible to give a multi-valued image (say, 0 for background, 1 for some objects and 2 for other objects) and extract each label separately in a single step.


This tool only has a single "value" parameter, which is interpreted differently depending on the extraction mode that is chosen:

  • ANY_LABEL_VS_BACKGROUND will extract components with any label value that is *not* equal to the background. In this case, the "value" parameter indicates the value of the background (this is typically 0, but in some exotic cases you might want to change that). Note that with this option, multiple connected pixels with a different label will be considered as part of the same component, since they both are different from the background. 
  • ALL_LABELS_VS_BACKGROUND will work very similarly to the previous option, however connected pixels with a different label will *not* be considered as part of the same component, and therefore be extracted separately. The "value" parameter still indicates the background value.
  • SPECIFIC_LABEL will extract all components with the desired label value. Here the "value" parameter is no longer the background value, but the specific value for which components should be extracted.

It is easy to see that in the specific case of binary data (0 and 1), selecting the first 2 options with a (background) value of "0" is identical to selecting the third option with a (specific) value of "1".


There is a *long* list on connected component algorithms in the literature, each with its pros and cons. The usual trade-off lies between computational speed and memory consumption. Sometimes even the size of the components has an influence: some algorithms are faster on small components, and slower on large components, and some work the other way round. Finally, some recent algorithms are particularly complex and would only work in 2D, while the extension to 3D raises significant issues.

The current implementation favors speed over memory consumption, and is rather balanced regarding the size of the objects. The algorithm sweeps the image data only twice: in the first pass, all pixels matching the extraction criterion are assembled into temporary components based on their connectivity. Obviously, for arbitrary objects, it is clear that the direction of sweeping generally causes some components with a different temporary label to eventually touch. When this happens, these components are marked for fusion before the second pass starts. (NOTE: the temporary labels are stored in a 32-bit integer map of same dimension as the original data, so pay attention to memory overload on large data sets!). In the second pass, the temporary map is sweeped, and the final regions of interest (ROI) are constructed, fusing the intermediate labels on the way.


Once the components have been extracted, they are converted to a area-type ROI (ROI2DArea or ROI3DArea). When using the standalone plug-in, the final ROI are added to the sequence indicated by the "Add ROI to" parameter. However when using the plug-in in protocols, the ROI are produced but not added to any sequence (there is a specific block for that purpose).