libphash¶

Perceptual image hashing in C. Nine algorithms that turn an image into a short fingerprint, so that a resized copy, a recompressed JPEG or a slightly brighter version of a picture lands a few bits away from the original, while an unrelated picture lands about half the bits away.

Above, pHash as the library computes it: the copies keep the original's hash, or nearly, and the unrelated photograph differs in about half of the 64 bits, which is what two unrelated hashes do by chance. The same file gives the same hash on Linux, macOS and Windows, on x86-64 and arm64, in any build with the same JPEG decoder.

What it looks like¶

/* Loads an image and prints its pHash. Build/run:
 *   cc basic_hash.c -o basic_hash $(pkg-config --cflags --libs libphash)
 *   ./basic_hash path/to/image.jpg
 */
#include <libphash.h>
#include <stdio.h>

int main(int argc, char **argv) {
    if (argc != 2) {
        fprintf(stderr, "usage: %s <image>\n", argv[0]);
        return 1;
    }

    ph_context_t *ctx = NULL;
    if (ph_create(&ctx) != PH_SUCCESS) {
        fprintf(stderr, "ph_create failed\n");
        return 1;
    }

    /* Fast grayscale loading: skips the RGB-to-gray conversion pass. Fine here since
     * pHash only ever operates on grayscale; skip this call to load in color if you
     * also want a color hash (ph_compute_color_hash(), ph_compute_color_moments_hash())
     * from the same load. */
    ph_context_set_load_grayscale(ctx, 1);

    ph_error_t err = ph_load_from_file(ctx, argv[1]);
    if (err != PH_SUCCESS) {
        fprintf(stderr, "failed to load %s: %s (%s)\n", argv[1], ph_get_error_string(err),
                ph_get_last_error_message(ctx));
        ph_free(ctx);
        return 1;
    }

    uint64_t hash = 0;
    err = ph_compute_phash(ctx, &hash);
    if (err != PH_SUCCESS) {
        fprintf(stderr, "ph_compute_phash failed: %s\n", ph_get_error_string(err));
        ph_free(ctx);
        return 1;
    }

    char hex[17];
    if (ph_hash_to_hex(hash, hex, sizeof(hex)) != PH_SUCCESS) {
        fprintf(stderr, "ph_hash_to_hex failed\n");
        ph_free(ctx);
        return 1;
    }
    printf("pHash: %s\n", hex);

    ph_free(ctx);
    return 0;
}

cc basic_hash.c -o basic_hash $(pkg-config --cflags --libs libphash)
./basic_hash photo.jpg

What it is for, and what it is not¶

For finding duplicate and near-duplicate images in a collection you control: deduplicating an archive, clustering a catalog, keying a cache, answering "have I stored this before" inside a trusted pipeline.

Not for anything where someone benefits from a wrong answer. Every hash here is deterministic and unkeyed, which is what makes deduplication work and also what makes the hashes straightforward to defeat on purpose. Content moderation, copyright blocklists and integrity checks on untrusted input need keyed algorithms, and none is implemented here. The reasoning and the citations are in the threat model.

Nine algorithms, one pipeline¶

flowchart LR
    A[File or buffer] --> B[Decode]
    B --> C[Orient, grayscale]
    C --> D[Reduce]
    D --> E1[aHash · dHash · pHash · wHash<br/>64-bit hash]
    D --> E2[mHash · BMH · Radial<br/>digest]
    B --> E3[ColorHash · ColorMoments<br/>color digest]

The four 64-bit hashes are compared by Hamming distance; the others return a digest with its own distance function. How libphash works follows an image through these steps; each algorithm has its own page under Theory.

Performance¶

Decoding a JPEG, and each hash at its defaults on the decoded image, one thread¹:

The four 64-bit hashes and BMH cost a small fraction of the decode. mHash and Radial pass a filter over the image, and cost more than decoding a small one; on a large image they and the two color hashes come closest to the decode. Performance has the times against image size and format, and what lowers them.

Also available¶

• Python: python-libphash (pip install python-libphash).
• Upgrading from 1.x: some hash values change silently; read Migrating from 1.x first.