img_hash_linker

A Rust library and CLI tool for linking images to URLs via perceptual hashing.

Overview

img_hash_linker computes perceptual image hashes (using the aHash algorithm) and associates them with URLs, allowing you to:

1. Compute perceptual hashes of images with configurable hash sizes
2. Link images to URLs via their perceptual hash
3. Find exact matches or similar images within a proximity threshold
4. Open the appropriate URL when given an image

Installation

CLI Tool

cargo install img_hash_linker

Rust Crate

Add this to your Cargo.toml:

[dependencies]
img_hash_linker = "1.1.0"

Usage

CLI Usage

The binary interface provides image hash computation and URL opening:

# Compute and display an image hash
img_hash_linker <image_path>

# Open a URL associated with an image
img_hash_linker <image_path> <csv_dict_path>

Where:

• <image_path> is the path to the image file
• <csv_dict_path> is the path to a CSV file containing hash-URL pairs (example in example.csv)

Library Usage

use img_hash_linker::{
    compute_hash,
    load_data_from_csv,
    open_link_from_hash,
    try_finding_similar_hash
};

let image_path = "path/to/image.jpg";
let dict_path = "path/to/links.csv";

// Configure hash size (optional, defaults to 8)
let hash_size: Option<u32> = Some(8); // Can also be None

// Compute hash from image
let hash: String = compute_hash(
    image::open(image_path).unwrap(),
    true,       // remove white borders
    hash_size   // hash size configuration
).unwrap();

// Load hash-URL pairs from CSV
let links: Vec<(String, String)> = load_data_from_csv(dict_path).unwrap();

// Try to find exact match first
match open_link_from_hash(links.clone(), hash.clone()) {
    Ok(message) => println!("{}", message), // Found exact match
    Err(e) => {
        // If no exact match, try finding similar hash
        match try_finding_similar_hash(hash.clone(), links.clone(), None) {
            Ok((similar_hash, _link, proximity)) => {
                println!(
                    "{} (Proximity: {:.2}%)",
                    open_link_from_hash(links.clone(), similar_hash).unwrap(),
                    proximity * 100.0
                );
            }
            Err(_) => {
                println!("{}", e);
            }
        }
    }
}

CSV Format

The CSV file should contain hash-URL pairs with headers:

hash,link
hash1,https://example.com/page1
hash2,https://example.com/page2

Important: The CSV must have hash and link headers. Additional fields are allowed but will be ignored.

Note: URLs can also be application URL handlers like spotify:// or vscode://.

Understanding the aHash Algorithm

The Average Hash (aHash) algorithm creates a perceptual hash of an image through these steps:

1. Resize the image to N×N pixels (configurable through "hash_size" parameter, default 8×8 = 64 pixels total)
2. Convert to grayscale
3. Calculate the average pixel value across all pixels
4. Compare each pixel to the average:
   • If a pixel's value is greater than or equal to the average, set the corresponding bit to 1
   • Otherwise, set it to 0
5. Output the resulting bits as a hexadecimal string

This creates a "fingerprint" of the image that:

• Is resilient to minor modifications (resizing, compression, etc.)
• Can identify visually similar images
• Is compact (configurable size, default 64 bits)
• Supports similarity matching within proximity thresholds

Hash Size Configuration

• Default: 8×8 (64 bits, 16 hex characters)
• Configurable: Any size N×N where N is specified
• Trade-off: Larger sizes provide more specific detail but less resilience to modifications (something like 8 or even shorter is perfect)

Features

• Fast, lightweight perceptual image hashing
• Configurable hash sizes for different use cases
• Automatic white border removal for consistent hashing
• Exact match and similarity-based hash matching
• Proximity scoring for similar images
• Support for both CLI and library usage
• Simple CSV-based hash-to-URL mapping

License

MIT