image-hash-native

A fast, native Node.js addon for calculating image hashes (Average Hash, Difference Hash, Perceptual Hash) and comparing them using Hamming distance.

Installation

npm install image-hash-native
# or
pnpm add image-hash-native

Usage

This library operates on raw image buffers (RGB). You can use image processing libraries like sharp to convert images into the required format.

Example with sharp

const { aHash, dHash, pHash, hamming } = require('image-hash-native');
const sharp = require('sharp');

(async () => {
    // Read an image and convert to raw RGB buffer
    const { data, info } = await sharp('image.jpg')
        .raw()
        .toBuffer({ resolveWithObject: true });

    // Calculate hashes
    const ah = aHash(data, info.width, info.height);
    const dh = dHash(data, info.width, info.height);
    const ph = pHash(data, info.width, info.height);

    console.log(`Average Hash: ${ah.toString(16)}`);
    console.log(`Difference Hash: ${dh.toString(16)}`);
    console.log(`Perceptual Hash: ${ph.toString(16)}`);

    // Compare hashes
    const distance = hamming(ah, ph);
    console.log(`Hamming Distance: ${distance}`);
})();

API

aHash(buffer, width, height)

Calculates the Average Hash.

• buffer: Buffer - Raw image data (RGB).
• width: number - Image width.
• height: number - Image height.
• Returns: bigint - The 64-bit hash.

dHash(buffer, width, height)

Calculates the Difference Hash.

• buffer: Buffer - Raw image data (RGB).
• width: number - Image width.
• height: number - Image height.
• Returns: bigint - The 64-bit hash.

pHash(buffer, width, height)

Calculates the Perceptual Hash.

• buffer: Buffer - Raw image data (RGB).
• width: number - Image width.
• height: number - Image height.
• Returns: bigint - The 64-bit hash.

hamming(hash1, hash2)

Calculates the Hamming distance between two hashes.

• hash1: bigint
• hash2: bigint
• Returns: number - The number of differing bits (0-64).