Comparing hashes¶

Distances and similarities, one per kind of digest.

Constants¶

PH_RADIAL_PCC_THRESHOLD¶

#define PH_RADIAL_PCC_THRESHOLD 0.9

The peak-of-cross-correlation threshold the radial hash's source uses, 0.9.

pHash treats two radial digests correlating at or above this as the same image (Zauner, Diplomarbeit FH Hagenberg 2010, section 3.2.3). It is provided as a starting point with a citation behind it, not as a tuned recommendation for your corpus: ph_radial_similarity() hands back the raw score so that you can pick your own cut, measured on your own images. What 0.9 accepts on two corpora is measured in Comparing hashes.

Explained in Comparing hashes · Radial — Radial Variance Hash

Functions¶

ph_hamming_distance()¶

int ph_hamming_distance(uint64_t hash1, uint64_t hash2);

returns int

Number of differing bits between two 64-bit hashes, 0 to 64.

For aHash, dHash, pHash and wHash values. Only meaningful between two hashes of the same algorithm, computed with the same settings.

Used in compare_two_images.c · find_duplicates.c · hash_distance.c

Explained in Quick start · Storing and searching hashes · aHash — Average Hash · Comparing hashes · dHash — Difference Hash · Perceptual hashing · pHash — Perceptual Hash · wHash — Wavelet Hash

ph_similarity()¶

double ph_similarity(uint64_t a, uint64_t b);

returns double

Normalized similarity between two 64-bit hashes, in [0.0, 1.0].

1.0 means identical hashes, 0.0 means every bit differs, and two unrelated images land near 0.5. The scale is shared with ph_similarity_digest() for digests of any length; a threshold is not, since how close a copy comes depends on the algorithm. See Comparing hashes.

Used in compare_two_images.c

Explained in Comparing hashes · Perceptual hashing

Comparing digests¶

The contract shared by every function below that reads a ph_digest_t.

ph_digest_t is a flat struct callers (including FFI bindings) may fill in themselves, and size can hold values data cannot: a digest whose size exceeds PH_DIGEST_MAX_BYTES is rejected, never truncated.

The kind tag is checked too. Each comparison below states the kind it is for, and refuses a digest tagged as something else: Hamming distance over quantized DCT coefficients returns a plausible number that means nothing, and this is how that call fails instead. PH_DIGEST_KIND_UNSPECIFIED – the zero a hand-filled struct holds – is accepted everywhere, so a binding that does not set the field gets no protection but no error either. A digest that breaks the contract gets:

• functions returning ph_error_t: PH_ERR_INVALID_ARGUMENT;
• distance/similarity functions: -1 (also for a size of 0, which carries no bits to compare – reporting distance 0 there would read as "identical").

ph_hamming_distance_digest() and ph_similarity_digest() are for PH_DIGEST_KIND_BITS; ph_l2_distance() is for PH_DIGEST_KIND_VECTOR and PH_DIGEST_KIND_VECTOR16; ph_radial_similarity() is for PH_DIGEST_KIND_COEFFICIENTS; ph_histogram_intersection() is for PH_DIGEST_KIND_HISTOGRAM.

ph_hamming_distance_digest()¶

int ph_hamming_distance_digest(const ph_digest_t *a, const ph_digest_t *b);

returns int

Number of differing bits between two PH_DIGEST_KIND_BITS digests (mHash, BMH, or a 64-bit hash taken as a digest).

Returns 0 to 8 times the digest size; -1 for anything the digest contract above rejects: NULL, mismatched or invalid sizes, or another kind.

Used in digest_and_metrics.c

Explained in Storing and searching hashes · BMH — Block Mean Hash · Comparing hashes · mHash — Marr–Hildreth Hash

ph_l2_distance()¶

double ph_l2_distance(const ph_digest_t *a, const ph_digest_t *b);

returns double

Euclidean distance between two feature vectors: PH_DIGEST_KIND_VECTOR16 (ColorMoments, decoded from its 16-bit fixed point) or PH_DIGEST_KIND_VECTOR (one unsigned byte per feature).

Returns 0.0 or more, in the features' own units; -1.0 for anything the digest contract above rejects: NULL, mismatched or invalid sizes, or another kind.

Used in digest_and_metrics.c

Explained in ColorMoments — Color Moments · Comparing hashes

ph_similarity_digest()¶

double ph_similarity_digest(const ph_digest_t *a, const ph_digest_t *b);

returns double

Normalized similarity between two digests, in [0.0, 1.0].

Returns -1.0 for anything the digest contract above rejects: NULL, mismatched or invalid sizes, or a kind other than PH_DIGEST_KIND_BITS.

Used in digest_and_metrics.c

Explained in aHash — Average Hash · BMH — Block Mean Hash · Comparing hashes · dHash — Difference Hash · mHash — Marr–Hildreth Hash · pHash — Perceptual Hash · wHash — Wavelet Hash

ph_radial_similarity()¶

ph_error_t ph_radial_similarity(
    const ph_digest_t *a,
    const ph_digest_t *b,
    double *out_pcc);

nodiscard · returns ph_error_t

Compares two radial digests the way the algorithm's source specifies: by the peak of their cross-correlation over all cyclic shifts.

The Pearson correlation of the two digests' bytes, computed with b shifted cyclically by each of 0 to size - 1 places; the largest of them. It runs from -1.0 to 1.0, and 1.0 means the same profile up to a shift. Compare it against PH_RADIAL_PCC_THRESHOLD, or against your own measured cut. The sums are exact integers and the score is rounded once, at the end, so it is the same on every machine and symmetric in a and b to the last bit. See Radial — Radial Variance Hash.

A digest with all bytes equal – the all-zero digest ph_compute_radial_hash() gives an image with no angular structure – has no correlation with anything: any number would be invented, and 1.0 would call two unrelated flat images identical. Such a pair is answered with PH_ERR_NO_STRUCTURE; whether "no data" counts as a match is the caller's decision.

Parameters

Returns PH_SUCCESS; PH_ERR_NO_STRUCTURE if either digest has all bytes equal; PH_ERR_INVALID_ARGUMENT for a NULL argument, an invalid or empty digest, two digests of different sizes, or a digest of another kind.

Used in digest_and_metrics.c

Explained in Handling errors · Comparing hashes · Radial — Radial Variance Hash

ph_histogram_intersection()¶

ph_error_t ph_histogram_intersection(
    const ph_digest_t *a,
    const ph_digest_t *b,
    double *out_similarity);

nodiscard · returns ph_error_t

Compares two color histograms by their intersection: sum(min(a_i, b_i)) over bins, each histogram normalized by its own total.

The measure Swain & Ballard define, and the reason a histogram is worth keeping: it counts only what the two images have in common, so a change of background or a partial overlap costs only the part that differs.

Runs from 0.0 (no color in common) to 1.0 (identical distributions). Two empty histograms score 1.0; an empty one against a populated one scores 0.0.

Parameters

Returns PH_SUCCESS, or PH_ERR_INVALID_ARGUMENT for a NULL argument, an invalid or empty digest, two digests of different sizes, or a digest tagged as something other than a histogram.

Used in digest_and_metrics.c

Explained in Handling errors · ColorHash — Color Histogram · Comparing hashes