Short Description

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


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.

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).

Resources needing this

One review on “Label Extractor

  1. J
    Great plugin, with good documentation and well commented source code. 5* if option is added to exclude edge objects.

Leave a Review

Leave a review
Cancel review
View full changelog
Close changelog


  • Version • Released on: 2019-04-05 18:02:10

    Updated for future Icy 2.0 and benefit from the new image cache instead of the file buffer.

  • Version • Released on: 2018-07-31 16:29:38

    Better tmp file deletion to avoid filling hard drive with repeated operations in same Icy session

  • Version • Released on: 2017-06-07 17:43:55

    Make the plugin compatible for Java 1.6 (for the oldies still out there)

  • Version • Released on: 2017-06-07 15:13:39

    Fixed an issue where the disk caching method (in 3D) would not work properly (due to file access permissions)

  • Version • Released on: 2016-02-02 19:56:32

    * NEW: 3D extraction is now cached on disk (to some extent) to save memory (only minimal loss of performance)
    * Pretty print the constant names

  • Version • Released on: 2015-08-05 20:05:11

    Adjusted the name of the extracted ROI to indicate the original (extracted) label value

  • Version • Released on: 2015-03-19 16:37:34

    Labels now have a automated numbering in their name for easier interpretation

  • Version • Released on: 2014-08-05 20:18:16

    Major speed boost of the standalone version (slowness was due to the ROI export)

  • Version • Released on: 2014-05-12 21:20:36

    Made methods static for script access

  • Version • Released on: 2014-02-12 19:09:12

    Stable release.
    Fixed an issue causing several empty ROI to be created in some cases

  • Version • Released on: 2014-01-23 18:47:46