Skip to main content

rosetta_squint_hash/
lib.rs

1//! rosetta-squint-hash — Byte-exact Rust port of Python imagehash 4.3.2.
2//!
3//! Public API: `Hash`, `ImageMultiHash`, `ImageHashError`, `hex_to_hash`,
4//! `hex_to_flathash`, `hex_to_multihash`, and the algorithm functions.
5
6// Rust 1.95 clippy tightens some style lints that conflict with the
7// byte-exact-port style of this crate (manual loops + casts mirror the
8// reference Python). Suppress the noisy ones at crate level; the
9// substantive lints remain on.
10#![allow(clippy::needless_range_loop)]
11#![allow(clippy::type_complexity)]
12#![allow(clippy::manual_div_ceil)]
13#![allow(clippy::manual_memcpy)]
14#![allow(clippy::iter_cloned_collect)]
15#![allow(clippy::ptr_arg)]
16#![allow(clippy::redundant_closure)]
17#![allow(clippy::unnecessary_sort_by)]
18#![allow(clippy::useless_vec)]
19
20#[doc(hidden)]
21pub mod internal;
22
23mod hex;
24pub use hex::{hex_to_flathash, hex_to_hash};
25
26mod average;
27pub use average::average_hash;
28
29mod dhash;
30pub use dhash::{dhash, dhash_vertical};
31
32mod phash;
33pub use phash::{phash, phash_simple, phash_simple_with_factor, phash_with_factor, SNAP_EPS};
34
35mod whash;
36pub use whash::{whash_db4, whash_db4_robust, whash_haar, WHASH_DB4_ROBUST_EPS};
37
38mod colorhash;
39pub use colorhash::{colorhash, colorhash_bin_encode};
40
41mod multihash;
42pub use multihash::{hex_to_multihash, ImageMultiHash};
43
44mod crop_resistant;
45pub use crop_resistant::crop_resistant_hash;
46
47use std::fmt;
48
49#[derive(Debug, thiserror::Error)]
50pub enum ImageHashError {
51    #[error("hash_size must be >= 2, got {0}")]
52    InvalidHashSize(usize),
53    #[error("hash_size must be a power of 2 for whash, got {0}")]
54    NotPowerOfTwo(usize),
55    #[error("hash_size too large for image: level={level} > ll_max_level={ll_max_level}")]
56    HashSizeTooLarge { level: usize, ll_max_level: usize },
57    #[error("binbits must be >= 1, got {0}")]
58    InvalidBinbits(usize),
59    #[error("invalid hex: {0}")]
60    InvalidHex(String),
61    #[error("shapes don't match: this=({h1},{w1}), other=({h2},{w2})")]
62    ShapeMismatch { h1: usize, w1: usize, h2: usize, w2: usize },
63    #[error("bits must be non-empty")]
64    EmptyBits,
65    #[error("bits must be rectangular; got widths {expected} and {got}")]
66    NonRectangular { expected: usize, got: usize },
67}
68
69#[derive(Debug, Clone, PartialEq, Eq)]
70pub struct Hash {
71    bits: Vec<Vec<bool>>,
72}
73
74impl Hash {
75    pub fn new(bits: Vec<Vec<bool>>) -> Result<Self, ImageHashError> {
76        if bits.is_empty() || bits[0].is_empty() {
77            return Err(ImageHashError::EmptyBits);
78        }
79        let w = bits[0].len();
80        for row in &bits {
81            if row.len() != w {
82                return Err(ImageHashError::NonRectangular { expected: w, got: row.len() });
83            }
84        }
85        Ok(Self { bits })
86    }
87
88    pub(crate) fn from_bits_unchecked(bits: Vec<Vec<bool>>) -> Self {
89        Self { bits }
90    }
91
92    pub fn to_hex(&self) -> String {
93        internal::bitpack::pack(&self.bits)
94    }
95
96    pub fn subtract(&self, other: &Hash) -> Result<usize, ImageHashError> {
97        let h1 = self.bits.len();
98        let w1 = self.bits[0].len();
99        let h2 = other.bits.len();
100        let w2 = other.bits[0].len();
101        if h1 != h2 || w1 != w2 {
102            return Err(ImageHashError::ShapeMismatch { h1, w1, h2, w2 });
103        }
104        let mut diff = 0;
105        for y in 0..h1 {
106            for x in 0..w1 {
107                if self.bits[y][x] != other.bits[y][x] {
108                    diff += 1;
109                }
110            }
111        }
112        Ok(diff)
113    }
114
115    pub fn bit_count(&self) -> usize {
116        if self.bits.is_empty() {
117            return 0;
118        }
119        self.bits.len() * self.bits[0].len()
120    }
121}
122
123impl fmt::Display for Hash {
124    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
125        f.write_str(&self.to_hex())
126    }
127}