Digests and comparison¶
Digest ¶
Digest(data: bytes, kind: DigestKind | int)
A multi-byte hash: the bytes and the kind that says how they may be compared.
BMH and mHash give bit vectors, Radial quantized coefficients, ColorHash a
histogram, ColorMoments a vector of signed 16-bit features. Each comparison method
accepts only the kinds it is meaningful for and raises :class:DigestKindError for
the others; :meth:similarity picks the comparison that belongs to the kind.
Digests are immutable, hashable, comparable for equality and picklable. hex()
and from_hex() give a text form that keeps the kind.
from_uint64
classmethod
¶
from_uint64(value: int) -> Digest
Wrap a 64-bit hash as an 8-byte BITS digest.
The most significant byte comes first, as in :func:hash_to_hex.
from_hex
classmethod
¶
from_hex(text: str) -> Digest
Parse the text form written by :meth:hex ("<kind>:<hex>").
hex ¶
Return the text form: the kind, a colon, the bytes in lowercase hex.
For example "bits:3fa0..."; :meth:from_hex parses it back.
hamming_distance ¶
hamming_distance(other: Digest) -> int
Count the differing bits between two BITS digests (BMH, mHash).
l2_distance ¶
l2_distance(other: Digest) -> float
Euclidean distance between two feature vectors (ColorMoments).
histogram_intersection ¶
histogram_intersection(other: Digest) -> float
Share of color two HISTOGRAM digests (ColorHash) have in common.
The result is 0.0 to 1.0.
radial_similarity ¶
radial_similarity(other: Digest) -> float
Peak cross-correlation of two Radial digests, -1.0 to 1.0.
Raises :class:NoStructureError when either digest is flat (all bytes equal),
as the Radial hash of an image without angular structure is: any score would be
invented. :data:RADIAL_PCC_THRESHOLD is the source's cut for "same image".
similarity ¶
similarity(other: Digest) -> float
Compare with the similarity measure that belongs to the digests' kind.
BITS: share of equal bits, 0.0 to 1.0. HISTOGRAM: histogram
intersection, 0.0 to 1.0. COEFFICIENTS: radial peak correlation, -1.0 to
1.0. VECTOR16 (ColorMoments) has no normalized similarity: use
:meth:l2_distance.
DigestKind ¶
Bases: IntEnum
What a digest's bytes mean, and so which comparisons it supports.
The values are those of ph_digest_kind_t.
hamming_distance ¶
Count the differing bits between two 64-bit hashes, 0 to 64.
similarity ¶
Share of equal bits between two 64-bit hashes.
1.0 means identical; unrelated images score near 0.5.
hash_to_hex ¶
Format a 64-bit hash as 16 lowercase hex digits, most significant first.
hash_from_hex ¶
Parse the 16 hex digits written by :func:hash_to_hex.