Class PerceptualHash

java.lang.Object
cloud.opencode.base.image.compare.PerceptualHash
public final class PerceptualHash extends Object
Perceptual Hash — image fingerprinting via aHash, dHash, pHash 感知哈希 — 通过 aHash、dHash、pHash 实现图像指纹

Provides three perceptual hashing algorithms that produce compact 64-bit fingerprints for images. Similar images yield similar hashes, enabling fast near-duplicate detection.

提供三种感知哈希算法，为图像生成紧凑的 64 位指纹。相似图像产生相似的哈希值， 可用于快速近似重复检测。

Features | 主要功能:

  • aHash — average hash based on 8x8 grayscale mean - 基于 8x8 灰度均值的平均哈希
  • dHash — difference hash based on adjacent column gradients - 基于相邻列梯度的差异哈希
  • pHash — perceptual hash based on DCT frequency domain - 基于 DCT 频域的感知哈希
  • Hamming distance and similarity comparison - 汉明距离与相似度比较

Usage Examples | 使用示例:

long h1 = PerceptualHash.pHash(image1);
long h2 = PerceptualHash.pHash(image2);
int dist = PerceptualHash.hammingDistance(h1, h2);
double sim = PerceptualHash.similarity(h1, h2);

Performance | 性能特性:

  • aHash/dHash: O(1) — fixed 8x8/9x8 downscale - 固定缩放尺寸
  • pHash: O(1) — fixed 32x32 DCT, only top-left 8x8 coefficients - 固定 32x32 DCT

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

    • aHash

      public static long aHash(BufferedImage image)
      Compute average hash (aHash) for an image. 计算图像的平均哈希 (aHash)。

      Scales to 8x8 grayscale, computes the mean pixel value, and produces a 64-bit hash where each bit indicates whether the pixel is above the mean.

      缩放至 8x8 灰度图，计算像素均值，产生 64 位哈希，每位表示像素是否高于均值。

      Parameters:
      image - the source image | 源图像
      Returns:
      64-bit average hash | 64 位平均哈希值
      Throws:
      NullPointerException - if image is null | 图像为 null 时抛出
      ImageOperationException - if image has zero dimensions | 图像尺寸为零时抛出

    • dHash

      public static long dHash(BufferedImage image)
      Compute difference hash (dHash) for an image. 计算图像的差异哈希 (dHash)。

      Scales to 9x8 grayscale and compares adjacent columns, producing a 64-bit hash where each bit indicates whether the left pixel is brighter than the right.

      缩放至 9x8 灰度图，比较相邻列像素，产生 64 位哈希，每位表示左像素是否比右像素亮。

      Parameters:
      image - the source image | 源图像
      Returns:
      64-bit difference hash | 64 位差异哈希值
      Throws:
      NullPointerException - if image is null | 图像为 null 时抛出
      ImageOperationException - if image has zero dimensions | 图像尺寸为零时抛出

    • pHash

      public static long pHash(BufferedImage image)
      Compute perceptual hash (pHash) for an image. 计算图像的感知哈希 (pHash)。

      Scales to 32x32 grayscale, applies Type-II DCT, takes the top-left 8x8 coefficients (excluding DC), and produces a 64-bit hash based on the median coefficient value.

      缩放至 32x32 灰度图，应用 Type-II DCT，取左上 8x8 系数（排除 DC）， 根据中值系数产生 64 位哈希。

      Parameters:
      image - the source image | 源图像
      Returns:
      64-bit perceptual hash | 64 位感知哈希值
      Throws:
      NullPointerException - if image is null | 图像为 null 时抛出
      ImageOperationException - if image has zero dimensions | 图像尺寸为零时抛出

    • hammingDistance

      public static int hammingDistance(long hash1, long hash2)
      Compute the Hamming distance between two hashes. 计算两个哈希值之间的汉明距离。
      Parameters:
      hash1 - first hash | 第一个哈希值
      hash2 - second hash | 第二个哈希值
      Returns:
      number of differing bits (0–64) | 不同位的数量 (0–64)

    • similarity

      public static double similarity(long hash1, long hash2)
      Compute the similarity between two hashes as a value between 0.0 and 1.0. 计算两个哈希值之间的相似度，值域 0.0 到 1.0。
      Parameters:
      hash1 - first hash | 第一个哈希值
      hash2 - second hash | 第二个哈希值
      Returns:
      similarity in range [0.0, 1.0] | 相似度，范围 [0.0, 1.0]