Connected-component labeling (also known as connected-component analysis, blob extraction, or region extraction) uniquely labels connected pixel regions in an image. Scanning pixel-by-pixel from top-left to bottom-right, it identifies adjacent pixels sharing identical or similar intensity values.

Basic Object Detection

To demonstrate connected-component labeling, consider this initial source image:

To detect and uniquely label objects, process the image and apply auto-leveling for clear visual distinction:

$ magick objects.gif -connected-components 4 -auto-level -depth 8 objects.png

Inspecting Object Statistics

To retrieve verbose object metadata (bounding boxes, centroids, areas, and mean colors), enable the verbose definition:

$ magick objects.gif -define connected-components:verbose=true -connected-components 4 objects.png

Output details for the five detected components:

Objects (id: bounding-box centroid area mean-color):
  0: 256x171+0+0 119.2,80.8 33117 srgb(0,0,0)
  2: 120x135+104+18 159.5,106.5 8690 srgb(255,255,255)
  3: 50x36+129+44 154.2,63.4 1529 srgb(0,0,0)
  4: 21x23+0+45 8.8,55.9 409 srgb(255,255,255)
  1: 4x10+252+0 253.9,4.1 31 srgb(255,255,255)

Filtering and Merging Objects

Small noise objects can be eliminated by merging them into adjacent larger neighbors using an area threshold:

$ magick objects.gif -define connected-components:area-threshold=410 -connected-components 4 \
  -auto-level objects.jpg

Notice how two small regions were merged into the background, leaving three primary objects:

Objects (id: bounding-box centroid area mean-color):
  0: 256x171+0+0 118.0,80.4 33557 srgb(0,0,0)
  2: 120x135+104+18 159.5,106.5 8690 srgb(255,255,255)
  3: 50x36+129+44 154.2,63.4 1529 srgb(0,0,0)

Available Threshold Metrics

In addition to area, ImageMagick supports several geometry metrics for filtering:

connected-components:angle-threshold (from equivalent ellipse)
connected-components:circularity-threshold (4 * π * area / perimeter²)
connected-components:diameter-threshold (√(4 * area / π))
connected-components:eccentricity-threshold (from equivalent ellipse)
connected-components:major-axis-threshold (diameter from equivalent ellipse)
connected-components:minor-axis-threshold (diameter from equivalent ellipse)
connected-components:perimeter-threshold

Advanced Command Definitions

Sorting and Formatting

exclude-header=true – Omits the header row from verbose output.
exclude-ids=true – Suppresses ID numbers in output.
sort=area|width|height|x|y – Defines sorting field (defaults to area).
sort-order=increasing|decreasing – Sets sort direction.
mean-color=true – Colors labeled objects using source mean colors instead of grayscale IDs.

Object Inclusion & Exclusion

remove-ids=list – Explicitly removes specific component IDs (e.g., 2,4-5).
keep-ids=list – Keeps specified IDs and merges all others.
keep-top=number – Retains top N largest components along with background.
keep-colors=r;g;b – Retains or removes components matching specific colors.
background-id=id – Overrides default largest-area background assignment.

Connectivity, Color Fuzz, and Rotation

Use -connected-components 8 to visit 8-connected neighbors rather than 4-connected neighbors. For real-world images with minor color variations within regions, use -fuzz to group near-matching pixels:

$ magick star-map.png -fuzz 5% -define connected-components:verbose=true \
  -define connected-components:mean-color=true -connected-components 4 stars.gif

Handling Scan Edge Cases

Because the component algorithm scans row-by-row looking above and to the left, top-left components lack preceding neighbors to merge into. For complex edge-boundary cases, rotate the image, re-run labeling, and rotate back:

$ magick \
  objects.gif \
  -define connected-components:verbose=true \
  -define connected-components:area-threshold=6000 \
  -virtual-pixel None \
  -connected-components 4 -rotate 180 \
  -connected-components 4 -rotate -180 \
  objects.png