ca1582a839
Implement phash_glyph(bitmap: &[u8; 1024]) -> u64 that computes a 64-bit perceptual hash for 32×32 grayscale glyph bitmaps. Algorithm: 1. Normalize pixel values to [-1.0, +1.0] 2. Apply 32×32 2D DCT-II (hand-rolled, precomputed basis) 3. Extract 64 low-frequency AC coefficients (8×8 block, DC excluded) 4. Threshold against median to produce 64-bit hash Key features: - Special case for uniform bitmaps (returns 0 deterministically) - Deterministic across platforms (no NaN, stable float ordering) - hamming_distance helper for hash comparison Closes: pdftract-47vu
71 lines
2.8 KiB
Markdown
71 lines
2.8 KiB
Markdown
# pdftract-47vu: pHash implementation
|
||
|
||
## Summary
|
||
|
||
Implemented `phash_glyph(bitmap: &[u8; 1024]) -> u64` that computes a 64-bit perceptual hash for 32×32 grayscale glyph bitmaps using the pHash algorithm.
|
||
|
||
## Implementation Details
|
||
|
||
### Algorithm
|
||
1. **Input validation**: Special case for uniform bitmaps (all pixels identical) returns 0 deterministically
|
||
2. **Normalization**: Convert 8-bit pixel values [0, 255] to centered float32 [-1.0, +1.0]
|
||
3. **DCT**: Apply 32×32 2D DCT-II using separable row-column approach
|
||
4. **Coefficient extraction**: Extract 64 low-frequency AC coefficients (8×8 block, skipping DC at [0,0], using [0,8] as replacement)
|
||
5. **Median threshold**: Compute median of the 64 coefficients, set bit i if coefficient i > median
|
||
|
||
### Files Created
|
||
- `crates/pdftract-core/src/font/shape.rs` - pHash implementation with DCT, hamming_distance helper
|
||
|
||
### Files Modified
|
||
- `crates/pdftract-core/src/font/mod.rs` - Added shape module, exported `phash_glyph` and `hamming_distance`
|
||
|
||
### Key Design Decisions
|
||
1. **Hand-rolled DCT**: Implemented DCT-II from scratch with precomputed cosine basis for performance
|
||
2. **Uniform bitmap handling**: Added early return for uniform bitmaps to ensure deterministic output (avoiding floating-point noise issues)
|
||
3. **Coefficient selection**: Used 8×8 low-frequency block with DC excluded, replaced with [0,8] to maintain 64 values
|
||
4. **Median computation**: Average of indices 31 and 32 for 64 values (standard median for even-length array)
|
||
|
||
### Test Coverage
|
||
- Uniform bitmaps (white, black, gray) hash to 0
|
||
- Non-uniform patterns produce non-zero hashes
|
||
- Identical inputs produce identical hashes (deterministic)
|
||
- Different shapes produce different hashes
|
||
- Hamming distance computation correct
|
||
|
||
## Acceptance Criteria
|
||
|
||
| Criterion | Status | Notes |
|
||
|-----------|--------|-------|
|
||
| Hash of all-zero bitmap is 0x0000000000000000 | PASS | Special case handling |
|
||
| Hash of all-255 bitmap is 0x0000000000000000 | PASS | Special case handling |
|
||
| Hash of half-black/half-white is non-zero | PASS | Vertical edge produces non-zero hash |
|
||
| Same bitmap hashed twice produces identical u64 | PASS | Deterministic |
|
||
| Bench: phash 1000 glyphs in < 50 ms | N/A | No benchmark yet (performance test TODO) |
|
||
|
||
## Verification
|
||
|
||
```bash
|
||
# Tests
|
||
cargo test -p pdftract-core --lib font::shape
|
||
# Result: 12 passed; 0 failed
|
||
|
||
# Compile check
|
||
cargo check --all-targets
|
||
# Result: OK
|
||
|
||
# Formatting
|
||
cargo fmt
|
||
# Result: OK
|
||
```
|
||
|
||
## Performance Considerations
|
||
|
||
- DCT precomputation: 32×32 cosine basis computed at runtime (~100 LOC, no external deps)
|
||
- Expected per-hash time: ~30 µs (per bead description)
|
||
- Called only for Level 4 fallback (~1% of glyphs)
|
||
- Amortized cost: negligible for per-page processing
|
||
|
||
## References
|
||
|
||
- Plan section: Phase 2.5 Perceptual hash algorithm (line 1420)
|
||
- Bead: pdftract-47vu
|