Class ImageCompare

java.lang.Object
cloud.opencode.base.image.compare.ImageCompare
public final class ImageCompare extends Object
Image Compare — pixel-level diff, SSIM, MSE, and PSNR metrics 图像比较 — 像素级差异、SSIM、MSE 和 PSNR 指标

Provides structural and statistical comparison between two images, useful for quality assessment, regression testing, and visual diff generation.

提供两幅图像之间的结构和统计比较，适用于质量评估、回归测试和视觉差异生成。

Features | 主要功能:

  • Pixel-level diff with highlighted difference image - 像素级差异及高亮差异图
  • SSIM (Structural Similarity Index) with 11x11 window - SSIM 结构相似性指数
  • MSE (Mean Squared Error) - MSE 均方误差
  • PSNR (Peak Signal-to-Noise Ratio) - PSNR 峰值信噪比

Usage Examples | 使用示例:

DiffResult result = ImageCompare.diff(imageA, imageB);
double similarity = ImageCompare.ssim(imageA, imageB);
double error = ImageCompare.mse(imageA, imageB);
double psnrDb = ImageCompare.psnr(imageA, imageB);

Performance | 性能特性:

  • diff/mse/psnr: O(W*H) per-pixel scan - 逐像素扫描
  • SSIM: O(W*H*K^2) with K=11 window — consider downscale for large images - 滑动窗口

Security | 安全性:

  • Thread-safe: Yes (stateless) - 线程安全: 是
  • Null-safe: No - 空值安全: 否
Since:
JDK 25, opencode-base-image V2.0.0
Author:
Leon Soo www.LeonSoo.com
See Also:

  • Method Details

    • diff

      public static ImageCompare.DiffResult diff(BufferedImage a, BufferedImage b)
      Compute pixel-level diff between two images. 计算两幅图像之间的像素级差异。

      If b has different dimensions, it is resized to match a. The diff image highlights pixels where any channel difference exceeds 10. diffPercent is the ratio of such pixels.

      如果 b 的尺寸不同，会缩放至与 a 相同。差异图高亮任一通道差值超过 10 的像素。 diffPercent 为此类像素的比例。

      Parameters:
      a - first image (reference) | 第一幅图像（参考）
      b - second image (comparison) | 第二幅图像（比较）
      Returns:
      diff result containing difference image and percentage | 包含差异图和百分比的结果
      Throws:
      NullPointerException - if either image is null | 任一图像为 null 时抛出
      ImageOperationException - if either image has zero dimensions | 图像尺寸为零时抛出

    • ssim

      public static double ssim(BufferedImage a, BufferedImage b)
      Compute Structural Similarity Index (SSIM) between two images. 计算两幅图像之间的结构相似性指数 (SSIM)。

      Uses an 11x11 sliding window with box averaging. Both images are converted to grayscale first. If b has different dimensions, it is resized to match a.

      使用 11x11 滑动窗口的简单均值。两幅图像首先转换为灰度图。 如果 b 的尺寸不同，会缩放至与 a 相同。

      Parameters:
      a - first image (reference) | 第一幅图像（参考）
      b - second image (comparison) | 第二幅图像（比较）
      Returns:
      SSIM value in range [0.0, 1.0] | SSIM 值，范围 [0.0, 1.0]
      Throws:
      NullPointerException - if either image is null | 任一图像为 null 时抛出
      ImageOperationException - if either image has zero dimensions | 图像尺寸为零时抛出

    • mse

      public static double mse(BufferedImage a, BufferedImage b)
      Compute Mean Squared Error (MSE) between two images. 计算两幅图像之间的均方误差 (MSE)。

      Computes MSE across all RGB channels. If b has different dimensions, it is resized to match a.

      在所有 RGB 通道上计算 MSE。如果 b 的尺寸不同，会缩放至与 a 相同。

      Parameters:
      a - first image (reference) | 第一幅图像（参考）
      b - second image (comparison) | 第二幅图像（比较）
      Returns:
      MSE value (0.0 for identical images) | MSE 值（相同图像为 0.0）
      Throws:
      NullPointerException - if either image is null | 任一图像为 null 时抛出
      ImageOperationException - if either image has zero dimensions | 图像尺寸为零时抛出

    • psnr

      public static double psnr(BufferedImage a, BufferedImage b)
      Compute Peak Signal-to-Noise Ratio (PSNR) between two images. 计算两幅图像之间的峰值信噪比 (PSNR)。

      PSNR = 10 * log10(255^2 / MSE). Returns Double.POSITIVE_INFINITY when the images are identical (MSE = 0).

      PSNR = 10 * log10(255^2 / MSE)。当图像相同时（MSE = 0）返回正无穷。

      Parameters:
      a - first image (reference) | 第一幅图像（参考）
      b - second image (comparison) | 第二幅图像（比较）
      Returns:
      PSNR in dB, or POSITIVE_INFINITY for identical images | PSNR 分贝值，相同图像返回正无穷
      Throws:
      NullPointerException - if either image is null | 任一图像为 null 时抛出
      ImageOperationException - if either image has zero dimensions | 图像尺寸为零时抛出