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.RasterDiffResult diff(Raster a, Raster b)
      Compute pixel-level diff between two equally-sized Rasters. 计算两个尺寸相同的 Raster 之间的像素级差异。

      Both rasters must have matching dimensions; no implicit resize is performed. Pixels with any RGB channel difference exceeding 10 are highlighted in red.

      两个 raster 必须尺寸相同，不会隐式缩放。任一 RGB 通道差值超过 10 的像素以红色高亮。

      Parameters:
      a - first raster (reference) | 第一个 raster（参考）
      b - second raster (comparison) | 第二个 raster（比较）
      Returns:
      the diff result | 差异结果
      Throws:
      NullPointerException - if either raster is null | 任一 raster 为 null 时抛出
      ImageOperationException - if dimensions are invalid or mismatched | 当尺寸无效或不一致时抛出
      Since:
      opencode-base-image V1.0.4

    • ssim

      public static double ssim(Raster a, Raster b)
      Compute SSIM between two equally-sized Rasters. 计算两个尺寸相同 Raster 之间的 SSIM。
      Parameters:
      a - first raster (reference) | 第一个 raster（参考）
      b - second raster (comparison) | 第二个 raster（比较）
      Returns:
      SSIM in [0.0, 1.0] | SSIM 值
      Throws:
      NullPointerException - if either is null | 任一 raster 为 null 时抛出
      ImageOperationException - if dimensions are invalid or mismatched | 当尺寸无效或不一致时抛出
      Since:
      opencode-base-image V1.0.4

    • mse

      public static double mse(Raster a, Raster b)
      Compute MSE between two equally-sized Rasters across RGB channels. 在 RGB 通道上计算两个尺寸相同 Raster 之间的 MSE。
      Parameters:
      a - first raster | 第一个 raster
      b - second raster | 第二个 raster
      Returns:
      MSE value (0.0 for identical rasters) | MSE 值（相同时为 0.0）
      Throws:
      NullPointerException - if either is null | 任一为 null 时抛出
      ImageOperationException - if dimensions are invalid or mismatched | 尺寸无效或不一致时抛出
      Since:
      opencode-base-image V1.0.4

    • psnr

      public static double psnr(Raster a, Raster b)
      Compute PSNR between two equally-sized Rasters. 计算两个尺寸相同 Raster 之间的 PSNR。
      Parameters:
      a - first raster | 第一个 raster
      b - second raster | 第二个 raster
      Returns:
      PSNR in dB, or POSITIVE_INFINITY for identical rasters | PSNR 分贝值，相同时为正无穷
      Throws:
      NullPointerException - if either is null | 任一为 null 时抛出
      ImageOperationException - if dimensions are invalid or mismatched | 尺寸无效或不一致时抛出
      Since:
      opencode-base-image V1.0.4