Class ConnectedComponentsOp

java.lang.Object
cloud.opencode.base.image.analysis.ConnectedComponentsOp
public final class ConnectedComponentsOp extends Object
Connected Components Analysis using Two-Pass Union-Find Algorithm 基于两遍扫描 Union-Find 算法的连通域分析

Analyzes connected components in binary images where foreground pixels (non-zero grayscale value) are grouped into labeled regions. Supports both 4-connectivity and 8-connectivity neighbor definitions.

分析二值图像中的连通域，前景像素（非零灰度值）被分组为标记区域。 支持 4-连通和 8-连通两种邻域定义。

Features | 主要功能:

  • Two-Pass labeling with Union-Find (path compression + union by rank) - 两遍标记 + Union-Find（路径压缩 + 按秩合并）
  • 4-connectivity and 8-connectivity support - 支持 4-连通和 8-连通
  • Per-component statistics: area, centroid, bounding box - 每个连通域统计: 面积、质心、边界框
  • Label matrix output for downstream processing - 标签矩阵输出供下游处理

Usage Examples | 使用示例:

BufferedImage binary = ...; // binary image with white foreground
ConnectedComponentsOp.Result result = ConnectedComponentsOp.analyze(binary);
System.out.println("Components: " + result.componentCount());
for (ConnectedComponentsOp.Component c : result.components()) {
    System.out.printf("Label %d: area=%d, centroid=(%d,%d)%n",
        c.label(), c.area(), c.centroidX(), c.centroidY());
}

// Use 4-connectivity for stricter neighbor definition
ConnectedComponentsOp.Result result4 = ConnectedComponentsOp.analyze(binary,
    ConnectedComponentsOp.Connectivity.FOUR);

Performance | 性能特性:

  • Two-Pass + Union-Find: O(n * alpha(n)) approximately O(n), where n = width * height - 两遍扫描 + Union-Find: O(n * alpha(n)) 约等于 O(n)，n = 宽 * 高
  • Space complexity: O(n) for label matrix and Union-Find structure - 空间复杂度: O(n) 用于标签矩阵和 Union-Find 结构

Security | 安全性:

  • Thread-safe: Yes (stateless, all methods are pure functions) - 线程安全: 是（无状态，所有方法为纯函数）
  • Null-safe: No (null image throws NullPointerException) - 空值安全: 否（null 图像抛出 NullPointerException）
Since:
JDK 25, opencode-base-image V2.0.0
Author:
Leon Soo www.LeonSoo.com
See Also:

  • Method Details

    • analyze

      public static ConnectedComponentsOp.Result analyze(BufferedImage image)
      Analyze connected components in a binary image using 8-connectivity. 使用 8-连通分析二值图像中的连通域。

      Foreground pixels are those with non-zero grayscale value after converting the image to grayscale using ITU-R BT.601 coefficients.

      将图像转换为灰度（使用 ITU-R BT.601 系数）后，非零灰度值的像素为前景像素。

      Parameters:
      image - the input image | 输入图像
      Returns:
      the analysis result containing labels and component statistics | 包含标签和连通域统计的分析结果
      Throws:
      NullPointerException - if image is null | 当图像为 null 时抛出
      ImageOperationException - if the image has invalid dimensions | 当图像尺寸无效时抛出

    • analyze

      public static ConnectedComponentsOp.Result analyze(BufferedImage image, ConnectedComponentsOp.Connectivity connectivity)
      Analyze connected components in a binary image with specified connectivity. 使用指定连通性分析二值图像中的连通域。

      The algorithm works in two passes:

      1. First pass: scan top-left to bottom-right, assign provisional labels, record equivalences in a Union-Find structure.
      2. Second pass: replace all labels with their canonical root from Union-Find, then compute per-component statistics (area, centroid, bounding box).

      算法分两遍执行:

      1. 第一遍: 从左上到右下扫描，分配临时标签，在 Union-Find 结构中记录等价关系。
      2. 第二遍: 将所有标签替换为 Union-Find 中的规范根标签，然后计算每个连通域的统计信息。
      Parameters:
      image - the input image | 输入图像
      connectivity - the connectivity type (FOUR or EIGHT) | 连通性类型（FOUR 或 EIGHT）
      Returns:
      the analysis result containing labels and component statistics | 包含标签和连通域统计的分析结果
      Throws:
      NullPointerException - if image or connectivity is null | 当图像或连通性为 null 时抛出
      ImageOperationException - if the image has invalid dimensions | 当图像尺寸无效时抛出