comicbox.formats.base.online.cover_hash

source module comicbox.formats.base.online.cover_hash

Cover-hash primitives and the matcher’s hashing-invocation policy.

pHash via the imagehash library (8x8 = 64 bits). Mokkari already returns a precomputed pHash in Issue.cover_hash, so for Metron candidates we string-compare. ComicVine and GCD candidates require downloading the cover image — that’s M6’s concern.

The matcher invocation policy decides when hashing runs:

  • Skip when the top metadata score is unambiguous (clears confidence_threshold AND well-separated from runner-up).
  • Hash top K candidates when uncertain or close-call.
  • Skip when nothing clears min_confidence (hashing won’t save it).

Classes

Functions

  • compute_phash — Return the pHash of an image as a hex string.

  • parse_hash — Parse a hex-encoded pHash string back into an ImageHash.

  • hamming_distance — Hamming distance between two hex-encoded pHash strings.

  • cover_score — Convert a Hamming distance into a [0, 1] similarity score.

source compute_phash(image_bytes: bytes) → str

Return the pHash of an image as a hex string.

source parse_hash(hex_str: str) → ImageHash

Parse a hex-encoded pHash string back into an ImageHash.

source hamming_distance(a: str, b: str) → int

Hamming distance between two hex-encoded pHash strings.

source cover_score(local_hash: str, candidate_hash: str) → float

Convert a Hamming distance into a [0, 1] similarity score.

s_cover = 1 - (hamming / 64). Clamped to [0, 1] for safety.

source class CoverHashUrlCache(db_path: Any)

Tiny SQLite cache mapping cover URLs to their pHash strings.

Open / create the sqlite cache file at db_path.

Methods

  • get — Return the cached pHash for a cover URL, or None if absent.

  • set — Store a pHash for a cover URL, overwriting any previous value.

source method CoverHashUrlCache.get(url: str) → str | None

Return the cached pHash for a cover URL, or None if absent.

source method CoverHashUrlCache.set(url: str, phash: str) → None

Store a pHash for a cover URL, overwriting any previous value.