VTK/Image Connectivity

A connectivity filter examines the connectivity between the elements in a data set, in order to produce "connected regions", where each connected region is a set of elements that are connected to each other but not to other regions. For mesh data, VTK provides the vtkPolyDataConnectivityFilter and the generic vtkConnectivityFilter for separating a data set into connected regions. This page describes the vtkImageConnectivityFilter, which serves the same purpose for image data.

VTK already has other connectivity filters, two of which the vtkImageConnectivityFilter aims to replace:

• vtkImageIslandRemoval2D - very old filter, requires a 2D label image as input
• vtkImagSeedConnectivity - very old filter, requires a label image as input

The API of vtkImageConnectivityFilter is intentionally similar to the generic vtkConnectivityFilter, but it produces a vtkImageData output instead of producing a vtkUnstructuredGrid.

Features

A connected region is defined as a set of adjacent (face-connected) voxels that are all have values within a prescribed range, called the ScalarRange. The default behavior of this filter is to produce an image where the voxels in each region are colored with a label value that identifies the region (i.e. each region will have a different label).

In addition to the input image, this filter can also take an optional data set input for region seeds. The seed data set can be an image (in which case any voxel with a non-zero value is a seed), or any other data set type (in which case each supplied point is a seed). The scalars for the seeds can be used to label the extracted regions. If no seeds are supplied, then the output will be as if all regions were seeded.

It is possible to extract only specific regions:

• the lower and upper size limits for the extracted regions can be specified
• seeds can be used to select regions
• the largest region can be automatically selected
• the above three rules can be combined (e.g. largest seeded region within size range)

It is also possible to control how the extracted regions are colored:

• they can be colored with scalars that come with the seed data
• they can be labeled consecutively by size
• they can all be colored the same (i.e. to produce a binary image)

Interface

Inputs

• SetInputConnection(input) - set the input data
• SetSeedConnection(seeds) - set the seeds (optional)
• SetStencilConnection(stencil) - apply a stencil (optional)

Parameters

• SetScalarRange(r1, r2) - range of input values to use
• SetSizeRange(s1, s2) - size of regions (voxel count) to output

• SetExtractionMode(mode) - specify which regions to output
• SetExtractionModeToSeededRegions() - output all seeded regions
• SetExtractionModeToAllRegions() - output all regions, seeded or not
• SetExtractionModeToLargestRegion() - only output the largest region

• SetLabelMode(mode) - specify how to color the output image
• SetLabelModeToSeedScalar() - label the regions the same as the seeds
• SetLabelModeToConstant() - all regions have the same label
• SetLabelModeToSizeRank() - regions labeled from largest to smallest
• SetLabelConstantValue(val) - for use with SetLabelModeToConstant()

• GenerateRegionExtentsOn() - see GetExtractedRegionExtents() below

Outputs

• GetOutputPort() - get the output

• GetNumberOfExtractedRegions() - the number of regions output
• GetExtractedRegionLabels() - get an array with the label for each region
• GetExtractedRegionSizes() - get the size (voxel count) for each region
• GetExtractedRegionExtents() - get the extent (limits) for each region

Uses

The operation performed by this filter is generically referred to as "region growing" (if seeded) or "blob extraction" (if not seeded).

Some potential uses of this filter are as follows:

• clean up images before volume rendering, by selecting the largest region that is above the background noise level
• find the crop region (extent) and size for each connected region in an image
• create a label map so that when a user picks an image, the application can report what connected region in the image was picked
• allow user to select a region of an image by picking a seed and adjusting the scalar range thresholds