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 | 使用示例:

Raster 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(Raster raster)
      Analyze connected components in a Raster using 8-connectivity. 使用 8-连通分析 Raster 中的连通域。

      Foreground pixels are those with non-zero BT.601 grayscale value.

      非零 BT.601 灰度值的像素为前景像素。

      Parameters:
      raster - the input raster | 输入 raster
      Returns:
      the analysis result | 分析结果
      Throws:
      NullPointerException - if raster is null | 当 raster 为 null 时抛出
      ImageOperationException - if dimensions are invalid | 当尺寸无效时抛出
      Since:
      opencode-base-image V1.0.4

    • analyze

      public static ConnectedComponentsOp.Result analyze(Raster raster, ConnectedComponentsOp.Connectivity connectivity)
      Analyze connected components in a Raster with specified connectivity. 使用指定连通性分析 Raster 中的连通域。
      Parameters:
      raster - the input raster | 输入 raster
      connectivity - the connectivity type | 连通性类型
      Returns:
      the analysis result | 分析结果
      Throws:
      NullPointerException - if any argument is null | 任一参数为 null 时抛出
      ImageOperationException - if dimensions are invalid | 当尺寸无效时抛出
      Since:
      opencode-base-image V1.0.4