module

CrImage::Util::Metrics

Class methods

hamming_distance(hash1 : UInt64, hash2 : UInt64) : Int32

Calculates Hamming distance between two perceptual hashes.

Hamming distance counts the number of differing bits. Lower values indicate more similar images.

Parameters:

  • hash1 : First perceptual hash
  • hash2 : Second perceptual hash

Returns: Number of differing bits (0-64)

Example:

distance = CrImage::Util::Metrics.hamming_distance(hash1, hash2)
puts "Very similar" if distance < 5
puts "Similar" if distance < 10
puts "Different" if distance >= 10
Source
mse(img1 : Image, img2 : Image) : Float64

Calculates Mean Squared Error (MSE) between two images.

MSE measures the average squared difference between corresponding pixels. Lower values indicate more similar images. 0 means identical images.

Parameters:

  • img1 : First image
  • img2 : Second image

Returns: MSE value (0.0 = identical, higher = more different)

Raises: ArgumentError if images have different dimensions

Example:

original = CrImage::PNG.read("original.png")
compressed = CrImage::JPEG.read("compressed.jpg")
mse = CrImage::Util::Metrics.mse(original, compressed)
puts "MSE: #{mse}"
Source
perceptual_hash(img : Image) : UInt64

Calculates a perceptual hash (pHash) for image similarity detection.

Perceptual hashing creates a compact fingerprint of an image that remains similar even after transformations like resizing, compression, or minor edits. Useful for duplicate detection.

The hash is a 64-bit integer where Hamming distance indicates similarity. Hamming distance < 10 typically indicates similar images.

Parameters:

  • img : The image to hash

Returns: 64-bit perceptual hash

Example:

img1 = CrImage::PNG.read("photo1.png")
img2 = CrImage::PNG.read("photo2.png")
hash1 = CrImage::Util::Metrics.perceptual_hash(img1)
hash2 = CrImage::Util::Metrics.perceptual_hash(img2)
distance = hamming_distance(hash1, hash2)
puts "Similar!" if distance < 10
Source
psnr(img1 : Image, img2 : Image) : Float64

Calculates Peak Signal-to-Noise Ratio (PSNR) between two images.

PSNR is a quality metric expressed in decibels (dB). Higher values indicate better quality/similarity. Commonly used for compression quality.

Typical values:

  • 40 dB: Excellent quality

  • 30-40 dB: Good quality
  • 20-30 dB: Acceptable quality
  • < 20 dB: Poor quality

Parameters:

  • img1 : First image (typically original)
  • img2 : Second image (typically compressed/processed)

Returns: PSNR value in dB (higher = better quality)

Raises: ArgumentError if images have different dimensions

Example:

original = CrImage::PNG.read("original.png")
compressed = CrImage::JPEG.read("compressed.jpg")
psnr = CrImage::Util::Metrics.psnr(original, compressed)
puts "PSNR: #{psnr.round(2)} dB"
Source
ssim(img1 : Image, img2 : Image, window_size : Int32 = 11) : Float64

Calculates Structural Similarity Index (SSIM) between two images.

SSIM measures perceived quality by comparing luminance, contrast, and structure. Returns a value between -1 and 1, where 1 means identical. More perceptually accurate than MSE/PSNR.

Parameters:

  • img1 : First image
  • img2 : Second image
  • window_size : Size of sliding window (default: 11)

Returns: SSIM value (-1 to 1, where 1 = identical)

Raises: ArgumentError if images have different dimensions

Example:

original = CrImage::PNG.read("original.png")
processed = CrImage::PNG.read("processed.png")
ssim = CrImage::Util::Metrics.ssim(original, processed)
puts "SSIM: #{ssim.round(4)}"
Source