Add perceptual hashing (phash) support for image similarity detection #318

cavedave · 2026-01-28T11:01:23Z

Phash Implementation: Perceptual Hashing for Image Similarity Detection

Overview

This PR implements perceptual hashing (phash) functionality for AIL, enabling automatic detection of visually similar images. The implementation follows the same architectural pattern as DomHash and HHHash, creating Phash objects that correlate with Images and other similar Phash objects.

Key Features

Perceptual hashing: Uses imagehash library to calculate 64-bit perceptual hashes for images
Automatic correlation: Creates Phash ↔ Image and Phash ↔ Phash correlations
Similarity detection: Finds similar images using Hamming distance (configurable threshold, default: 8)
UI integration: Adds Phash object browser and correlation graph visualization
Comprehensive testing: 100% coverage for Phash objects, 92%+ for modules

Why Phash Was Chosen

Perceptual hashing (pHash) was selected for image similarity detection in AIL for several reasons:

Robustness: Detects visually similar images even after compression, resizing, or minor modifications
Efficiency: 64-bit hash enables fast comparison using Hamming distance
Proven algorithm: Uses well-established DCT-based approach implemented in imagehash library
Consistency: Follows same pattern as existing DomHash/HHHash implementations in AIL
Scalability: Lightweight hash values enable efficient storage and comparison

For detailed analysis, see: Image Analysis Document

Files Changed

New Files Created

bin/lib/objects/Phashs.py (122 lines)
- Phash class: Represents a perceptual hash value
- Phashs collection class: Manages Phash objects
- Module-level create() function: Idempotent Phash object creation
bin/modules/ImagePhash.py (71 lines)
- Processes images from Image queue
- Calculates phash, stores in Image metadata, creates Phash objects
- Creates Phash ↔ Image correlations
bin/modules/PhashCorrelation.py (121 lines)
- Processes Phash objects from queue
- Finds similar phashes using Hamming distance
- Creates Phash ↔ Phash correlations
var/www/blueprints/objects_phash.py (74 lines)
- Flask blueprint for Phash object routes
- /objects/phashes - List view
- /objects/phash/post - Form handling
- /objects/phash/range/json - Chart data
var/www/templates/objects/phash/PhashDaterange.html (164 lines)
- Jinja2 template for Phash object browser UI
- Date range filtering and object listing
tests/test_objects_phashes.py (339 lines)
- Comprehensive unit tests for Phash objects
- 27 tests covering all methods and edge cases
- 100% code coverage

Modified Files

bin/lib/objects/Images.py
- Added calculate_phash(): Calculates phash using imagehash.phash()
- Added get_phash(): Lazy-loads phash (calculates if not cached)
- Added set_phash(): Stores phash in Image metadata
- Added compare_phash(): Calculates Hamming distance between two phashes
- Added find_similar_images_by_phash(): Utility function for finding similar images
bin/lib/objects/Screenshots.py
- Added calculate_phash(), get_phash(), set_phash() (same as Images)
bin/lib/correlations_engine.py
- Added "phash": ["image", "phash"] to CORRELATION_TYPES_BY_OBJ
- Enables Phash ↔ Image and Phash ↔ Phash correlations
bin/lib/objects/ail_objects.py
- Registered Phash in OBJECTS_CLASS dictionary
bin/lib/ail_core.py
- Added 'phash' to AIL_OBJECTS set
- Added 'phash' to AIL_OBJECTS_CORRELATIONS_DEFAULT set
configs/modules.cfg
- Added [ImagePhash] section with queue configuration
- Added [PhashCorrelation] section with queue configuration
bin/LAUNCH.sh
- Added ImagePhash module to launch sequence
- Added PhashCorrelation module to launch sequence
configs/core.cfg.sample
- Added phash_max_hamming_distance = 8 configuration option
var/www/Flask_server.py
- Imported objects_phash blueprint
- Registered objects_phash blueprint with Flask app
tests/test_modules.py
- Added TestModuleImagePhash test class (8 tests)
- Added TestModulePhashCorrelation test class (3 tests)
- Added TestModulePhashCorrelationFindSimilar test class (6 tests)
- Added TestModulePhashCorrelationCompute test class (8 tests)
- Total: 25 module tests

Architecture: Following DomHash/HHHash Pattern

Phash follows the same object pattern as DomHash and HHHash:

Object Class: Phash extends AbstractDaterangeObject
Collection Class: Phashs extends AbstractDaterangeObjects
Hash Value = Object ID: Phash value becomes the object's unique identifier
Correlation via add(): Creates Phash ↔ Image correlation automatically
Module-based Creation: Uses ImagePhash module (like Phash uses modules, unlike DomHash/HHHash which are inline)

Key Difference: Phash adds similarity matching (Hamming distance) which DomHash/HHHash don't need (they use exact matching).

Correlations

Phash ↔ Image Correlation

Created automatically when ImagePhash module processes an image
Uses phash_obj.add(date, image) method
Bidirectional: Phash object shows correlated Images, Image shows correlated Phash

Phash ↔ Phash Correlation

Created by PhashCorrelation module
Finds similar phashes using Hamming distance ≤ phash_max_hamming_distance
Uses phash_obj.add_correlation('phash', '', similar_phash_id)
Enables graph visualization of similar images

Algorithm Details

Perceptual Hashing

Library: imagehash (external dependency)
Algorithm: DCT-based perceptual hash
Output: 64-bit hash as 16-character hex string (e.g., c6073f39b0949d4b)

Hamming Distance

Library: imagehash built-in subtraction operator
Range: 0-64 (0 = identical, 64 = completely different)
Default Threshold: 8 (configurable via phash_max_hamming_distance)

Testing

Test Coverage

Phash Objects: 100% coverage (27 tests)
ImagePhash Module: 92% coverage (8 tests)
PhashCorrelation Module: 96% coverage (17 tests)
Total: 52 tests

Running Tests

# Run all phash-related tests
python3 -m nose2 tests.test_objects_phashes tests.test_modules.TestModuleImagePhash tests.test_modules.TestModulePhashCorrelation -v

# With coverage
python3 -m nose2 tests.test_objects_phashes tests.test_modules.TestModuleImagePhash tests.test_modules.TestModulePhashCorrelation --coverage bin/lib/objects/Phashs.py bin/modules/ImagePhash.py bin/modules/PhashCorrelation.py --with-coverage --coverage-report term-missing

Configuration

Required Configuration

Add to configs/core.cfg:

[Images]
phash_max_hamming_distance = 8

Module Configuration

Already added to configs/modules.cfg:

[ImagePhash]
subscribe = Image
publish = PhashCorrelation

[PhashCorrelation]
subscribe = PhashCorrelation

Dependencies

Optional Dependencies

imagehash - Perceptual hashing library
PIL (Pillow) - Image processing

Both are gracefully handled if missing (functions return None).

Performance Considerations

Phash calculation: Performed once per image, cached in metadata
Similarity search: O(n) scan of all Phash objects (acceptable for current scale)
Future optimization: Could add indexing or approximate nearest neighbor search for large datasets

Note: Performance analysis needs to be performed with large volume of data. Initial tests on small datasets (<100 files) and library documentation indicate these functions (phash and hamming) are fast.

Known Limitations

Old images: Images imported before phash implementation won't have phash until:
- ImagePhash module processes them (if re-queued)
- Manual reprocessing via backfill script
- This is expected behavior
Correlation display: "Direct Correlations" shows phash: 0 for images because:
- Phash correlations are stored as Phash ↔ Image (not Image ↔ Phash in direct view)
- Graph view correctly shows phash correlations
- This matches DomHash/HHHash pattern

Breaking Changes

None. This is a new feature addition with no breaking changes to existing functionality.

Screenshots

Checklist

Code follows existing patterns (DomHash/HHHash)
All tests passing
High test coverage (100% Phash, 92%+ modules)
Error handling implemented

adulau · 2026-01-29T10:05:37Z

Thanks a lot for the pull-request.

We are currently discussing this aspect:

Similarity search: O(n) scan of all Phash objects (acceptable for current scale)

Could we imagine that we do BITOPT directly and structure it in a tree to make faster lookup especially when we have a lot of images?

Maybe we could already keep your version as-is (after a review @Terrtia ) and update the processing model later to have an efficient storage structure to match the binary value in a tree-like structure (or other).

Terrtia · 2026-01-29T10:17:36Z

bin/lib/correlations_engine.py

    "gtracker": ["domain", "item"],
    "hhhash": ["domain"],
-    "image": ["barcode", "chat", "chat-subchannel", "chat-thread", "message", "ocr", "qrcode", "user-account"],  # TODO subchannel + threads ????
+    "image": ["barcode", "chat", "chat-subchannel", "chat-thread", "message", "ocr", "phash", "qrcode", "user-account", "image", "screenshot"],  # TODO subchannel + threads ????


the image object shouldn't correlate with another image or screenshot.

"phash": ["image", "phash"], is used to correlate phash with images and screenshots

This is in the new code

Terrtia · 2026-01-29T10:18:28Z

bin/lib/correlations_engine.py

    "pgp": ["chat", "domain", "item", "message", "ocr"],
    "qrcode": ["chat", "cve", "cryptocurrency", "decoded", "domain", "image", "message", "screenshot"],     # "chat-subchannel", "chat-thread" ?????
-    "screenshot": ["barcode", "domain", "item", "qrcode"],
+    "screenshot": ["barcode", "domain", "item", "qrcode", "image"],


a screenshot object shouldn't correlate with an image.

Terrtia · 2026-01-29T10:23:24Z

bin/lib/objects/Phashs.py

@@ -0,0 +1,121 @@
+#!/usr/bin/env python3


imagehash is missing from the requirements.

Terrtia · 2026-01-29T10:32:06Z

bin/lib/objects/Images.py

            description = description.replace("`", ' ')
        return description

+    def calculate_phash(self):


All pHash-related functions should be moved to lib/objects/Phashs.
This would make the code clearer, easier to maintain, and help avoid import issues.

Since pHash is now implemented as a dedicated object, it can be retrieved by the correlation engine using:
self.get_correlation('phash').get('phash')

Terrtia · 2026-01-29T10:32:40Z

bin/lib/objects/Screenshots.py

            model = get_default_image_description_model()
        return self._get_field(f'desc:{model}')

+    def calculate_phash(self):


All pHash-related functions should be moved to lib/objects/Phashs.
This would make the code clearer, easier to maintain, and help avoid import issues.

Since pHash is now implemented as a dedicated object, it can be retrieved by the correlation engine using:
self.get_correlation('phash').get('phash')

I did this in commit 6556837

Terrtia · 2026-01-29T13:14:46Z

bin/modules/ImagePhash.py

@@ -0,0 +1,70 @@
+#!/usr/bin/env python3


I would prefer if the ImagePhash and PhashCorrelation modules were merged into a single module to reduce overhead.

The combined module should first check whether the image already has an existing pHash correlation using:
image.exists_correlation('phash')

If no pHash exists, it should:

Create a new pHash object

Add a new correlation between the image and the created pHash

Compare it with existing pHashes

Add a direct correlation between the two pHashes if the Hamming distance is below the threshold

I agree with this. This is a better design

…or retrieval; tests pass

adulau · 2026-01-29T13:29:11Z

@cavedave We did a test of rewrite with copilot for the tree-like structure. If you want to review it, feel free.

#319

This sounds sane but some tests from your side would be awesome.

cavedave · 2026-01-29T15:07:15Z

@adulau @Terrtia I agree with these suggestions. It will take me a few days to go through these fixes

adulau · 2026-01-29T15:27:53Z

PR_DESCRIPTION.md

+- **Consistency**: Follows same pattern as existing DomHash/HHHash implementations in AIL
+- **Scalability**: Lightweight hash values enable efficient storage and comparison
+
+For detailed analysis, see: [Image Analysis Document](file:///home/david-curran/Nextcloud/Hoplite/docs/ImageAnalysisDec.docx)


Just for your information, maybe you want to the document in the repo and not the reference to the nextcloud local directory.

Is there good location to share this document with you? I am not sure it should be public so I am not sure it should be in the repo.

So we can keep it in the HOPLITE repo and remove the reference in this markdown. Thank you!

Add perceptual hashing (phash) support for image similarity detection

c793a16

Terrtia self-requested a review January 28, 2026 11:06

Terrtia reviewed Jan 29, 2026

View reviewed changes

bin/lib/objects/Phashs.py

@@ -0,0 +1,121 @@

#!/usr/bin/env python3

Copy link

Member

Terrtia Jan 29, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

imagehash is missing from the requirements.

Terrtia reviewed Jan 29, 2026

View reviewed changes

Copilot AI mentioned this pull request Jan 29, 2026

Implement perceptual hashing with BK-tree indexing for O(log n) similarity search #319

Draft

Terrtia reviewed Jan 29, 2026

View reviewed changes

Address Terrtia review: move phash logic to Phashs; use correlation f…

6556837

…or retrieval; tests pass

adulau reviewed Jan 29, 2026

View reviewed changes

Add perceptual hashing (phash) support for image similarity detection #318

Are you sure you want to change the base?

Add perceptual hashing (phash) support for image similarity detection #318

Uh oh!

Conversation

cavedave commented Jan 28, 2026

Phash Implementation: Perceptual Hashing for Image Similarity Detection

Overview

Key Features

Why Phash Was Chosen

Files Changed

New Files Created

Modified Files

Architecture: Following DomHash/HHHash Pattern

Correlations

Phash ↔ Image Correlation

Phash ↔ Phash Correlation

Algorithm Details

Perceptual Hashing

Hamming Distance

Testing

Test Coverage

Running Tests

Configuration

Required Configuration

Module Configuration

Dependencies

Optional Dependencies

Performance Considerations

Known Limitations

Breaking Changes

Screenshots

Checklist

Uh oh!

adulau commented Jan 29, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

adulau commented Jan 29, 2026

Uh oh!

cavedave commented Jan 29, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants