fix: critical bug fixes and improvements from code review

- Fix DCT-II implementation with proper twiddle factors
- Fix duplicate TLS contexts (single shared context)
- Fix unsafe set_len with safe resize
- Fix EXIF orientation (read from raw bytes before decode)
- Fix similarity consistency (block-level in MultiHashFingerprint)
- Fix serde feature gating (properly optional)
- Add model_id support to Embedding
- Add kamadak-exif dependency
- Update CHANGELOG, README, USAGE docs

Author: bravo1goingdark

CHANGELOG.md

@@ -21,14 +21,24 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   - Fixed buffer reclamation order bug in image preprocessing
   - Fixed `apply_orientation()` unnecessarily cloning entire image - now uses `Cow::Borrowed` to avoid expensive clone when no EXIF orientation transform is needed
   - Fixed SIMD CPU extension detection being performed on every `Preprocessor::new()` call - now cached globally using `OnceLock` for better performance
+  - **Fixed DCT-II implementation** in PHash: Added proper twiddle factors for mathematically correct DCT-II computation
+  - **Fixed duplicate thread-local contexts**: Both `fingerprint()` and `fingerprint_with()` now share a single module-level TLS slot instead of creating separate ones
+  - **Fixed unsafe memory operations**: Replaced `unsafe { set_len() }` with safe `resize()` in preprocessing buffers
+  - **Fixed EXIF orientation handling**: Now reads EXIF orientation from raw bytes before decoding and applies transformations (rotate/flip) to decoded image
+  - **Fixed similarity algorithm consistency**: `MultiHashFingerprint::compare()` now includes block-level similarity (60% weight) for consistent crop resistance with single-algorithm mode
+  - **Fixed error handling in DCT**: Changed `unwrap()` to proper `Result` propagation in `dct2_32()`
 
 - **API improvements**:
   - Made `hash_similarity()` and `hamming_distance()` public utilities
   - Added fast-path for exact match in similarity comparison
   - Added compile-time assertions verifying `ImgFprintError` implements `Send + Sync` for safe use in async and multi-threaded contexts
+  - **Added model ID support to embeddings**: `Embedding::new_with_model()` allows tagging embeddings with model identifiers to prevent comparing incompatible models
+  - **Fixed serde feature gating**: `serde` crate is now properly optional (not compiled unless feature enabled)
 
 - **Code quality**:
   - Fixed clippy warnings (needless_range_loop, manual_clamp)
+  - Added `kamadak-exif` dependency for EXIF orientation parsing
+  - Updated bincode dev-dependency comment documenting v2 API changes
 
 ## [0.3.1] - 2025-03-16
 

Cargo.lock

@@ -13,20 +13,21 @@ readme = "README.md"
 
 [dependencies]
 image = { version = "0.25", default-features = false, features = ["png", "jpeg", "gif", "webp", "bmp"] }
+exif = { package = "kamadak-exif", version = "0.6" }
 fast_image_resize = { version = "6.0", features = ["image"] }
 blake3 = "1.8"
 realfft = "3.4"
 rustfft = "6.2"
 thiserror = "2.0"
-serde = { version = "1.0", features = ["derive"] }
+serde = { version = "1.0", features = ["derive"], optional = true }
 rayon = { version = "1.10", optional = true }
 tract-onnx = { version = "0.22.1", optional = true }
 tracing = { version = "0.1", optional = true }
 subtle = "2.6"
 
 [features]
 default = ["serde", "parallel"]
-serde = []
+serde = ["dep:serde"]
 parallel = ["dep:rayon"]
 local-embedding = ["dep:tract-onnx"]
 local-embedding-model = ["local-embedding"]
@@ -36,7 +37,7 @@ tracing = ["dep:tracing"]
 criterion = { version = "0.8.2", features = ["html_reports"] }
 image = { version = "0.25", default-features = false, features = ["png"] }
 serde_json = "1.0"
-bincode = "1.3.3"
+bincode = "1.3.3"  # v2 has breaking API changes; pin until upgrade
 proptest = "1.5"
 
 [[example]]

Cargo.toml

@@ -34,7 +34,9 @@ Perfect for:
 - **Deterministic Output** - Same input always produces same fingerprint
 - **BLAKE3 Exact Hash** - Byte-identical detection (6-8x faster than SHA256)
 - **Block-Level Hashing** - 4x4 grid for crop resistance
+- **EXIF Orientation** - Automatically corrects JPEG orientation from camera metadata
 - **Semantic Embeddings** - CLIP-style vector representations via external providers or local ONNX models
+- **Embedding Model ID** - Tag embeddings with model identifiers to prevent comparing incompatible models
 - **SIMD Acceleration** - AVX2/NEON optimized resizing
 - **Parallel Processing** - Multi-core batch operations
 - **Zero-Copy APIs** - Minimal allocations in hot paths
@@ -148,7 +150,7 @@ ImageFingerprint
 
 ### Algorithm Pipeline
 
-1. **Decode** - Parse any supported format (PNG, JPEG, GIF, WebP, BMP) into RGB
+1. **Decode** - Parse any supported format (PNG, JPEG, GIF, WebP, BMP) into RGB with EXIF orientation correction for JPEG
 2. **Normalize** - Resize to 256x256 using SIMD-accelerated Lanczos3 filter
 3. **Convert** - RGB to Grayscale (luminance)
 4. **Parallel Hash Computation** - All three algorithms computed simultaneously:
@@ -159,13 +161,17 @@ ImageFingerprint
 
 ### Multi-Algorithm Comparison
 
-When using `MultiHashFingerprint`, the similarity score uses weighted combination:
+When using `MultiHashFingerprint`, the similarity score uses weighted combination with block-level similarity:
 
 - **10%** AHash similarity (average hash, fastest, simplest)
 - **60%** PHash similarity (DCT-based, robust to compression)
 - **30%** DHash similarity (gradient-based, good for structural changes)
 
-This provides better accuracy than any single algorithm alone.
+Within each algorithm, similarity is computed as:
+- **40%** global hash similarity (overall structure)
+- **60%** block-level similarity (crop resistance via 4x4 grid)
+
+This provides superior crop resistance compared to global-only comparison.
 
 ## Performance
 

README.md

@@ -567,13 +567,19 @@ let fp = multi.get(HashAlgorithm::PHash);
 pub fn compare(&self, other: &MultiHashFingerprint) -> Similarity
 ```
 
-Compares two multi-hash fingerprints using weighted combination.
+Compares two multi-hash fingerprints using weighted combination with block-level similarity for crop resistance.
 
-**Weights:**
+**Algorithm Weights:**
 - **10%** AHash similarity (average hash, fastest)
-- **60%** PHash similarity (DCT-based, robust to compression)
+- **60%** PHash similarity (DCT-based, robust to compression)  
 - **30%** DHash similarity (gradient-based, good for structural changes)
 
+**Per-Algorithm Composition:**
+- **40%** global hash similarity (overall structure)
+- **60%** block-level similarity (4x4 grid, crop resistance)
+
+This provides superior crop resistance compared to global-only comparison.
+
 **Example:**
 ```rust
 let multi1 = ImageFingerprinter::fingerprint(&img1)?;
@@ -774,6 +780,29 @@ println!("Semantic similarity: {:.4}", similarity);
 
 **Note:** The library does not include built-in embedding providers. You must implement `EmbeddingProvider` for your use case (OpenAI CLIP, HuggingFace, local models, etc.).
 
+#### Model ID Support
+
+To prevent accidental comparison of embeddings from different models (e.g., comparing 512-dim CLIP with 768-dim CLIP), you can tag embeddings with a model identifier:
+
+```rust
+use imgfprint::Embedding;
+
+// Create embedding with model ID
+let embedding = Embedding::new_with_model(
+    vec![0.1, 0.2, 0.3, /* ... 512 dimensions */],
+    Some("clip-vit-base-patch32".to_string())
+)?;
+
+// The model ID is validated during similarity comparison
+let sim = imgfprint::semantic_similarity(&emb1, &emb2)?;
+// Will error if model IDs differ (prevents meaningless comparisons)
+```
+
+**Benefits:**
+- Prevents comparing incompatible embeddings
+- Explicit model tracking for audit trails
+- Backward compatible (model_id is optional)
+
 #### Local ONNX Models
 
 With the `local-embedding` feature:

USAGE.md

@@ -185,11 +185,15 @@ impl MultiHashFingerprint {
 
     /// Compares two multi-hash fingerprints using weighted combination.
     ///
-    /// Uses weighted combination:
+    /// Uses weighted combination of algorithm similarities:
     /// - 10% AHash similarity (average hash, fastest)
     /// - 60% PHash similarity (DCT-based, robust to compression)
     /// - 30% DHash similarity (gradient-based, good for structural changes)
     ///
+    /// Each algorithm's similarity includes both global and block-level hashing
+    /// for improved crop resistance. Block hashes are weighted at 60% and global
+    /// hashes at 40% within each algorithm.
+    ///
     /// Returns a Similarity struct with combined score and component distances.
     ///
     /// Uses constant-time comparison to prevent timing attacks on exact match.
@@ -198,6 +202,7 @@ impl MultiHashFingerprint {
     /// * `other` - The fingerprint to compare against
     #[must_use]
     pub fn compare(&self, other: &MultiHashFingerprint) -> Similarity {
+        use crate::core::similarity::{compute_similarity, hamming_distance};
         use subtle::ConstantTimeEq;
 
         let exact_match = self.exact.ct_eq(&other.exact).into();
@@ -211,18 +216,19 @@ impl MultiHashFingerprint {
             };
         }
 
-        let ahash_dist = self.ahash.distance(&other.ahash);
-        let phash_dist = self.phash.distance(&other.phash);
-        let dhash_dist = self.dhash.distance(&other.dhash);
-
-        // Use shared hash_similarity function for consistency
-        let ahash_sim = hash_similarity(ahash_dist);
-        let phash_sim = hash_similarity(phash_dist);
-        let dhash_sim = hash_similarity(dhash_dist);
+        // Compute per-algorithm similarities including block-level comparison
+        let ahash_sim = compute_similarity(&self.ahash, &other.ahash).score;
+        let phash_sim = compute_similarity(&self.phash, &other.phash).score;
+        let dhash_sim = compute_similarity(&self.dhash, &other.dhash).score;
 
         let weighted_score =
             ahash_sim * AHASH_WEIGHT + phash_sim * PHASH_WEIGHT + dhash_sim * DHASH_WEIGHT;
 
+        // Use global hash distances for perceptual_distance (backward compatibility)
+        let ahash_dist = hamming_distance(self.ahash.global_hash, other.ahash.global_hash);
+        let phash_dist = hamming_distance(self.phash.global_hash, other.phash.global_hash);
+        let dhash_dist = hamming_distance(self.dhash.global_hash, other.dhash.global_hash);
+
         let avg_distance = ((ahash_dist as f32 * AHASH_WEIGHT)
             + (phash_dist as f32 * PHASH_WEIGHT)
             + (dhash_dist as f32 * DHASH_WEIGHT)) as u32;

src/core/fingerprint.rs

@@ -10,6 +10,11 @@ use crate::imgproc::preprocess::{extract_blocks, extract_global_region, Preproce
 use blake3::Hasher;
 use std::cell::RefCell;
 
+// Module-level shared thread-local context to avoid duplication
+thread_local! {
+    static SHARED_CTX: RefCell<FingerprinterContext> = RefCell::new(FingerprinterContext::new());
+}
+
 #[cfg(feature = "tracing")]
 use tracing::{debug, instrument};
 
@@ -317,11 +322,7 @@ impl ImageFingerprinter {
         #[cfg(feature = "tracing")]
         let start = std::time::Instant::now();
 
-        thread_local! {
-            static CTX: RefCell<FingerprinterContext> = RefCell::new(FingerprinterContext::new());
-        }
-
-        let result = CTX.with(|ctx| ctx.borrow_mut().fingerprint(image_bytes));
+        let result = SHARED_CTX.with(|ctx| ctx.borrow_mut().fingerprint(image_bytes));
 
         #[cfg(feature = "tracing")]
         debug!(
@@ -348,11 +349,8 @@ impl ImageFingerprinter {
         #[cfg(feature = "tracing")]
         let start = std::time::Instant::now();
 
-        thread_local! {
-            static CTX: RefCell<FingerprinterContext> = RefCell::new(FingerprinterContext::new());
-        }
-
-        let result = CTX.with(|ctx| ctx.borrow_mut().fingerprint_with(image_bytes, algorithm));
+        let result =
+            SHARED_CTX.with(|ctx| ctx.borrow_mut().fingerprint_with(image_bytes, algorithm));
 
         #[cfg(feature = "tracing")]
         debug!(

src/core/fingerprinter.rs

@@ -35,6 +35,9 @@ pub fn hash_similarity(distance: u32) -> f32 {
 ///
 /// Uses a pre-computed population count table for faster computation
 /// than the built-in count_ones() on 64-bit values.
+///
+/// Note: On modern x86-64 CPUs with POPCNT instruction, `count_ones()`
+/// may be faster. Benchmark both approaches for your specific use case.
 #[inline(always)]
 pub fn hamming_distance(a: u64, b: u64) -> u32 {
     let xor = a ^ b;
@@ -133,7 +136,7 @@ pub fn compute_similarity(a: &ImageFingerprint, b: &ImageFingerprint) -> Similar
 /// For example, if image A is cropped to show only the top-left quadrant,
 /// blocks in the bottom-right of A won't match B, but the top-left blocks
 /// will still contribute to the similarity score.
-fn compute_block_similarity(a: &[u64; 16], b: &[u64; 16]) -> f32 {
+pub fn compute_block_similarity(a: &[u64; 16], b: &[u64; 16]) -> f32 {
     let mut total_similarity = 0.0f32;
     let mut valid_comparisons = 0u32;