Perception

0.8.4 verified Fri May 01 auth: no python

Perception provides flexible, well-documented, and comprehensively tested tooling for perceptual hashing research, development, and production use. Version 0.8.4 supports Python >=3.10 <4.0. Release cadence is irregular, with updates every few months.

pip install perception

Common errors

error AttributeError: module 'perception' has no attribute 'hashers' ↓

cause Hashers submodule not imported; perception package exposes only ImageHash and tools by default.

fix

Run 'from perception import hashers' before using hashers.

error ImportError: cannot import name 'ImageHash' from 'perception.hashers' ↓

cause ImageHash moved to top level in v0.7.

fix

Use 'from perception import ImageHash'.

error TypeError: unsupported operand type(s) for -: 'ImageHash' and 'int' ↓

cause Subtracting an int from an ImageHash is not supported; only ImageHash - ImageHash works.

fix

Ensure both operands are ImageHash instances: 'hash1 - hash2'.

error ValueError: The truth value of an ImageHash is ambiguous ↓

cause ImageHash does not implement __bool__; cannot be used in if condition directly.

fix

Compare explicitly: 'if hash1.distance(hash2) == 0:' or 'if hash1 == hash2:'.

Warnings

breaking In v0.7, ImageHash became a top-level export. Importing from 'perception.hashers.ImageHash' now raises ImportError. ↓

fix Use 'from perception import ImageHash' instead.

deprecated The 'perception.hashers.dhash' function is deprecated in favor of 'perception.hashers.DHash' class. ↓

fix Instantiate 'hashers.DHash()' instead of calling 'hashers.dhash()'.

gotcha Computing a hash with a non-existent image file returns a zero hash without raising an error. This may silently produce false matches. ↓

fix Check file existence before computing, or catch FileNotFoundError if using from perception.tools.

gotcha The __sub__ method of ImageHash returns an integer Hamming distance, but the hash objects themselves are not directly comparable with <, >, etc. Only equality and subtraction work. ↓

fix Use hash1 - hash2 for distance; for comparison, convert to binary string manually.

Imports

ImageHash
wrong
```
from perception.hashers import ImageHash
```
correct
```
from perception import ImageHash
```
Old import path deprecated in v0.7; ImageHash is now a top-level alias.
hashers
wrong
```
import perception.hashers
```
correct
```
from perception import hashers
```
Submodule must be imported explicitly; direct attribute access fails.
tools
```
from perception import tools
```

Quickstart

Compute perceptual hashes for two images and compare using Hamming distance.

from perception import hashers

hasher = hashers.PHash()
hash1 = hasher.compute('image1.jpg')
hash2 = hasher.compute('image2.jpg')
distance = hash1 - hash2
print(f'Hamming distance: {distance}')