python-libphash 1.2.0__tar.gz → 1.3.0__tar.gz

{python_libphash-1.2.0 → python_libphash-1.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-libphash
-Version: 1.2.0
+Version: 1.3.0
 Summary: High-performance perceptual hashing library (CFFI bindings)
 Author-email: gudoshnikovn <gudoshnikov-na@yandex.ru>
 License-Expression: MIT
@@ -16,11 +16,16 @@ Provides-Extra: dev
 Requires-Dist: pytest; extra == "dev"
 Requires-Dist: mypy; extra == "dev"
 Requires-Dist: ruff; extra == "dev"
+Provides-Extra: benchmark
+Requires-Dist: imagehash; extra == "benchmark"
+Requires-Dist: Pillow; extra == "benchmark"
+Requires-Dist: pandas; extra == "benchmark"
+Requires-Dist: tabulate; extra == "benchmark"
 Dynamic: license-file
 
 # python-libphash
 
-High-performance Python bindings for [libphash](https://github.com/gudoshnikovn/libphash) v1.6.1, a C library for perceptual image hashing.
+High-performance Python bindings for [libphash](https://github.com/gudoshnikovn/libphash) v1.9.0, a C library for perceptual image hashing.
 
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)
@@ -37,10 +42,11 @@ High-performance Python bindings for [libphash](https://github.com/gudoshnikovn/
     *   `phash`: Perceptual Hash (DCT based)
     *   `whash`: Wavelet Hash
     *   `mhash`: Median Hash
+    *   `color_hash`: Packed 42-bit HSV-based color hash (compatible with `imagehash.colorhash`).
 *   **Digest Hashes (Multi-byte):**
-    *   `bmh`: Block Mean Hash
-    *   `color_hash`: Color Moment Hash
-    *   `radial_hash`: Radial Variance Hash
+    *   `bmh`: Block Mean Hash (256-bit digest).
+    *   `color_moments_hash`: Statistical color distribution digest (mean, variance, skewness, kurtosis).
+    *   `radial_hash`: Rotation-invariant Fourier-Mellin transform digest.
 
 ## Installation
 
@@ -91,9 +97,12 @@ distance = compare_images("image1.jpg", "image2.jpg", method=HashMethod.PHASH)
 print(f"Hamming Distance: {distance}")
 ```
 
-### Advanced Configuration (New in v1.6.1)
+### Advanced Configuration (New in v1.8.0)
 Fine-tune hashing algorithms for specific use cases. Note that hashes generated with different parameters are **not comparable**.
 
+*   **Ultra-Fast Image Decoding (v1.9.0)**: `libphash` now bundles high-performance decoders for JPEG and PNG. It uses `libjpeg-turbo` (TurboJPEG API) and `spng` or `libpng` with NEON/SSE SIMD acceleration. Image data is loaded via `mmap()` for zero-copy I/O between the file system and the decoder.
+    *   **Fallback**: Automatically falls back to `stb_image` if bundled decoders are disabled or for other formats.
+
 ```python
 with ImageContext("photo.jpg") as ctx:
     # pHash (DCT) resolution
@@ -105,6 +114,9 @@ with ImageContext("photo.jpg") as ctx:
     # Block-based hashes (BMH) grid resolution
     ctx.set_block_params(block_size=16)
     
+    # Wavelet Hash (wHash) Mode: "fast" (default) or "full"
+    ctx.set_whash_mode("full")
+    
     # Custom Grayscale weights (R, G, B)
     ctx.set_gray_weights(38, 75, 15)
     
@@ -141,6 +153,7 @@ The main class for loading images and computing hashes.
 *   `set_phash_params(dct_size, reduction_size)`: Configure pHash DCT resolution.
 *   `set_radial_params(projections, samples)`: Configure Radial Hash precision.
 *   `set_block_params(block_size)`: Configure BMH/mHash grid resolution.
+*   `set_whash_mode(mode="fast")`: Use "fast" (median) or "full" (ImageHash accurate 2D DWT).
 *   **Properties**: `ahash`, `dhash`, `phash`, `whash`, `mhash` (returns `int`).
 *   **Properties**: `bmh`, `color_hash`, `radial_hash` (returns `Digest`).
 
@@ -152,11 +165,16 @@ The main class for loading images and computing hashes.
 
 ### Utilities
 *   `hamming_distance(h1: int, h2: int)`: Returns the number of differing bits between two 64-bit integers.
+*   `ph_can_use_libjpeg()`: Returns `True` if `libjpeg-turbo` is enabled.
+*   `ph_can_use_libpng()`: Returns `True` if `libpng` or `spng` is enabled.
 *   `get_hash(path, method)`: Quick way to get a hash without manual context management.
 *   `compare_images(path1, path2, method)`: Returns the Hamming distance between two image files.
 
 ## Performance
-Since the core logic is implemented in C and uses `stb_image` for decoding, `libphash` is significantly faster than pure-Python alternatives. It also uses CFFI's "out-of-line" mode for minimal overhead.
+Since the core logic is implemented in C and uses SIMD-accelerated decoders, `libphash` is significantly faster than pure-Python alternatives.
+*   **JPEG Decoding**: ~2.0x faster than Pillow
+*   **PNG Decoding**: ~1.3x faster than Pillow.
+*   **Zero-Copy**: Uses `mmap()` to avoid kernel-user space copies.
 
 ## License
 This project is licensed under the MIT License - see the LICENSE file for details.

python_libphash-1.2.0/src/python_libphash.egg-info/PKG-INFO → python_libphash-1.3.0/README.md

@@ -1,26 +1,6 @@
-Metadata-Version: 2.4
-Name: python-libphash
-Version: 1.2.0
-Summary: High-performance perceptual hashing library (CFFI bindings)
-Author-email: gudoshnikovn <gudoshnikov-na@yandex.ru>
-License-Expression: MIT
-Project-URL: Homepage, https://github.com/gudoshnikovn/python-libphash
-Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: C
-Classifier: Topic :: Multimedia :: Graphics
-Requires-Python: >=3.8
-Description-Content-Type: text/markdown
-License-File: LICENSE
-Requires-Dist: cffi>=1.15.0
-Provides-Extra: dev
-Requires-Dist: pytest; extra == "dev"
-Requires-Dist: mypy; extra == "dev"
-Requires-Dist: ruff; extra == "dev"
-Dynamic: license-file
-
 # python-libphash
 
-High-performance Python bindings for [libphash](https://github.com/gudoshnikovn/libphash) v1.6.1, a C library for perceptual image hashing.
+High-performance Python bindings for [libphash](https://github.com/gudoshnikovn/libphash) v1.9.0, a C library for perceptual image hashing.
 
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)
@@ -37,10 +17,11 @@ High-performance Python bindings for [libphash](https://github.com/gudoshnikovn/
     *   `phash`: Perceptual Hash (DCT based)
     *   `whash`: Wavelet Hash
     *   `mhash`: Median Hash
+    *   `color_hash`: Packed 42-bit HSV-based color hash (compatible with `imagehash.colorhash`).
 *   **Digest Hashes (Multi-byte):**
-    *   `bmh`: Block Mean Hash
-    *   `color_hash`: Color Moment Hash
-    *   `radial_hash`: Radial Variance Hash
+    *   `bmh`: Block Mean Hash (256-bit digest).
+    *   `color_moments_hash`: Statistical color distribution digest (mean, variance, skewness, kurtosis).
+    *   `radial_hash`: Rotation-invariant Fourier-Mellin transform digest.
 
 ## Installation
 
@@ -91,9 +72,12 @@ distance = compare_images("image1.jpg", "image2.jpg", method=HashMethod.PHASH)
 print(f"Hamming Distance: {distance}")
 ```
 
-### Advanced Configuration (New in v1.6.1)
+### Advanced Configuration (New in v1.8.0)
 Fine-tune hashing algorithms for specific use cases. Note that hashes generated with different parameters are **not comparable**.
 
+*   **Ultra-Fast Image Decoding (v1.9.0)**: `libphash` now bundles high-performance decoders for JPEG and PNG. It uses `libjpeg-turbo` (TurboJPEG API) and `spng` or `libpng` with NEON/SSE SIMD acceleration. Image data is loaded via `mmap()` for zero-copy I/O between the file system and the decoder.
+    *   **Fallback**: Automatically falls back to `stb_image` if bundled decoders are disabled or for other formats.
+
 ```python
 with ImageContext("photo.jpg") as ctx:
     # pHash (DCT) resolution
@@ -105,6 +89,9 @@ with ImageContext("photo.jpg") as ctx:
     # Block-based hashes (BMH) grid resolution
     ctx.set_block_params(block_size=16)
     
+    # Wavelet Hash (wHash) Mode: "fast" (default) or "full"
+    ctx.set_whash_mode("full")
+    
     # Custom Grayscale weights (R, G, B)
     ctx.set_gray_weights(38, 75, 15)
     
@@ -141,6 +128,7 @@ The main class for loading images and computing hashes.
 *   `set_phash_params(dct_size, reduction_size)`: Configure pHash DCT resolution.
 *   `set_radial_params(projections, samples)`: Configure Radial Hash precision.
 *   `set_block_params(block_size)`: Configure BMH/mHash grid resolution.
+*   `set_whash_mode(mode="fast")`: Use "fast" (median) or "full" (ImageHash accurate 2D DWT).
 *   **Properties**: `ahash`, `dhash`, `phash`, `whash`, `mhash` (returns `int`).
 *   **Properties**: `bmh`, `color_hash`, `radial_hash` (returns `Digest`).
 
@@ -152,11 +140,16 @@ The main class for loading images and computing hashes.
 
 ### Utilities
 *   `hamming_distance(h1: int, h2: int)`: Returns the number of differing bits between two 64-bit integers.
+*   `ph_can_use_libjpeg()`: Returns `True` if `libjpeg-turbo` is enabled.
+*   `ph_can_use_libpng()`: Returns `True` if `libpng` or `spng` is enabled.
 *   `get_hash(path, method)`: Quick way to get a hash without manual context management.
 *   `compare_images(path1, path2, method)`: Returns the Hamming distance between two image files.
 
 ## Performance
-Since the core logic is implemented in C and uses `stb_image` for decoding, `libphash` is significantly faster than pure-Python alternatives. It also uses CFFI's "out-of-line" mode for minimal overhead.
+Since the core logic is implemented in C and uses SIMD-accelerated decoders, `libphash` is significantly faster than pure-Python alternatives.
+*   **JPEG Decoding**: ~2.0x faster than Pillow
+*   **PNG Decoding**: ~1.3x faster than Pillow.
+*   **Zero-Copy**: Uses `mmap()` to avoid kernel-user space copies.
 
 ## License
 This project is licensed under the MIT License - see the LICENSE file for details.

python_libphash-1.3.0/native/libphash/.gitmodules

@@ -0,0 +1,9 @@
+[submodule "vendor/libjpeg-turbo"]
+	path = vendor/libjpeg-turbo
+	url = https://github.com/libjpeg-turbo/libjpeg-turbo.git
+[submodule "vendor/libpng"]
+	path = vendor/libpng
+	url = https://github.com/pnggroup/libpng.git
+[submodule "vendor/spng"]
+	path = vendor/spng
+	url = https://github.com/randy408/libspng.git

python_libphash-1.3.0/native/libphash/CMakeLists.txt

@@ -0,0 +1,100 @@
+cmake_minimum_required(VERSION 3.10)
+project(libphash VERSION 1.9.0 LANGUAGES C)
+
+# --- Options ---
+option(PHASH_BUILD_TESTS "Build tests" ON)
+option(PHASH_BUILD_SHARED "Build shared library" OFF)
+option(PHASH_USE_TURBOJPEG "Use bundled libjpeg-turbo for fast JPEG decoding" ON)
+option(PHASH_USE_LIBPNG "Use bundled libpng for fast PNG decoding" ON)
+
+# --- Compiler Flags ---
+if(MSVC)
+    add_compile_options(/W3 /O2)
+else()
+    add_compile_options(-Wall -Wextra -O3 -fPIC)
+    # Architecture specific optimizations
+    if(CMAKE_SYSTEM_PROCESSOR MATCHES "x86_64|amd64")
+        add_compile_options(-msse4.2)
+    elseif(CMAKE_SYSTEM_PROCESSOR MATCHES "aarch64|arm64")
+        add_compile_options(-march=armv8-a+simd)
+    endif()
+endif()
+
+# --- Library ---
+file(GLOB_RECURSE SOURCES "src/*.c")
+
+if(PHASH_BUILD_SHARED)
+    add_library(phash SHARED ${SOURCES})
+    target_compile_definitions(phash PRIVATE LIBPHASH_EXPORTS)
+else()
+    add_library(phash STATIC ${SOURCES})
+endif()
+
+target_include_directories(phash PUBLIC 
+    $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/include>
+    $<INSTALL_INTERFACE:include>
+)
+
+target_link_libraries(phash PRIVATE m)
+
+if(UNIX AND NOT APPLE)
+    target_link_libraries(phash PRIVATE dl)
+endif()
+
+# --- Bundled libjpeg-turbo (TurboJPEG API) ---
+if(PHASH_USE_TURBOJPEG)
+    target_compile_definitions(phash PRIVATE PH_USE_TURBOJPEG)
+    # libjpeg-turbo doesn't like add_subdirectory, so we point to pre-built lib
+    find_library(TURBOJPEG_LIB NAMES turbojpeg turbojpeg-static
+                 PATHS ${CMAKE_CURRENT_SOURCE_DIR}/vendor/libjpeg-turbo/build)
+    if(TURBOJPEG_LIB)
+        target_link_libraries(phash PRIVATE ${TURBOJPEG_LIB})
+    else()
+        message(WARNING "libturbojpeg.a not found in vendor/libjpeg-turbo/build. Please build it first.")
+    endif()
+    target_include_directories(phash PRIVATE 
+        ${CMAKE_CURRENT_SOURCE_DIR}/vendor/libjpeg-turbo/src
+        ${CMAKE_CURRENT_SOURCE_DIR}/vendor/libjpeg-turbo/build
+    )
+endif()
+
+# --- Bundled libpng ---
+if(PHASH_USE_LIBPNG)
+    target_compile_definitions(phash PRIVATE PH_USE_LIBPNG)
+    set(PNG_SHARED OFF CACHE BOOL "" FORCE)
+    set(PNG_STATIC ON CACHE BOOL "" FORCE)
+    set(PNG_TESTS OFF CACHE BOOL "" FORCE)
+    set(PNG_HARDWARE_OPTIMIZATIONS ON CACHE BOOL "" FORCE)
+    # libpng works mostly OK with add_subdirectory
+    add_subdirectory(vendor/libpng EXCLUDE_FROM_ALL)
+    target_link_libraries(phash PRIVATE png_static z)
+    target_include_directories(phash PRIVATE 
+        ${CMAKE_CURRENT_SOURCE_DIR}/vendor/libpng
+        ${CMAKE_CURRENT_BINARY_DIR}/vendor/libpng
+    )
+endif()
+
+# --- Bundled spng ---
+if(PHASH_USE_SPNG)
+    target_compile_definitions(phash PRIVATE PH_USE_SPNG)
+    add_library(spng_static STATIC vendor/spng/spng/spng.c)
+    target_include_directories(spng_static PUBLIC vendor/spng/spng)
+    target_link_libraries(phash PRIVATE spng_static z)
+    target_include_directories(phash PRIVATE vendor/spng/spng)
+endif()
+
+# --- Tests ---
+if(PHASH_BUILD_TESTS)
+    enable_testing()
+    file(GLOB TEST_SOURCES "tests/test_*.c")
+    foreach(test_src ${TEST_SOURCES})
+        get_filename_component(test_name ${test_src} NAME_WE)
+        add_executable(${test_name} ${test_src})
+        target_link_libraries(${test_name} PRIVATE phash)
+        target_include_directories(${test_name} PRIVATE ${CMAKE_CURRENT_SOURCE_DIR}/src)
+        add_test(NAME ${test_name} COMMAND ${test_name})
+    endforeach()
+
+    # Add benchmark as a smoke test (verifies loading and hashing works)
+    add_test(NAME benchmark_smoke COMMAND test_benchmark hash ${CMAKE_CURRENT_SOURCE_DIR}/tests/photo.jpeg 10)
+endif()

{python_libphash-1.2.0 → python_libphash-1.3.0}/native/libphash/Makefile

@@ -1,7 +1,9 @@
-CC = gcc
+# Compiler and common flags
+CC ?= gcc
 CFLAGS = -I./include -O3 -Wall -Wextra -fPIC
 LDFLAGS = -lm
 
+# Architecture-specific optimizations
 UNAME_M := $(shell uname -m)
 ifeq ($(UNAME_M),x86_64)
     CFLAGS += -msse4.2
@@ -10,6 +12,13 @@ ifeq ($(UNAME_M),arm64)
     CFLAGS += -march=armv8-a+simd
 endif
 
+# OS-specific flags
+UNAME_S := $(shell uname -s)
+ifeq ($(UNAME_S),Linux)
+    LDFLAGS += -ldl
+endif
+
+# Project structure
 LIB_NAME = libphash.a
 OBJ_DIR = obj
 SRC_DIR = src
@@ -17,39 +26,51 @@ HASH_DIR = $(SRC_DIR)/hashes
 TEST_DIR = tests
 INC_DIR = include
 
+# Sources and Objects
 SRCS = $(wildcard $(SRC_DIR)/*.c) $(wildcard $(HASH_DIR)/*.c)
 OBJS = $(SRCS:$(SRC_DIR)/%.c=$(OBJ_DIR)/%.o)
 
+# Tests
 TEST_SRCS = $(wildcard $(TEST_DIR)/test_*.c)
 TEST_BINS = $(TEST_SRCS:$(TEST_DIR)/%.c=%)
 
+# Default target
 all: $(LIB_NAME) $(TEST_BINS)
 
-format:
-	find $(SRC_DIR) $(TEST_DIR) $(INC_DIR) -name "*.c" -o -name "*.h" | xargs clang-format -i
-
+# Diagnostic/Debug build
 debug: CFLAGS = -I./include -g -O0 -fsanitize=address,undefined -Wall -Wextra -fPIC
 debug: clean all
 
+# Reformat code
+format:
+	find $(SRC_DIR) $(TEST_DIR) $(INC_DIR) -name "*.c" -o -name "*.h" | xargs clang-format -i
+
+# Library build
 $(LIB_NAME): $(OBJS)
 	ar rcs $@ $^
 
+# Object file compilation
 $(OBJ_DIR)/%.o: $(SRC_DIR)/%.c
 	@mkdir -p $(dir $@)
 	$(CC) $(CFLAGS) -c $< -o $@
 
+# Test compilation
 test_%: $(TEST_DIR)/test_%.c $(LIB_NAME)
 	$(CC) $(CFLAGS) $< $(LIB_NAME) -o $@ $(LDFLAGS)
 
+# Run all tests
 test: $(TEST_BINS)
-	@for test in $(TEST_BINS); do ./$$test || exit 1; done
+	@for test in $(TEST_BINS); do \
+		echo "Running $$test..."; \
+		./$$test || exit 1; \
+	done
 	@echo "ALL TESTS PASSED"
 
+# Legacy/Standalone benchmark target (internal use)
+benchmark: test_benchmark
+	./test_benchmark hash tests/photo.jpeg 100
+
 clean:
 	rm -rf $(OBJ_DIR) *.a test_* benchmark
 
-benchmark: tests/benchmark.c $(LIB_NAME)
-	$(CC) $(CFLAGS) $< $(LIB_NAME) -o benchmark $(LDFLAGS)
-	./benchmark
-
 .PHONY: all debug test clean format benchmark

python_libphash-1.3.0/native/libphash/README.md

@@ -0,0 +1,93 @@
+# libphash
+
+A high-performance, portable C library for Perceptual Image Hashing. 
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+## Core Features
+
+- **Multiple Algorithms**: `aHash`, `dHash`, `pHash` (DCT), `wHash` (Wavelet), `mHash`, `BMH`, `Radial`, and `ColorHash`.
+- **High-Performance Decoders**: Bundled support for `libjpeg-turbo`, `libpng`, and `spng` with SIMD acceleration (NEON/SSE).
+- **Fast Grayscale Loading**: Native decoders can perform grayscale conversion during decompression, saving time and memory.
+- **Zero-Allocation Processing**: Uses a context-based scratchpad for internal operations.
+- **FFI-Friendly**: Clean C API with opaque pointers, optimized for Python, Rust, or Node.js.
+- **Cross-Platform**: Optimized for ARM64 (Apple Silicon, Raspberry Pi) and x86_64.
+
+---
+
+## 🚀 Performance Modes
+
+libphash can be built in two primary configurations:
+
+| Mode | Decoders | Dependencies | Best For |
+| :--- | :--- | :--- | :--- |
+| **High Performance** (Default) | `libjpeg-turbo`, `libpng`/`spng` | Self-contained (vendor submodules) | Production, massive datasets |
+| **Minimal** | `stb_image` (fallback) | Zero | Embedded, quick scripts |
+
+---
+
+## 🛠 Building
+
+### Recommended (CMake)
+Recommended for managing bundled high-performance decoders.
+```bash
+mkdir build && cd build
+cmake .. -DPHASH_BUILD_TESTS=ON
+make -j$(nproc)
+ctest
+```
+
+### Portable (Makefile)
+Fast and simple for minimal builds.
+```bash
+# Default build (gcc)
+make -j8
+
+# Using specific compiler
+make CC=clang test
+```
+
+---
+
+## 📖 Documentation
+
+For detailed technical information, see the [**Technical Documentation Index**](docs/README.md).
+- [Architecture Overview](docs/architecture.md)
+- [Development Guide & Coding Standards](docs/development.md)
+- [Algorithmic Deep Dive](docs/algorithms.md)
+
+---
+
+## 💻 Usage Example
+
+```c
+#include <libphash.h>
+#include <stdio.h>
+
+int main() {
+    ph_context_t *ctx = NULL;
+    uint64_t hash = 0;
+
+    ph_create(&ctx);
+    
+    // Enable fast grayscale loading (skips RGB conversion)
+    ph_context_set_load_grayscale(ctx, 1);
+    
+    if (ph_load_from_file(ctx, "photo.jpg") == PH_SUCCESS) {
+        ph_compute_phash(ctx, &hash);
+        printf("pHash: %016llx\n", (unsigned long long)hash);
+    }
+
+    ph_free(ctx);
+    return 0;
+}
+```
+
+## Language Bindings
+
+- **Python**: [python-libphash](https://github.com/gudoshnikovn/python-libphash) (`pip install python-libphash`)
+
+## License
+
+This project is licensed under the MIT License.
+Includes `stb_image`, `libjpeg-turbo`, `libpng`, and `spng` in the `vendor/` directory.

python_libphash-1.3.0/native/libphash/docs/README.md

@@ -0,0 +1,28 @@
+# libphash Technical Documentation
+
+Welcome to the internal technical documentation for `libphash`. This directory contains detailed information about the library's design, development process, and algorithmic implementations.
+
+## Navigation
+
+- [**Architecture Overview**](architecture.md)
+  System design, module breakdown, and core data structures.
+- [**Development Guide**](development.md)
+  Build instructions, testing strategies, coding standards, and naming conventions.
+- [**Algorithms Depth**](algorithms.md)
+  Technical details on Hamming distance, pHash, aHash, dHash, and color-aware hashing.
+
+---
+
+## Quick Build Reference
+
+```bash
+# Using standard Makefile
+make -j$(sysctl -n hw.ncpu)
+make test
+
+# Using CMake (recommended for cross-platform)
+mkdir build && cd build
+cmake ..
+make -j8
+ctest
+```

python_libphash-1.3.0/native/libphash/docs/algorithms.md

@@ -0,0 +1,41 @@
+# Algorithmic Deep Dive
+
+This document explains the mathematical foundations and tuning parameters of the hashes implemented in `libphash`.
+
+## 1. aHash (Average Hash)
+- **Concept**: Downscale to 8x8, convert to grayscale, compute average luminance, and set bits based on whether a pixel is above/below the average.
+- **Strength**: High speed, very simple.
+- **Weakness**: Sensitive to brightness/contrast shifts.
+
+## 2. pHash (Perceptual Hash)
+- **Concept**: Downscale to 32x32, perform a Discrete Cosine Transform (DCT), and use the top-left 8x8 coefficients.
+- **Tuning**: 
+    - `phash_dct_size`: Default 32. Larger sizes capture more detail but are slower.
+    - `phash_reduction_size`: Default 8. Determines final hash length (8x8=64 bits).
+- **Strength**: Highly robust against scaling, rotation (< 5°), and moderate compression.
+
+## 3. dHash (Difference Hash)
+- **Concept**: Compares adjacent pixels horizontally or vertically.
+- **Strength**: Faster than pHash, better at detecting duplicates than aHash.
+
+## 4. wHash (Wavelet Hash)
+- **Concept**: Uses Discrete Wavelet Transform (Haar) to analyze image in frequency and spatial domains simultaneously.
+- **Modes**:
+    - `PH_WHASH_FAST`: Single-level decomposition.
+    - `PH_WHASH_FULL`: Multi-level decomposition (more accurate, slower).
+
+## 5. ColorHash
+- **Concept**: Computes statistical moments (mean, variance) across HSV or RGB channels.
+- **Use Case**: When image content is similar but colors differ significantly (e.g., product photos).
+
+---
+
+## Comparison Summary
+
+| Algorithm | Speed | Rotation | Noise | Scaling |
+|---|---|---|---|---|
+| aHash | ⭐⭐⭐⭐⭐ | ❌ | ⭐ | ⭐⭐⭐ |
+| dHash | ⭐⭐⭐⭐ | ❌ | ⭐⭐ | ⭐⭐⭐⭐ |
+| pHash | ⭐⭐⭐ | ⭐⭐⭐ | ⭐⭐⭐⭐ | ⭐⭐⭐⭐⭐ |
+| wHash | ⭐⭐ | ⭐ | ⭐⭐⭐ | ⭐⭐⭐⭐ |
+| Radial | ⭐ | ⭐⭐⭐⭐⭐ | ⭐⭐ | ⭐⭐⭐ |

python_libphash-1.3.0/native/libphash/docs/architecture.md

@@ -0,0 +1,48 @@
+# Architecture Overview
+
+`libphash` is a high-performance C library designed for perceptual image hashing. It prioritizes speed, minimal dependencies, and architectural flexibility.
+
+## Core Components
+
+### 1. Loader Subsystem (`src/loader.c`)
+Handles image decoding from files and memory buffers.
+- **Backends**: Supports `libjpeg-turbo`, `libpng`, `spng`, and fallback to `stb_image`.
+- **Zero-Copy**: Uses `mmap` where possible to minimize memory overhead.
+- **Fast Grayscale**: Decoders are configured to perform grayscale conversion during decompression if requested, avoiding a separate RGB-to-gray pass.
+
+### 2. Image Processing Kernels (`src/image.c`)
+Low-level primitives for image manipulation:
+- **Resizing**: Area sampling (box filter) for downscaling, bilinear interpolation for upscaling.
+- **Grayscale**: SIMD-accelerated (NEON/SSE) color conversion using ITU-R BT.601 coefficients.
+- **Filtering**: 3x3 Gaussian blur and Laplacian sharpening.
+- **Gamma Correction**: LUT-based gamma normalization (2.2).
+
+### 3. Hash Algorithms (`src/hashes/`)
+Divided into specific implementations:
+- `ahash.c`: Average Hash (frequency-based).
+- `phash.c`: DCT-based hash (robust against moderate scaling/rotation).
+- `dhash.c`: Gradient-based hash (extremely fast).
+- `whash.c`: Wavelet-based (Haar) hash (multi-resolution).
+- `radial.c`: Rotationally invariant hash.
+- `color_moments.c`: Statistical color distribution.
+
+## Data Flow
+
+```mermaid
+graph TD
+    File[Image File/Memory] --> Loader[Loader Subsystem]
+    Loader -->|Raw Pixels| Context[ph_context_t]
+    Context -->|Downscale/Blur/Gamma| Preproc[Pre-processing]
+    Preproc -->|Grayscale Buffer| Algos[Hash Algorithms]
+    Algos -->|64-bit/Digest| Output[Resulting Hash]
+```
+
+## Key Structures
+
+### `ph_context_t`
+The central object containing:
+- Loaded pixel data.
+- Metadata (width, height, channels).
+- Pre-computed LUTs (Gamma).
+- Configurable parameters (DCT size, block size, weights).
+- Scratchpad memory for zero-allocation processing.

python_libphash-1.3.0/native/libphash/docs/development.md

@@ -0,0 +1,44 @@
+# Development Guide
+
+This guide outlines the standards and procedures for contributing to `libphash`.
+
+## Build Environment
+
+### Toolchains
+The project supports `gcc`, `clang`, and `msvc`. The `Makefile` allows compiler overrides:
+```bash
+make CC=clang
+```
+
+### Formatting
+We use `clang-format` with a custom style (based on LLVM with minor tweaks).
+- **Indentation**: 4 spaces.
+- **Rule**: Run `make format` before every commit.
+
+## Naming Conventions
+
+- **Public APIs**: Prefix with `ph_` (e.g., `ph_compute_ahash`).
+- **Internal Helper Functions**: Standard C naming, not exposed in `libphash.h`.
+- **Types**: Suffix with `_t` (e.g., `ph_context_t`).
+- **Files**: Lowercase with underscores (e.g., `color_hsv.c`).
+
+## Testing Strategy
+
+### 1. Unit Tests (`tests/test_*.c`)
+Each module should have a corresponding test file. We use a simple `test_macros.h` for assertions.
+
+### 2. Stability Tests (`tests/test_stability.c`)
+Ensures that different loading modes (RGB vs Grayscale) and different architectures (NEON vs Scalar) produce bit-exact or near-exact results.
+
+### 3. Benchmarks (`tests/test_benchmark.c`)
+Used for performance regression testing. Run with:
+```bash
+./test_benchmark hash tests/photo.jpeg 100
+```
+
+## Adding New Features
+
+1.  **Header**: Add the public signature to `include/libphash.h`.
+2.  **Implementation**: Add the source file to `src/` or `src/hashes/`.
+3.  **Build**: `Makefile` and `CMakeLists.txt` use wildcards, so new files are detected automatically.
+4.  **Documentation**: Update `docs/algorithms.md` and the function comments in the header (Doxygen style).