Class ColorExtractor

java.lang.Object
cloud.opencode.base.image.color.ColorExtractor
public final class ColorExtractor extends Object
Color Extraction Utility 颜色提取工具类

Extracts dominant colors from images using a simplified K-Means clustering algorithm on downsampled pixel data.

使用简化的 K-Means 聚类算法对降采样像素数据提取图像主色调。

Features | 主要功能:

  • Extract multiple dominant colors via K-Means - 通过 K-Means 提取多个主色调
  • Extract single dominant color - 提取单个主色调
  • 64x64 downsampling for performance - 64x64 降采样以提升性能

Usage Examples | 使用示例:

// Extract top 5 dominant colors
List<Color> colors = ColorExtractor.dominantColors(image, 5);

// Extract the single most dominant color
Color primary = ColorExtractor.dominantColor(image);

Performance | 性能特性:

  • Time: O(k * iter * n) where n = 64*64 samples, k = cluster count, iter = max 20 - 时间: O(k * iter * n)
  • Space: O(n + k) - 空间: O(n + k)

Security | 安全性:

  • Thread-safe: Yes (stateless) - 线程安全: 是（无状态）
  • Null-safe: No - 空值安全: 否
Since:
JDK 25, opencode-base-image V1.0.3
Author:
Leon Soo www.LeonSoo.com
See Also:

  • Method Details

    • dominantColors

      public static List<Color> dominantColors(BufferedImage image, int count)
      Extract the dominant colors from an image using K-Means clustering. 使用 K-Means 聚类从图像中提取主色调列表。

      The image is first downsampled to 64x64 for performance, then K-Means clustering is applied with the specified number of clusters. Results are returned sorted by cluster size (most dominant first).

      图像首先被降采样到 64x64 以提升性能，然后使用指定数量的聚类进行 K-Means 聚类。结果按聚类大小降序排列返回（最主要的颜色排在前面）。

      Parameters:
      image - the source image | 源图像
      count - the number of dominant colors to extract, must be in [1, 20] | 要提取的主色调数量，必须在 [1, 20] 范围
      Returns:
      the list of dominant colors sorted by prevalence | 按主要程度排序的主色调列表
      Throws:
      NullPointerException - if image is null | 当图像为 null 时抛出
      ImageOperationException - if count is out of [1, 20] range | 当 count 超出 [1, 20] 范围时抛出

    • dominantColor

      public static Color dominantColor(BufferedImage image)
      Extract the single most dominant color from an image. 从图像中提取单个最主要的颜色。

      Equivalent to calling dominantColors(image, 1).get(0).

      等效于调用 dominantColors(image, 1).get(0)。

      Parameters:
      image - the source image | 源图像
      Returns:
      the most dominant color | 最主要的颜色
      Throws:
      NullPointerException - if image is null | 当图像为 null 时抛出