Crate imgfprint 

High-performance, deterministic image fingerprinting library.

Provides perceptual hashing with crop resistance for image deduplication and similarity detection in production systems.

Supports multiple algorithms (PHash, DHash) with automatic parallel computation for improved accuracy.

Quick Start

Compute all hashes (recommended for best accuracy):

use imgfprint::ImageFingerprinter;
let fp1 = ImageFingerprinter::fingerprint(&std::fs::read("img1.jpg")?)?;
let fp2 = ImageFingerprinter::fingerprint(&std::fs::read("img2.jpg")?)?;

let sim = fp1.compare(&fp2);
println!("Similarity: {:.2}", sim.score);

Compute specific algorithm only:

use imgfprint::{ImageFingerprinter, HashAlgorithm};

let fp = ImageFingerprinter::fingerprint_with(
    &std::fs::read("img1.jpg")?,
    HashAlgorithm::DHash
)?;

High-Throughput Usage

For processing many images, use FingerprinterContext to enable buffer reuse and avoid repeated allocations:

use imgfprint::FingerprinterContext;

let mut ctx = FingerprinterContext::new();

// Process multiple images efficiently
for path in &["img1.jpg", "img2.jpg", "img3.jpg"] {
    let fp = ctx.fingerprint(&std::fs::read(path)?)?;
    // Use fingerprint...
}

Performance Features

• SIMD-accelerated resize: Uses AVX2/NEON instructions for 3-4x faster resizing
• Cached DCT plans: Reuses DCT computation plans across all calls
• Buffer reuse: Context API minimizes allocations in high-throughput scenarios
• Parallel processing: Batch operations use rayon for multi-core speedup

Structs

Embedding

A semantic embedding vector representing image content.

FingerprinterContext

Context for high-performance fingerprinting with buffer reuse.

ImageFingerprint

A perceptual fingerprint containing multiple hash layers for robust comparison.

ImageFingerprinter

Static methods for computing and comparing image fingerprints.

MultiHashConfig

Tunable weights and thresholds for MultiHashFingerprint::compare_with_config.

MultiHashFingerprint

A multi-algorithm fingerprint containing hashes from multiple perceptual algorithms.

PreprocessConfig

Decode-time guards that an integrator (UCFP, server pipelines) can tune.

Similarity

Similarity score between two image fingerprints.

Enums

HashAlgorithm

Available perceptual hash algorithms.

ImgFprintError

Errors that can occur during image fingerprinting.

Constants

DEFAULT_AHASH_WEIGHT

Default weight for AHash in the combined score (10%).

DEFAULT_BLOCK_DISTANCE_THRESHOLD

Default maximum Hamming distance for a block to count as a valid match (32 of 64).

DEFAULT_BLOCK_WEIGHT

Default weight for the block-level hashes inside each per-algorithm similarity (60%).

DEFAULT_DHASH_WEIGHT

Default weight for DHash in the combined score (30%).

DEFAULT_GLOBAL_WEIGHT

Default weight for the global hash inside each per-algorithm similarity (40%).

DEFAULT_MAX_DIMENSION

Default maximum image edge length, in pixels. Beyond this, decode is rejected.

DEFAULT_MAX_INPUT_BYTES

Default maximum input size, in bytes (50 MiB).

DEFAULT_MIN_DIMENSION

Default minimum image edge length, in pixels. Below this, decode is rejected.

DEFAULT_PHASH_WEIGHT

Default weight for PHash in the combined score (60%).

FORMAT_VERSION

On-disk format version of the binary fingerprint representation.

Traits

EmbeddingProvider

Trait for embedding providers.

Functions

decode_image

Decodes image bytes, validates dimensions, and applies EXIF orientation.

decode_image_with_config

Decodes image bytes with a tunable PreprocessConfig.

semantic_similarity

Computes cosine similarity between two embeddings.