Hashing¶
hash ¶
hash(source: Source, algorithm: Uint64Algorithm | Uint64Name = ..., *, config: Config | None = ...) -> int
hash(source: Source, algorithm: DigestAlgorithm | DigestName, *, config: Config | None = ...) -> Digest
hash(source: Source, algorithm: AlgorithmLike, *, config: Config | None = ...) -> int | Digest
hash(source: Source, algorithm: AlgorithmLike = PHASH, *, config: Config | None = None) -> int | Digest
Hash one image.
source is a path, encoded bytes, a binary file object, an array of pixels or a
Pillow image. Returns an int for aHash, dHash, pHash and wHash, a
:class:Digest for the others.
ImageContext ¶
ImageContext(config: Config | None = None)
One image and the configuration to hash it with: a libphash ph_context_t.
Load an image with one of the load_* methods, then compute any number of hashes
from it; loading the next image reuses the context's buffers, which makes a context
kept across a loop faster than :func:hash per image.
A context is safe to share between threads: the calls into C are serialized on a
lock of the context. Threads that work in parallel each need their own context (or a
batch, :func:hash_files). Close it with :meth:close or a with block; one
left to the garbage collector is freed too.
width
property
¶
Width of the loaded image (after orientation and decode scale), 0 if none.
channels
property
¶
3 for color, 1 for grayscale.
An alpha channel is resolved at load and not kept.
load ¶
load(source: Source) -> None
Load whatever source is.
source is a path, encoded bytes, a binary file object, an array of pixels or
a Pillow image. Bytes are always the encoded file, never a path.
load_file ¶
load_file(path: StrPath) -> None
Load an image file. On failure the context holds no image.
load_bytes ¶
Load an encoded image (JPEG, PNG, WebP, ...) from memory, without a copy.
The buffer must not change while the call runs. On failure the context holds no image.
load_fileobj ¶
load_fileobj(fileobj: SupportsRead) -> None
Read a binary file object to its end and load the bytes.
The object is an open file, an io.BytesIO, a response body or anything else
with a read() that returns bytes.
load_pixels ¶
load_pixels(pixels: PixelArray, channel_order: ChannelOrder = 'rgb') -> None
Load decoded pixels.
pixels is an 8-bit array of shape (h, w), (h, w, 1), (h, w, 3) or (h, w, 4),
e.g. a numpy uint8 array. channel_order="bgr" reads OpenCV's order. The
pixels are copied into the context, and no EXIF orientation applies. On failure
the previously loaded image stays loaded.
load_pil ¶
load_pil(image: PILImage) -> None
Load a Pillow image.
:func:pixels_from_pil describes how each mode is read.
hash ¶
hash(algorithm: DigestAlgorithm | DigestName) -> Digest
hash(algorithm: AlgorithmLike) -> int | Digest
hash(algorithm: AlgorithmLike = PHASH) -> int | Digest
Compute one hash of the loaded image.
Returns an int for aHash, dHash, pHash and wHash, a :class:Digest for the
others.
hashes ¶
hashes(*algorithms: AlgorithmLike) -> dict[Algorithm, int | Digest]
Compute several hashes at once, all of the same loaded image.
The 64-bit ones share their work on the full image (one ph_compute_multi
call); digests are computed one by one. No other thread loads an image in
between.
phash ¶
Perceptual hash: the low-frequency DCT block of a reduction.
Each coefficient is compared with the block's median.
whash ¶
Wavelet hash: the low-frequency Haar band of a reduction.
Each coefficient is compared with the band's median.
mhash ¶
mhash() -> Digest
Marr-Hildreth hash: a Laplacian-of-Gaussian response (BITS).
Nine bits per window, 576 bits in all.
Algorithm ¶
Bases: IntEnum
A hash algorithm; the values are libphash's ph_algorithm_t.
Wherever an algorithm is expected, its libphash name ("phash",
"color_moments") is accepted too; str(algorithm) is that name.