Skip to content

release: v1.10.0 - modular refactoring, WebP support, and CI/CD improvements#9

Merged
gudoshnikovn merged 26 commits into
mainfrom
release/v1.10.0
Mar 30, 2026
Merged

release: v1.10.0 - modular refactoring, WebP support, and CI/CD improvements#9
gudoshnikovn merged 26 commits into
mainfrom
release/v1.10.0

Conversation

@gudoshnikovn

@gudoshnikovn gudoshnikovn commented Mar 24, 2026

Copy link
Copy Markdown
Owner

Features & Core Enhancements

  • Native WebP Support: Integrated high-performance direct WebP decoding.
  • Improved Error Handling: Added clear, human-readable error descriptions.
  • Memory & Math Fixes: Optimized the internal allocator to prevent memory growth and fixed critical calculation bugs in hashing algorithms.

Architecture & Infrastructure

  • Modular Codebase: Reorganized the source code into focused, logical modules and cleaned up internal headers for better maintainability.
  • Testing Overhaul: Completely restructured the test suite, separated test data, and added comprehensive unit tests, achieving greater than 95% code coverage.
  • CI/CD Benchmarks: Added automated GitHub workflows to track performance regressions on new PRs.

Miscellaneous

  • Documentation: Significant updates to the README and overall project documentation.

- Add libwebp as a vendor submodule and update build system (CMake/Makefile)
- Implement zero-copy WebP decoding in loader and core API
- Add WebP support to test suite and benchmarks
- Improve WebP loading performance by ~27x compared to external dwebp
- Update README and THIRD-PARTY-NOTICES with licensing info
… algorithms

- aHash/dHash/pHash: Remove incorrect Laplacian filter to restore standard algorithmic compliance and fix grayscale caching loop.
- wHash: Fix downscaling matrix logic and cascaded Haar DWT in the fast variant to extract the correct LL-band (low frequency).
- ColorHash & ColorMoments: Correct bitwise string packing to generate true 64-bit entropy and prevent out-of-bounds reads on grayscale images.
- Radial: Resolve internal scratchpad memory overlap on Gaussian blur and handle valid black pixels correctly in Radon projections.
- mHash: Enforce 18x18 input block scaling (step=2) to extract exactly 64-bit entropy instead of producing truncated 49-bit hashes.
- BMH: Fix unsafe integer cast causing max digest size clamping failures on large image blocks.
- Core: Implement correct grayscale cache invalidation on color weight changes.
Full refactoring of the C engine for better maintainability and safety:
- Organized source tree: created src/image/ and src/loaders/ subdirectories.
- Unified image loading with a backend-registry dispatcher (loader.c).
- Decentralized image.c into specialized modules (resize, color, filters).
- Implemented a linear arena allocator in ph_context_t for scratchpad memory.
- Grouped context fields into 'image', 'config', and 'arena' sub-structures.
- All changes verified with the full test suite (all tests passed).
- Extracted math helpers for mHash, pHash, wHash, Radial, and Color hashes.
- Added unit tests for new helpers and expanded e2e coverage.
- Verified memory safety with AddressSanitizer.
@gudoshnikovn gudoshnikovn self-assigned this Mar 24, 2026
@github-actions

github-actions Bot commented Mar 24, 2026

Copy link
Copy Markdown

Performance Benchmark


--- Loading Performance (/home/runner/work/libphash/libphash/tests/data/photo.jpeg, 50 iterations) ---
Mode: Grayscale (Fast)
Total time: 0.0376s, Avg: 0.7528ms/load

--- Loading Performance (/home/runner/work/libphash/libphash/tests/data/photo.jpeg, 50 iterations) ---
Mode: RGB (Full)
Total time: 0.0555s, Avg: 1.1090ms/load

--- Hashing Performance (50 iterations) ---
Algorithm       | Total Time   | Avg (ms/op) 
----------------|--------------|--------------
aHash           |     0.0022s |     0.0439ms
dHash           |     0.0022s |     0.0449ms
pHash           |     0.0030s |     0.0592ms
wHash (Fast)    |     0.0017s |     0.0342ms
wHash (Full)    |     0.0304s |     0.6082ms
mHash           |     0.0018s |     0.0357ms
ColorHash       |     0.0554s |     1.1089ms
Radial          |     0.0017s |     0.3332ms (1/10 iter)

- Added AVX2 and SSE4.1 SIMD paths for pHash (DCT) and Hamming distance.
- Implemented 32-byte aligned memory allocation in Arena for SIMD efficiency.
- Added `madvise(MADV_SEQUENTIAL)` to optimize `mmap` image loading on Linux.
- Updated CMake with LTO support, AVX2 detection, and `-ffast-math` for hashes.
- Removed global `-mavx2` compiler flag that caused auto-vectorization overhead in simple hash algorithms on x86_64 processors.
- Disabled LTO (Link Time Optimization) by default for the static library to prevent inline heuristic regressions.
- Reverted manual AVX2 intrinsics in `phash.c`.
- Restricted explicitly `-mavx2` instruction set compilation to `common.c` for Hamming distance optimizations only.
- Converted Radial Hash interpolation to `float` (6% faster).
- Added separate wHash (Fast/Full) tests to benchmark.
- Updated internal headers and unit tests for float compatibility.
@gudoshnikovn gudoshnikovn merged commit ae3a9cf into main Mar 30, 2026
2 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant