{"id":45551995,"url":"https://github.com/gudoshnikovn/python-libphash","last_synced_at":"2026-04-19T11:01:27.455Z","repository":{"id":332528127,"uuid":"1130160214","full_name":"gudoshnikovn/python-libphash","owner":"gudoshnikovn","description":"A Python binding for the libphash C library that provides efficient computation of perceptual image hashes for similarity detection.","archived":false,"fork":false,"pushed_at":"2026-03-30T12:06:06.000Z","size":303,"stargazers_count":0,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-30T14:12:47.787Z","etag":null,"topics":["c","cffi","perceptual-hashing","phash","python"],"latest_commit_sha":null,"homepage":"https://pypi.org/project/python-libphash/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/gudoshnikovn.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-01-08T05:44:14.000Z","updated_at":"2026-02-23T06:09:49.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/gudoshnikovn/python-libphash","commit_stats":null,"previous_names":["gudoshnikovn/python-libphash"],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/gudoshnikovn/python-libphash","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gudoshnikovn%2Fpython-libphash","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gudoshnikovn%2Fpython-libphash/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gudoshnikovn%2Fpython-libphash/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gudoshnikovn%2Fpython-libphash/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/gudoshnikovn","download_url":"https://codeload.github.com/gudoshnikovn/python-libphash/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gudoshnikovn%2Fpython-libphash/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32004043,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-18T20:23:30.271Z","status":"online","status_checked_at":"2026-04-19T02:00:07.110Z","response_time":55,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["c","cffi","perceptual-hashing","phash","python"],"created_at":"2026-02-23T05:18:33.616Z","updated_at":"2026-04-19T11:01:27.388Z","avatar_url":"https://github.com/gudoshnikovn.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# python-libphash\n\nHigh-performance Python bindings for [libphash](https://github.com/gudoshnikovn/libphash), a C library(v1.10.4) for perceptual image hashing.\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)\n\n## Overview\n\n`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.\n\n### Supported Algorithms\n\n*   **64-bit Hashes (uint64):**\n    *   `ahash`: Average Hash\n    *   `dhash`: Difference Hash\n    *   `phash`: Perceptual Hash (DCT based)\n    *   `whash`: Wavelet Hash\n    *   `mhash`: Median Hash\n    *   `color_hash`: Packed 42-bit HSV-based color hash (compatible with `imagehash.colorhash`).\n*   **Digest Hashes (Multi-byte):**\n    *   `bmh`: Block Mean Hash (256-bit digest).\n    *   `color_moments_hash`: Statistical color distribution digest (mean, variance, skewness, kurtosis).\n    *   `radial_hash`: Rotation-invariant Fourier-Mellin transform digest.\n\n## Installation\n\n### Prerequisites\n*   A C compiler (GCC/Clang or MSVC)\n*   Python 3.8 or higher\n\n### Install from PyPI\n```bash\npip install python-libphash\n# or using uv\nuv add python-libphash\n```\n\n### Install from source\n```bash\ngit clone --recursive https://github.com/yourusername/python-libphash.git\ncd python-libphash\npip install .\n# or using uv\nuv pip install .\n```\n\n## Quick Start\n\n### Quick Start (CLI)\nYou can quickly compute a hash from the command line after installation:\n```bash\npython -m libphash.utils --path photo.jpg --method phash\n```\n\n### Basic Usage\n```python\nfrom libphash import ImageContext, HashMethod, hamming_distance\n\n# Use the context manager for automatic memory management\nwith ImageContext(\"photo.jpg\") as ctx:\n    # Get standard 64-bit hashes\n    phash_val = ctx.phash\n    dhash_val = ctx.dhash\n    \n    print(f\"pHash: {phash_val:016x}\")\n    print(f\"dHash: {dhash_val:016x}\")\n\n# Compare two images\nfrom libphash import compare_images\ndistance = compare_images(\"image1.jpg\", \"image2.jpg\", method=HashMethod.PHASH)\nprint(f\"Hamming Distance: {distance}\")\n```\n\n### Customizing Algorithms \u0026 Performance\nFine-tune hashing algorithms for specific use cases. Note that hashes generated with different parameters are **not comparable**.\n\n*   **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.\n    *   **Fallback**: Automatically falls back to `stb_image` for other formats or if bundled decoders are disabled.\n\n```python\nwith ImageContext(\"photo.jpg\") as ctx:\n    # pHash (DCT) resolution\n    ctx.set_phash_params(dct_size=32, reduction_size=8)\n    \n    # Radial Hash precision\n    ctx.set_radial_params(projections=40, samples=128)\n    \n    # Block-based hashes (BMH) grid resolution\n    ctx.set_block_params(block_size=16)\n    \n    # Wavelet Hash (wHash) Mode: \"fast\" (default) or \"full\"\n    ctx.set_whash_mode(\"full\")\n    \n    # Custom Grayscale weights (R, G, B)\n    ctx.set_gray_weights(38, 75, 15)\n    \n    print(f\"Custom pHash: {ctx.phash:016x}\")\n```\n\n### Working with Digests (Advanced Hashes)\nAlgorithms like Radial Hash or Color Hash return a `Digest` object instead of a single integer.\n\n```python\nwith ImageContext(\"photo.jpg\") as ctx:\n    digest = ctx.radial_hash\n    print(f\"Digest size: {digest.size} bytes\")\n    print(f\"Raw data: {digest.data.hex()}\")\n\n# Comparing digests\nwith ImageContext(\"photo_v2.jpg\") as ctx2:\n    digest2 = ctx2.radial_hash\n    \n    # Hamming distance for bit-wise comparison\n    h_dist = digest.distance_hamming(digest2)\n    \n    # L2 (Euclidean) distance for similarity\n    l2_dist = digest.distance_l2(digest2)\n```\n\n## API Reference\n\n### `ImageContext`\nThe main class for loading images and computing hashes.\n*   `__init__(path=None, bytes_data=None)`: Load an image from a file path or memory.\n*   `set_gamma(gamma: float)`: Set gamma correction.\n*   `set_gray_weights(r, g, b)`: Set custom RGB weights for grayscale conversion.\n*   `set_phash_params(dct_size, reduction_size)`: Configure pHash DCT resolution.\n*   `set_radial_params(projections, samples)`: Configure Radial Hash precision.\n*   `set_block_params(block_size)`: Configure BMH/mHash grid resolution.\n*   `set_whash_mode(mode=\"fast\")`: Use \"fast\" (median) or \"full\" (ImageHash accurate 2D DWT).\n*   **Properties**: `ahash`, `dhash`, `phash`, `whash`, `mhash` (returns `int`).\n*   **Properties**: `bmh`, `color_hash`, `radial_hash` (returns `Digest`).\n\n### `Digest`\n*   `data`: The raw `bytes` of the hash.\n*   `size`: Length of the hash in bytes.\n*   `distance_hamming(other)`: Calculates bit-wise distance.\n*   `distance_l2(other)`: Calculates Euclidean distance.\n\n### Utilities\n*   `hamming_distance(h1: int, h2: int)`: Returns the number of differing bits between two 64-bit integers.\n*   `ph_can_use_libjpeg()`: Returns `True` if `libjpeg-turbo` is enabled.\n*   `ph_can_use_libpng()`: Returns `True` if `libpng` or `spng` is enabled.\n*   `get_hash(path, method)`: Quick way to get a hash without manual context management.\n*   `compare_images(path1, path2, method)`: Returns the Hamming distance between two image files.\n\n## Performance\nSince 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.\n\n| Algorithm | imagehash (s) | libphash (s) | Speedup |\n| :--- | :--- | :--- | :--- |\n| **aHash** | 0.2164 | 0.1033 | **1.92x** |\n| **pHash** | 0.3211 | 0.0842 | **3.40x** |\n| **dHash** | 0.2017 | 0.1048 | **1.80x** |\n| **wHash** | 1.7832 | 0.0869 | **17.16x** |\n\n*Benchmarks ran on 200 images (JPEG).*\n\n## License\nThis project is licensed under the MIT License - see the LICENSE file for details.\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgudoshnikovn%2Fpython-libphash","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgudoshnikovn%2Fpython-libphash","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgudoshnikovn%2Fpython-libphash/lists"}