python-libphash 1.4.0__tar.gz → 1.4.1__tar.gz

python_libphash-1.4.1/PKG-INFO

@@ -0,0 +1,191 @@
+Metadata-Version: 2.4
+Name: python-libphash
+Version: 1.4.1
+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"
+Requires-Dist: setuptools; 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"
+Requires-Dist: scikit-learn; extra == "benchmark"
+Requires-Dist: tqdm; extra == "benchmark"
+Requires-Dist: numpy; extra == "benchmark"
+Dynamic: license-file
+
+# python-libphash
+
+High-performance Python bindings for [libphash](https://github.com/gudoshnikovn/libphash), a C library(v1.10.4) 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/)
+
+## Overview
+
+`libphash` provides multiple algorithms to generate "perceptual hashes" of images. Unlike cryptographic hashes (like MD5 or SHA256), perceptual hashes change only slightly if the image is resized, compressed, or has minor color adjustments. This makes them ideal for finding duplicate or similar images.
+
+### Supported Algorithms
+
+*   **64-bit Hashes (uint64):**
+    *   `ahash`: Average Hash
+    *   `dhash`: Difference Hash
+    *   `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 (256-bit digest).
+    *   `color_moments_hash`: Statistical color distribution digest (mean, variance, skewness, kurtosis).
+    *   `radial_hash`: Rotation-invariant Fourier-Mellin transform digest.
+
+## Installation
+
+### Prerequisites
+*   A C compiler (GCC/Clang or MSVC)
+*   Python 3.8 or higher
+
+### Install from PyPI
+```bash
+pip install python-libphash
+# or using uv
+uv add python-libphash
+```
+
+### Install from source
+```bash
+git clone --recursive https://github.com/yourusername/python-libphash.git
+cd python-libphash
+pip install .
+# or using uv
+uv pip install .
+```
+
+## Quick Start
+
+### Quick Start (CLI)
+You can quickly compute a hash from the command line after installation:
+```bash
+python -m libphash.utils --path photo.jpg --method phash
+```
+
+### Basic Usage
+```python
+from libphash import ImageContext, HashMethod, hamming_distance
+
+# Use the context manager for automatic memory management
+with ImageContext("photo.jpg") as ctx:
+    # Get standard 64-bit hashes
+    phash_val = ctx.phash
+    dhash_val = ctx.dhash
+    
+    print(f"pHash: {phash_val:016x}")
+    print(f"dHash: {dhash_val:016x}")
+
+# Compare two images
+from libphash import compare_images
+distance = compare_images("image1.jpg", "image2.jpg", method=HashMethod.PHASH)
+print(f"Hamming Distance: {distance}")
+```
+
+### Customizing Algorithms & Performance
+Fine-tune hashing algorithms for specific use cases. Note that hashes generated with different parameters are **not comparable**.
+
+*   **Ultra-Fast Image Decoding**: `libphash` bundles high-performance decoders for JPEG, PNG, and WebP. It uses `libjpeg-turbo` (TurboJPEG API), `libpng`/`spng`, and `libwebp` with SIMD acceleration (SSE/NEON/AVX2). 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` for other formats or if bundled decoders are disabled.
+
+```python
+with ImageContext("photo.jpg") as ctx:
+    # pHash (DCT) resolution
+    ctx.set_phash_params(dct_size=32, reduction_size=8)
+    
+    # Radial Hash precision
+    ctx.set_radial_params(projections=40, samples=128)
+    
+    # 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)
+    
+    print(f"Custom pHash: {ctx.phash:016x}")
+```
+
+### Working with Digests (Advanced Hashes)
+Algorithms like Radial Hash or Color Hash return a `Digest` object instead of a single integer.
+
+```python
+with ImageContext("photo.jpg") as ctx:
+    digest = ctx.radial_hash
+    print(f"Digest size: {digest.size} bytes")
+    print(f"Raw data: {digest.data.hex()}")
+
+# Comparing digests
+with ImageContext("photo_v2.jpg") as ctx2:
+    digest2 = ctx2.radial_hash
+    
+    # Hamming distance for bit-wise comparison
+    h_dist = digest.distance_hamming(digest2)
+    
+    # L2 (Euclidean) distance for similarity
+    l2_dist = digest.distance_l2(digest2)
+```
+
+## API Reference
+
+### `ImageContext`
+The main class for loading images and computing hashes.
+*   `__init__(path=None, bytes_data=None)`: Load an image from a file path or memory.
+*   `set_gamma(gamma: float)`: Set gamma correction.
+*   `set_gray_weights(r, g, b)`: Set custom RGB weights for grayscale conversion.
+*   `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`).
+
+### `Digest`
+*   `data`: The raw `bytes` of the hash.
+*   `size`: Length of the hash in bytes.
+*   `distance_hamming(other)`: Calculates bit-wise distance.
+*   `distance_l2(other)`: Calculates Euclidean distance.
+
+### 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 SIMD-accelerated decoders (SSE4.2, AVX2, NEON), `libphash` is significantly faster than pure-Python alternatives while maintaining top-tier accuracy.
+
+| Algorithm | imagehash (s) | libphash (s) | Speedup |
+| :--- | :--- | :--- | :--- |
+| **aHash** | 0.2164 | 0.1033 | **1.92x** |
+| **pHash** | 0.3211 | 0.0842 | **3.40x** |
+| **dHash** | 0.2017 | 0.1048 | **1.80x** |
+| **wHash** | 1.7832 | 0.0869 | **17.16x** |
+
+*Benchmarks ran on 200 images (JPEG).*
+
+## License
+This project is licensed under the MIT License - see the LICENSE file for details.
+

python_libphash-1.4.1/README.md

@@ -0,0 +1,162 @@
+# python-libphash
+
+High-performance Python bindings for [libphash](https://github.com/gudoshnikovn/libphash), a C library(v1.10.4) 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/)
+
+## Overview
+
+`libphash` provides multiple algorithms to generate "perceptual hashes" of images. Unlike cryptographic hashes (like MD5 or SHA256), perceptual hashes change only slightly if the image is resized, compressed, or has minor color adjustments. This makes them ideal for finding duplicate or similar images.
+
+### Supported Algorithms
+
+*   **64-bit Hashes (uint64):**
+    *   `ahash`: Average Hash
+    *   `dhash`: Difference Hash
+    *   `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 (256-bit digest).
+    *   `color_moments_hash`: Statistical color distribution digest (mean, variance, skewness, kurtosis).
+    *   `radial_hash`: Rotation-invariant Fourier-Mellin transform digest.
+
+## Installation
+
+### Prerequisites
+*   A C compiler (GCC/Clang or MSVC)
+*   Python 3.8 or higher
+
+### Install from PyPI
+```bash
+pip install python-libphash
+# or using uv
+uv add python-libphash
+```
+
+### Install from source
+```bash
+git clone --recursive https://github.com/yourusername/python-libphash.git
+cd python-libphash
+pip install .
+# or using uv
+uv pip install .
+```
+
+## Quick Start
+
+### Quick Start (CLI)
+You can quickly compute a hash from the command line after installation:
+```bash
+python -m libphash.utils --path photo.jpg --method phash
+```
+
+### Basic Usage
+```python
+from libphash import ImageContext, HashMethod, hamming_distance
+
+# Use the context manager for automatic memory management
+with ImageContext("photo.jpg") as ctx:
+    # Get standard 64-bit hashes
+    phash_val = ctx.phash
+    dhash_val = ctx.dhash
+    
+    print(f"pHash: {phash_val:016x}")
+    print(f"dHash: {dhash_val:016x}")
+
+# Compare two images
+from libphash import compare_images
+distance = compare_images("image1.jpg", "image2.jpg", method=HashMethod.PHASH)
+print(f"Hamming Distance: {distance}")
+```
+
+### Customizing Algorithms & Performance
+Fine-tune hashing algorithms for specific use cases. Note that hashes generated with different parameters are **not comparable**.
+
+*   **Ultra-Fast Image Decoding**: `libphash` bundles high-performance decoders for JPEG, PNG, and WebP. It uses `libjpeg-turbo` (TurboJPEG API), `libpng`/`spng`, and `libwebp` with SIMD acceleration (SSE/NEON/AVX2). 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` for other formats or if bundled decoders are disabled.
+
+```python
+with ImageContext("photo.jpg") as ctx:
+    # pHash (DCT) resolution
+    ctx.set_phash_params(dct_size=32, reduction_size=8)
+    
+    # Radial Hash precision
+    ctx.set_radial_params(projections=40, samples=128)
+    
+    # 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)
+    
+    print(f"Custom pHash: {ctx.phash:016x}")
+```
+
+### Working with Digests (Advanced Hashes)
+Algorithms like Radial Hash or Color Hash return a `Digest` object instead of a single integer.
+
+```python
+with ImageContext("photo.jpg") as ctx:
+    digest = ctx.radial_hash
+    print(f"Digest size: {digest.size} bytes")
+    print(f"Raw data: {digest.data.hex()}")
+
+# Comparing digests
+with ImageContext("photo_v2.jpg") as ctx2:
+    digest2 = ctx2.radial_hash
+    
+    # Hamming distance for bit-wise comparison
+    h_dist = digest.distance_hamming(digest2)
+    
+    # L2 (Euclidean) distance for similarity
+    l2_dist = digest.distance_l2(digest2)
+```
+
+## API Reference
+
+### `ImageContext`
+The main class for loading images and computing hashes.
+*   `__init__(path=None, bytes_data=None)`: Load an image from a file path or memory.
+*   `set_gamma(gamma: float)`: Set gamma correction.
+*   `set_gray_weights(r, g, b)`: Set custom RGB weights for grayscale conversion.
+*   `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`).
+
+### `Digest`
+*   `data`: The raw `bytes` of the hash.
+*   `size`: Length of the hash in bytes.
+*   `distance_hamming(other)`: Calculates bit-wise distance.
+*   `distance_l2(other)`: Calculates Euclidean distance.
+
+### 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 SIMD-accelerated decoders (SSE4.2, AVX2, NEON), `libphash` is significantly faster than pure-Python alternatives while maintaining top-tier accuracy.
+
+| Algorithm | imagehash (s) | libphash (s) | Speedup |
+| :--- | :--- | :--- | :--- |
+| **aHash** | 0.2164 | 0.1033 | **1.92x** |
+| **pHash** | 0.3211 | 0.0842 | **3.40x** |
+| **dHash** | 0.2017 | 0.1048 | **1.80x** |
+| **wHash** | 1.7832 | 0.0869 | **17.16x** |
+
+*Benchmarks ran on 200 images (JPEG).*
+
+## License
+This project is licensed under the MIT License - see the LICENSE file for details.
+

python_libphash-1.4.1/native/libphash/README.md

@@ -0,0 +1,119 @@
+# libphash
+
+A high-performance, portable C library for Perceptual Image Hashing.
+
+`libphash` is designed for speed and efficiency, providing a robust set of algorithms for image fingerprinting with native, SIMD-accelerated decoders and a zero-fragmentation memory model.
+
+## Language Bindings
+
+* **Python**: [python-libphash](https://github.com/gudoshnikovn/python-libphash) (`pip install python-libphash`)
+* *More bindings (Node.js, Rust, Go) are in development.*
+
+---
+
+## Core Features
+
+* **Multiple Algorithms**: `aHash`, `dHash`, `pHash` (DCT-based), `wHash` (Wavelet), `mHash`, `BMH`, `Radial`, and `ColorHash`.
+* **High-Performance Decoders**: Built-in support for `libjpeg-turbo`, `libpng`, `spng`, and `libwebp` with SIMD acceleration (NEON/SSE) and `mmap` optimization.
+* **Fast Grayscale Loading**: Native decoders can perform grayscale conversion during decompression, significantly reducing CPU cycles and memory overhead.
+* **Zero-Fragmentation Arena**: Optimized context-based **Arena Allocator** for internal operations, ensuring predictable performance in high-load environments.
+* **FFI-Friendly**: Clean C API with opaque pointers, designed for seamless integration with Python, Rust, Node.js, and Go.
+* **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`, `libwebp` | Self-contained (vendor submodules) | Production, massive datasets, server-side processing |
+| **Minimal** | `stb_image` (fallback) | Zero | Embedded systems, quick scripts, simple builds |
+
+---
+
+## Building & Installation
+
+### Recommended (CMake)
+
+Best for managing bundled high-performance decoders and system integration.
+
+```bash
+mkdir build && cd build
+cmake .. -DCMAKE_BUILD_TYPE=Release
+make -j$(nproc)
+sudo make install
+
+```
+
+### Portable (Makefile)
+
+Fast and simple for minimal builds or static linking.
+
+```bash
+# Build static library
+make -j8
+
+# Run tests
+make test
+
+```
+
+---
+
+## Usage Example
+
+### C Code
+
+```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;
+}
+
+```
+
+### Compiling & Linking
+
+To compile your application with `libphash`:
+
+```bash
+gcc main.c -o my_app -lphash
+
+```
+
+---
+
+## License & Credits
+
+This project is licensed under the **MIT License**. See the [LICENSE](LICENSE) file for the full text.
+
+### Third-Party Software
+
+`libphash` bundles several high-performance libraries to ensure zero-dependency builds:
+
+* **libjpeg-turbo (v3.1.4)**: IJG, BSD-3-Clause, zlib.
+* **libpng (v1.6.56)**: libpng License 2.0.
+* **libwebp (v1.6.0)**: WebP License (BSD 3-Clause).
+* **spng (v0.7.4)**: BSD 2-Clause License.
+* **stb_image (v2.30)**: Public Domain / MIT.
+* **stb_image_resize2 (v2.18)**: Public Domain / MIT.
+
+For detailed licensing information regarding these components, please refer to [THIRD-PARTY-NOTICES.md](THIRD-PARTY-NOTICES.md).

python_libphash-1.4.1/native/libphash/THIRD-PARTY-NOTICES.md

@@ -0,0 +1,97 @@
+# Third-Party Software Notices
+
+This document contains licensing information for third-party libraries bundled with **libphash** in the `vendor/` directory.
+
+While **libphash** itself is licensed under the **MIT License**, the following components are subject to their respective licenses.
+
+---
+
+## 1. libjpeg-turbo
+
+* **Project:** [https://libjpeg-turbo.org/](https://libjpeg-turbo.org/)
+* **License:** IJG, Modified BSD, and zlib
+
+`libjpeg-turbo` is covered by three compatible licenses:
+
+1. **The IJG (Independent JPEG Group) License**: This applies to the original libjpeg code.
+2. **The Modified (3-clause) BSD License**: This applies to the TurboJPEG API and most of the SIMD extensions.
+3. **The zlib License**: This applies to the libjpeg-turbo SIMD extensions based on the work of the Independent JPEG Group.
+
+*Notice:* This software is based in part on the work of the Independent JPEG Group.
+
+---
+
+## 2. libpng
+
+* **Project:** [http://www.libpng.org/pub/png/libpng.html](http://www.libpng.org/pub/png/libpng.html)
+* **License:** libpng License 2.0
+
+Copyright (c) 1995-2022 The PNG Reference Library Authors.
+Copyright (c) 2018-2022 Cosmin Truta.
+Copyright (c) 2000-2002, 2004, 2006-2018 Glenn Randers-Pehrson.
+Copyright (c) 1996-1997 Andreas Dilger.
+Copyright (c) 1995-1996 Guy Eric Schalnat, Group 42, Inc.
+
+The libpng software is provided "AS IS", without warranty of any kind, express or implied.
+
+---
+
+## 3. spng (Simple PNG)
+
+* **Project:** [https://github.com/randy408/libspng](https://github.com/randy408/libspng)
+* **License:** BSD 2-Clause "Simplified" License
+
+Copyright (c) 2018-2023, Randy Shin. All rights reserved.
+
+Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
+2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
+
+---
+
+## 4. stb_image.h
+
+* **Project:** [https://github.com/nothings/stb](https://github.com/nothings/stb)
+* **License:** Public Domain / MIT / Unlicense
+
+This software is dual-licensed to the public domain and under the following license: you are free to use this software under the terms of the MIT license or the Unlicense.
+
+Copyright (c) 2017 Sean Barrett.
+
+## 5. libwebp
+
+* **Project:** [https://developers.google.com/speed/webp/](https://developers.google.com/speed/webp/)
+* **License:** BSD 3-Clause License
+
+Copyright (c) 2010, Google Inc. All rights reserved.
+
+Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
+2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
+3. Neither the name of Google nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.
+
+---
+
+## 6. stb_image_resize2.h
+
+* **Project:** [https://github.com/nothings/stb](https://github.com/nothings/stb)
+* **License:** Public Domain / MIT / Unlicense
+
+This software is dual-licensed to the public domain and under the following license: you are free to use this software under the terms of the MIT license or the Unlicense.
+
+Copyright (c) 2023 Jeff Roberts and Jorge L Rodriguez.
+
+---
+
+### Summary Table
+
+| Library | Directory | License Type |
+| --- | --- | --- |
+| **libjpeg-turbo** | `vendor/libjpeg-turbo` | IJG / BSD-3 / zlib |
+| **libpng** | `vendor/libpng` | libpng License 2.0 |
+| **libwebp** | `vendor/libwebp` | BSD 3-Clause |
+| **spng** | `vendor/spng` | BSD 2-Clause |
+| **stb_image** | `vendor/stb_image.h` | Public Domain (MIT) |
+| **stb_image_resize2** | `vendor/stb_image_resize2.h` | Public Domain (MIT) |