imghash

To use imghash in your Node.js project, install it using npm:

npm install imghash

To determine if two images are perceptually similar, calculate the distance between their hashes. You can use algorithms like Hamming distance or Levenshtein Distance.

Example using leven:

const imghash = require("imghash");
const leven = require("leven");

const hash1 = await imghash.hash("./img1");
const hash2 = await imghash.hash("./img2");

const distance = leven(hash1, hash2);
console.log(`Distance between images is: ${distance}`);

// Threshold check (example threshold: 12)
if (distance <= 12) {
  console.log("Images are similar");
} else {
  console.log("Images are NOT similar");
}

Use .hashRaw() to generate a hex hash directly from decoded image pixel data without reading from a file.

Parameters:

• data: An object describing the image data: { width: [width], height: [height], data: [decoded image pixels] }.
• bits: The desired hash length.

Returns: A hex hash string.

// Example structure for the data parameter
const data = { width: 100, height: 100, data: [...] };
const hash = await imghash.hashRaw(data, 8);

Use these utility methods to switch between binary and hexadecimal representations of a hash.

• .hexToBinary(s): Converts a hex string (e.g., f884c4d8d1193c07) to a binary string (e.g., 1000100010000010).
• .binaryToHex(s): Converts a binary string to a hex string.

const hex = imghash.hexToBinary("f884c4d8d1193c07");
const binary = imghash.binaryToHex("1000100010000010");

The .hash() method is the primary way to generate a perceptual hash from an image file or buffer. It returns a Promise that resolves to a hash string.

Parameters:

• filepath: Path to a png or jpeg file, or a Buffer containing image data.
• bits (optional): The desired hash length. Defaults to 8.
• format (optional): The output format. Defaults to hex.

Example usage:

const imghash = require("imghash");

// Default hex hash
const hash1 = await imghash.hash("./path/to/file");
console.log(hash1); // e.g., "f884c4d8d1193c07"

// Custom length and binary format
const hash2 = await imghash.hash("./path/to/file", 4, "binary");
console.log(hash2); // e.g., "1000100010000010"

The hashRaw function allows you to generate a hash directly from ImageData without the file loading or decoding overhead. This is useful if you are already working with canvas or decoded image data.

Parameters:

• data: An ImageData object.
• bits: The number of bits for the hash.

Returns: A Promise<string> (the raw hex hash).

import { hashRaw } from 'imghash';

// Assuming imageData is obtained from a canvas or similar source
const rawHash = await hashRaw(imageData, 8);

The API provides utility functions to convert hash strings between hexadecimal and binary representations.

• hexToBinary(s: string): Converts a hexadecimal hash string to a binary string.
• binaryToHex(s: string): Converts a binary hash string to a hexadecimal string.

import { hexToBinary, binaryToHex } from 'imghash';

const hex = 'a1b2';
const binary = hexToBinary(hex);

const backToHex = binaryToHex(binary);
// backToHex === 'a1b2'