digital-art-api / tests /test_phash.py
Ruzzel Mendoza
fallback legacy
18f4339
Raw History Blame Contribute Delete
39.1 kB
"""
Tests for the perceptual-hash plagiarism pipeline (lib/phash.py).
Covers:
1. Entropy filtering excludes flat blocks (+ low_content_warning fallback)
2. Consensus scoring vs single-minimum scoring (synthetic fixture)
3. Transform/geometric consistency calculation
4. Calibration score conversion (calibrated_confidence)
5. Sparse/minimalist artwork vs exact copy (multiplier must not over-suppress)
6. Regression: unrelated artworks with matching backgrounds (original bug)
7. Rotation-aware global pre-filter
"""
import io
import json
import os
import numpy as np
import pytest
from PIL import Image, ImageDraw
from lib import phash
# -----------------------------
# Synthetic image fixtures
# -----------------------------
def to_stream(img, fmt="PNG"):
buf = io.BytesIO()
img.save(buf, format=fmt)
buf.seek(0)
return buf
def flat_image(color=(255, 255, 255), size=(256, 256)):
return Image.new("RGB", size, color)
def noise_image(seed=0, size=(256, 256)):
"""Full-frame high-detail noise: every block is content-bearing."""
rng = np.random.default_rng(seed)
arr = rng.integers(0, 256, size=(size[1], size[0]), dtype=np.uint8)
return Image.fromarray(arr, mode="L").convert("RGB")
def noise_quadrant_image(seed=0, size=(256, 256)):
"""Noise only in the top-left quadrant; the rest is flat white."""
img = flat_image(size=size)
noise = noise_image(seed=seed, size=(size[0] // 2, size[1] // 2))
img.paste(noise, (0, 0))
return img
# Real-art-like fixture for the reported false positive: an artwork made of
# full-frame texture so every block (including the center) is content-bearing.
# Two seeds produce mutually distant block hashes (a clean negative) while the
# textured center exercises the center-uninformative geometry path in
# compute_transform_consistency. The flat shared-background pathology is
# covered separately by test_regression_matching_background_unrelated_art.
def realistic_unrelated_artwork(seed=0, size=(256, 256)):
rng = np.random.default_rng(seed)
arr = rng.integers(0, 256, size=(size[1], size[0]), dtype=np.uint8)
return Image.fromarray(arr, mode="L").convert("RGB")
# =====================================================================
# 1. Entropy filtering
# =====================================================================
def test_block_entropy_flat_vs_content():
flat = phash.preprocess_image(flat_image())
noisy = phash.preprocess_image(noise_image())
assert phash.block_entropy(flat) < phash.MIN_BLOCK_STDDEV
assert phash.block_entropy(noisy) >= phash.MIN_BLOCK_STDDEV
def test_generate_block_hashes_tags_entropy():
hashes = phash.generate_hashes(to_stream(noise_image()))
assert hashes is not None
for name, block in hashes["blocks"].items():
assert "entropy" in block, f"block {name} missing entropy tag"
assert isinstance(block["entropy"], float)
# hash algorithm keys must still be present unchanged
for algo in ("phash", "dhash", "whash"):
assert algo in block
def test_entropy_filtering_excludes_flat_blocks():
"""Flat blocks of one image must be excluded from block pairing."""
full_noise = phash.generate_hashes(to_stream(noise_image(seed=1)))
quadrant_noise = phash.generate_hashes(to_stream(noise_quadrant_image(seed=2)))
# quadrant image: only top_left (all noise) and center (partly noise)
# carry content; the other three blocks are flat white. With multi-scale
# blocks the content-bearing keys carry a "scale:" prefix (one per scale).
eligible = phash.blocks_with_content(quadrant_noise["blocks"])
for scale in phash.SCALE_FACTORS:
assert f"{scale}:top_left" in eligible
assert f"{scale}:center" in eligible
assert f"{scale}:top_right" not in eligible
assert f"{scale}:bottom_left" not in eligible
assert f"{scale}:bottom_right" not in eligible
result = phash.compare_blocks(full_noise["blocks"], quadrant_noise["blocks"])
# query side is full noise -> all blocks of every scale eligible
expected_blocks = 5 * len(phash.SCALE_FACTORS)
assert result["content_blocks_used"] == expected_blocks
assert result["low_content_warning"] is False
# Reverse direction: only content-bearing blocks of the query are used
result_rev = phash.compare_blocks(quadrant_noise["blocks"], full_noise["blocks"])
assert result_rev["content_blocks_used"] == len(eligible)
assert result_rev["content_blocks_used"] < expected_blocks
def test_all_flat_falls_back_with_warning():
"""When every block is flat, blocks are still used but warning is set."""
white = phash.generate_hashes(to_stream(flat_image((255, 255, 255))))
grey = phash.generate_hashes(to_stream(flat_image((200, 200, 200))))
assert phash.low_content_warning_for(white) is True
assert phash.low_content_warning_for(phash.generate_hashes(to_stream(noise_image()))) is False
result = phash.compare_blocks(white["blocks"], grey["blocks"])
assert result["low_content_warning"] is True
assert result["similarity"] >= 0 # fallback still produces a score
def test_legacy_hashes_without_entropy_stay_eligible():
"""Old DB rows store no entropy key; their blocks must still be usable."""
legacy_blocks = {
"top_left": {"phash": "0" * 16, "dhash": "0" * 16, "whash": "0" * 16},
"center": {"phash": "f" * 16, "dhash": "f" * 16, "whash": "f" * 16},
}
assert phash.blocks_with_content(legacy_blocks) == ["top_left", "center"]
# =====================================================================
# 2. Consensus scoring vs single-minimum scoring
# =====================================================================
def quadrant_noise_image(seed_tl, seed_tr, seed_bl, seed_br, size=(256, 256)):
"""Four independently-random noise quadrants (all blocks content-bearing)."""
img = Image.new("RGB", size)
half = (size[0] // 2, size[1] // 2)
img.paste(noise_image(seed=seed_tl, size=half), (0, 0))
img.paste(noise_image(seed=seed_tr, size=half), (half[0], 0))
img.paste(noise_image(seed=seed_bl, size=half), (0, half[1]))
img.paste(noise_image(seed=seed_br, size=half), (half[0], half[1]))
return img
def test_identical_images_score_near_100():
h1 = phash.generate_hashes(to_stream(noise_image(seed=7)))
h2 = phash.generate_hashes(to_stream(noise_image(seed=7)))
result = phash.compare_hash_sets(h1, h2)
assert result["block_similarity"] > 95
assert result["transform_similarity"] > 95
assert result["final_similarity"] > 95
assert result["raw_similarity"] == result["final_similarity"]
assert result["raw_similarity_legacy"] > 95
# identical: the winning scale-pair mesh (5 content blocks) all agree
assert result["content_blocks_used"] == 5
assert result["low_content_warning"] is False
def test_consensus_vs_single_minimum_on_coincidental_match():
"""
Image B shares exactly ONE block position (top_left) with image A; everything
else is unrelated noise.
Old method: single best pair out of the cross-comparisons is the identical
block -> ~100% (multiple-comparisons problem, rewards coincidence).
New method: only the top-left blocks (one per scale) agree out of
5 x N scales eligible blocks -> capped around 100 / (5 x N).
"""
img_a = quadrant_noise_image(seed_tl=10, seed_tr=11, seed_bl=12, seed_br=13)
img_b = quadrant_noise_image(seed_tl=10, seed_tr=21, seed_bl=22, seed_br=23)
h1 = phash.generate_hashes(to_stream(img_a))
h2 = phash.generate_hashes(to_stream(img_b))
block_result = phash.compare_blocks(h1["blocks"], h2["blocks"])
# exactly the shared top-left block agrees, at every scale;
# all content blocks (5 per scale) were used
assert block_result["content_blocks_used"] == 5 * len(phash.SCALE_FACTORS)
agreeing = {a["b1"] for a in block_result["agreements"]}
assert agreeing == {f"{s}:top_left" for s in phash.SCALE_FACTORS}
result = phash.compare_hash_sets(h1, h2)
# legacy method still reports a falsely-high score (documents old bug)
assert result["raw_similarity_legacy"] > 70
# consensus method suppresses the single coincidental match
assert result["raw_similarity"] < 40
assert result["raw_similarity"] < result["raw_similarity_legacy"] - 30
def test_unrelated_images_score_low():
h1 = phash.generate_hashes(to_stream(noise_image(seed=31)))
h2 = phash.generate_hashes(to_stream(noise_image(seed=32)))
result = phash.compare_hash_sets(h1, h2)
assert result["raw_similarity"] < 20
# =====================================================================
# 3. Transform/geometric consistency
# =====================================================================
def test_transform_consistency_unit():
identity = [
{"b1": "top_left", "b2": "top_left", "dist": 1},
{"b1": "top_right", "b2": "top_right", "dist": 2},
{"b1": "bottom_left", "b2": "bottom_left", "dist": 3},
]
consistency, dominant = phash.compute_transform_consistency(identity)
assert consistency == 1.0
assert dominant == "0"
mixed = [
{"b1": "top_left", "b2": "top_left", "dist": 1}, # votes "0"
{"b1": "bottom_right", "b2": "top_left", "dist": 1}, # votes "180"
]
consistency, dominant = phash.compute_transform_consistency(mixed)
assert consistency == pytest.approx(0.5)
assert dominant in ("0", "180")
# center matches are geometrically uninformative -> neutral
center_only = [{"b1": "center", "b2": "center", "dist": 0}]
consistency, dominant = phash.compute_transform_consistency(center_only)
assert consistency == 1.0
assert dominant is None
# no agreements AT ALL: no geometric evidence, so consistency reads 0.0
consistency, dominant = phash.compute_transform_consistency([])
assert consistency == 0.0
assert dominant is None
def test_identical_images_have_full_consistency():
h1 = phash.generate_hashes(to_stream(noise_image(seed=41)))
h2 = phash.generate_hashes(to_stream(noise_image(seed=41)))
result = phash.compare_hash_sets(h1, h2)
assert result["transform_consistency"] == 1.0
assert result["dominant_transform"] == "0"
assert result["final_similarity"] > 95
def test_scrambled_geometry_suppresses_score():
"""
Image B contains the same content as image A but with the top-left and
bottom-right quadrants swapped: every block still matches (low raw
distances), but the matches tell a geometrically inconsistent story, so
the confidence multiplier must suppress the final score.
"""
img_a = quadrant_noise_image(seed_tl=50, seed_tr=51, seed_bl=52, seed_br=53)
img_b = quadrant_noise_image(seed_tl=53, seed_tr=51, seed_bl=52, seed_br=50)
h1 = phash.generate_hashes(to_stream(img_a))
h2_same = phash.generate_hashes(to_stream(img_a))
h2_scrambled = phash.generate_hashes(to_stream(img_b))
consistent = phash.compare_hash_sets(h1, h2_same)
scrambled = phash.compare_hash_sets(h1, h2_scrambled)
# swapped corners imply "180", unchanged corners imply "0" -> split votes
assert scrambled["transform_consistency"] == pytest.approx(0.5)
assert scrambled["dominant_transform"] in ("0", "180")
# suppressed well below the geometrically-consistent comparison
assert scrambled["raw_similarity"] < consistent["raw_similarity"] / 2
def test_single_lucky_match_capped_by_evidence():
"""One agreeing block out of five cannot earn full confidence."""
multiplier = phash.confidence_multiplier(
[{"b1": "top_left", "b2": "top_left", "dist": 0}], n_eligible_blocks=5
)
# consistency 1.0 but evidence cap = 1 / min(2, 5) = 0.5
assert multiplier == pytest.approx(0.5)
# Reproduces the production symptom that triggered this fix: two unrelated
# works with a shared flat background and textured content score raw 0 and
# calibrated 0 under the new consensus method (the clean negative the original
# audit reported missing), while the OLD method inflated them. This also guards
# the reporting fix: transform_consistency must be an honest 0.0 when there are
# no agreements, not the misleading default 1.0, and the agreement counts must
# explain the zero.
def test_regression_unrelated_true_negative_shape():
h1 = phash.generate_hashes(to_stream(realistic_unrelated_artwork(seed=11)))
h2 = phash.generate_hashes(to_stream(realistic_unrelated_artwork(seed=2022)))
assert phash.blocks_with_content(h1["blocks"]) == list(h1["blocks"])
assert phash.blocks_with_content(h2["blocks"]) == list(h2["blocks"])
r = phash.compare_hash_sets(h1, h2)
assert r["content_blocks_used"] == 5
assert r["low_content_warning"] is False
assert r["low_content_warning"] is False
assert r["raw_similarity"] == 0
assert r["calibrated_confidence"] == 0
assert r["block_agreements"] == 0
assert r["transform_agreements"] == 0
# THE FIXED FIELD: zero agreements must NOT report perfect consistency
assert r["transform_consistency"] == 0.0
assert r["dominant_transform"] is None
# old method still inflates (documents the previous false positive)
assert not (r["raw_similarity_legacy"] <= 50)
def test_match_fields_expose_agreement_counts():
img = noise_image(seed=77)
h_query = phash.generate_hashes(to_stream(img))
rows = [artwork_row("a", phash.generate_hashes(to_stream(img)))]
results = phash.scan_database(h_query, rows)
assert len(results) == 1
for match in results:
assert "block_agreements" in match
assert "transform_agreements" in match
# identical copy: the winning scale-pair mesh (5 blocks) agrees, all 6 transforms agree
assert results[0]["block_agreements"] == 5
assert results[0]["transform_agreements"] == 6
# =====================================================================
# 4. Calibration score conversion
# =====================================================================
SAMPLE_CALIBRATION = {
"version": 1,
"n_pairs": 1000,
# baseline of unrelated pairs: mostly low scores, long right tail
"mean": 12.0,
"stddev": 6.0,
"percentiles": {
"0": 0.0, "5": 3.0, "25": 7.0, "50": 11.0, "75": 15.0,
"90": 20.0, "95": 24.0, "99": 30.0, "99.9": 38.0, "100": 45.0,
},
"plagiarism_threshold": 30.0,
}
def test_calibrated_confidence_identity_fallback_without_config(monkeypatch):
"""No calibration config -> identity mapping, field always populated."""
monkeypatch.setattr(phash, "CALIBRATION_CONFIG_PATH",
os.path.join(os.path.dirname(__file__), "does_not_exist.json"))
phash.reset_calibration_cache()
try:
assert phash.load_calibration() is None
assert phash.calibrated_confidence(73.5) == pytest.approx(73.5)
assert phash.plagiarism_threshold() is None
finally:
phash.reset_calibration_cache()
def test_calibrated_confidence_percentile_interpolation():
cfg = SAMPLE_CALIBRATION
# exact percentile anchors
assert phash.calibrated_confidence(11.0, calibration=cfg) == pytest.approx(50.0)
assert phash.calibrated_confidence(30.0, calibration=cfg) == pytest.approx(99.0)
# linear interpolation between anchors: halfway between p50(11) and p75(15)
assert phash.calibrated_confidence(13.0, calibration=cfg) == pytest.approx(62.5)
# monotonic
low = phash.calibrated_confidence(5.0, calibration=cfg)
high = phash.calibrated_confidence(25.0, calibration=cfg)
assert low < high
def test_calibrated_confidence_tails_and_clamping():
cfg = SAMPLE_CALIBRATION
# below baseline min -> clamped to >= 0, and never above the min percentile
assert 0.0 <= phash.calibrated_confidence(-10.0, calibration=cfg) <= 0.0
# above baseline max -> extrapolates toward 100 but never exceeds it
top = phash.calibrated_confidence(100.0, calibration=cfg)
assert 99.9 <= top <= 100.0
# scores are clamped into [0, 100] before mapping
assert phash.calibrated_confidence(150.0, calibration=cfg) == top
def test_plagiarism_threshold_from_config():
assert phash.plagiarism_threshold(calibration=SAMPLE_CALIBRATION) == pytest.approx(30.0)
# threshold derived from the 99th percentile of the unrelated baseline
assert (phash.plagiarism_threshold(calibration=SAMPLE_CALIBRATION)
== SAMPLE_CALIBRATION["percentiles"]["99"])
def test_compare_hash_sets_includes_calibrated_fields(monkeypatch):
"""compare_hash_sets must expose both raw scores and calibrated confidence."""
monkeypatch.setattr(phash, "load_calibration", lambda path=None: None)
h1 = phash.generate_hashes(to_stream(noise_image(seed=61)))
h2 = phash.generate_hashes(to_stream(noise_image(seed=61)))
result = phash.compare_hash_sets(h1, h2)
for field in ("raw_similarity", "raw_similarity_legacy", "calibrated_confidence",
"transform_consistency", "content_blocks_used", "low_content_warning",
"calibration_loaded", "background_coincidence_suppressed",
"transform_evidence_status", "block_evidence_status"):
assert field in result
assert result["calibration_loaded"] is False
# identity fallback: calibrated equals raw when uncalibrated
assert result["calibrated_confidence"] == result["raw_similarity"]
# =====================================================================
# 10. Dynamic reweighting of absent evidence channels
# =====================================================================
def hex_block(hex_char):
"""Block entry whose three hashes are all the same repeated hex char."""
return {"phash": hex_char * 16, "dhash": hex_char * 16, "whash": hex_char * 16}
def synthetic_hashset(block_chars, transform_seed=0):
"""Hashset dict with no transform evidence (all transform phashes far
apart from any other synthetic set with a different transform_seed) and
the given per-position blocks."""
rng = np.random.default_rng(transform_seed)
def rand_hex():
return "".join(rng.choice(list("0123456789abcdef"), size=16))
transforms = {str(i): {"phash": rand_hex(),
"dhash": rand_hex(),
"whash": rand_hex()}
for i in range(6)}
positions = ["top_left", "top_right", "bottom_left", "bottom_right", "center"]
blocks = {f"1.0:{p}": hex_block(c) for p, c in zip(positions, block_chars)}
return {"transforms": transforms, "blocks": blocks}
def test_transform_absent_renormalizes_onto_blocks():
"""transform_agreements == 0 means the transform channel structurally
cannot contribute (e.g. a pure crop/zoom). The score must then be
renormalized fully onto the block channel, not capped at 70% of it, and
the response must say so via transform_evidence_status."""
# two of five blocks share content; every transform pair disagrees
h1 = synthetic_hashset(["0", "1", "2", "3", "4"], transform_seed=0)
h2 = synthetic_hashset(["0", "9", "2", "8", "7"], transform_seed=1)
result = phash.compare_hash_sets(h1, h2)
assert result["transform_agreements"] == 0
assert result["transform_similarity"] == 0
assert result["block_agreements"] == 2
assert result["transform_evidence_status"] == "absent"
assert result["block_evidence_status"] == "checked"
# renormalized: raw equals the (multiplied) block score, not 0.7 * it
assert result["raw_similarity"] == result["block_similarity"]
assert result["raw_similarity"] == result["final_similarity"]
def test_block_absent_renormalizes_onto_transforms():
"""Symmetric degenerate case: no content-bearing block mesh at all
(content_blocks_used == 0) renormalizes onto the transform channel."""
h1 = synthetic_hashset(["0", "1", "2", "3", "4"])
h2 = synthetic_hashset(["0", "1", "2", "3", "4"])
h2["blocks"] = {} # no block mesh on the compared side
result = phash.compare_hash_sets(h1, h2)
assert result["content_blocks_used"] == 0
assert result["block_evidence_status"] == "absent"
assert result["transform_evidence_status"] == "checked"
# identical transforms: full transform similarity, renormalized
assert result["raw_similarity"] == result["transform_similarity"]
def test_both_channels_absent_scores_zero():
h1 = synthetic_hashset(["0", "1", "2", "3", "4"], transform_seed=0)
h1["blocks"] = {}
h2 = synthetic_hashset(["0", "1", "2", "3", "4"], transform_seed=2)
h2["blocks"] = {}
result = phash.compare_hash_sets(h1, h2)
assert result["transform_evidence_status"] == "absent"
assert result["block_evidence_status"] == "absent"
assert result["raw_similarity"] == 0
def test_both_channels_checked_keeps_fixed_blend():
"""When both channels have evidence the 0.3/0.7 split must be untouched:
an identical pair has multiplier 1.0 on both sides, so raw must equal
0.3*transform + 0.7*block exactly."""
img = noise_image(seed=303)
h1 = phash.generate_hashes(to_stream(img))
h2 = phash.generate_hashes(to_stream(img))
result = phash.compare_hash_sets(h1, h2)
assert result["transform_agreements"] > 0
assert result["transform_evidence_status"] == "checked"
assert result["block_evidence_status"] == "checked"
expected = round(0.3 * result["transform_similarity"]
+ 0.7 * result["block_similarity"], 2)
assert result["raw_similarity"] == expected
# =====================================================================
# 5. Sparse/minimalist artwork vs exact copy
# =====================================================================
def sparse_art_image():
"""White background with one small black blob fully inside the top-left
quadrant: only ONE block carries content."""
img = flat_image()
ImageDraw.Draw(img).ellipse((16, 16, 56, 56), fill=(0, 0, 0))
return img
def test_sparse_art_exact_copy_not_over_suppressed():
"""
Minimalist art legitimately has only 1-2 content blocks. The consensus
evidence cap must not demand more agreeing blocks than content exists,
so an exact duplicate keeps full multiplier and stays flaggable.
"""
img = sparse_art_image()
h1 = phash.generate_hashes(to_stream(img))
h2 = phash.generate_hashes(to_stream(img))
# one content position at every scale
assert (phash.blocks_with_content(h1["blocks"])
== [f"{s}:top_left" for s in phash.SCALE_FACTORS])
result = phash.compare_hash_sets(h1, h2)
# the winning scale-pair mesh has exactly one eligible (content) block
assert result["content_blocks_used"] == 1
assert result["low_content_warning"] is False
# single content block matches itself: geometric vote is unambiguous
assert result["transform_consistency"] == 1.0
assert result["dominant_transform"] == "0"
# multiplier is NOT capped below 1 despite only one agreeing block
assert phash.confidence_multiplier(
[{"b1": "top_left", "b2": "top_left", "dist": 0.0}],
n_eligible_blocks=1) == pytest.approx(1.0)
# exact duplicate reaches ~100 instead of being suppressed
assert result["final_similarity"] > 95
assert result["background_coincidence_suppressed"] is False
# and it clears the calibrated flagging threshold
threshold = phash.plagiarism_threshold()
if threshold is not None: # only when calibration config is present
assert result["raw_similarity"] >= threshold
# =====================================================================
# 6. Regression: unrelated artworks with matching backgrounds
# =====================================================================
def background_art_a():
"""White background + black circle in the top-left region."""
img = flat_image()
ImageDraw.Draw(img).ellipse((10, 10, 90, 90), fill=(0, 0, 0))
return img
def background_art_b():
"""Same white background + unrelated noise patch at bottom-right."""
rng = np.random.default_rng(77)
patch = Image.fromarray(
rng.integers(0, 256, size=(80, 80), dtype=np.uint8), mode="L"
).convert("RGB")
img = flat_image()
img.paste(patch, (170, 170))
return img
def test_regression_matching_background_unrelated_art():
"""
The original reported bug: two unrelated artworks sharing a similar flat
background were flagged as >70% similar. The legacy algorithm must still
reproduce the false positive (documents the old behavior) while the new
consensus pipeline scores it low.
"""
h1 = phash.generate_hashes(to_stream(background_art_a()))
h2 = phash.generate_hashes(to_stream(background_art_b()))
result = phash.compare_hash_sets(h1, h2)
# old single-minimum method inflates via the shared flat background
assert result["raw_similarity_legacy"] > 70
# new method: no block agreements and the global resemblance is voided
# for lack of block corroboration (background/layout coincidence guard)
assert result["background_coincidence_suppressed"] is True
assert result["raw_similarity"] < 5
assert result["raw_similarity"] < result["raw_similarity_legacy"] - 60
# stays far below the calibrated flagging threshold
threshold = phash.plagiarism_threshold()
if threshold is not None:
assert result["raw_similarity"] < threshold
# =====================================================================
# 8. Regression: crop/zoom of the same artwork (known false negative)
# =====================================================================
def crop_zoom_pair_paths():
root = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
return (os.path.join(root, "image1.png"), os.path.join(root, "image2.png"))
def test_regression_crop_zoom_true_positive():
"""
image2.png is a tighter crop/zoom of image1.png (same character, pose,
palette, star-patch shirt, ocean background; face/top of head cropped out).
A true duplicate must score meaningfully positive.
Multi-scale grid-block matching (SCALE_FACTORS scaled 2x2+center meshes,
evaluated per scale-pair and taking the best) now separates this pair from
the unrelated baseline: raw_similarity ~24 (measured) vs baseline max 0.0
across 78 true multi-scale unrelated pairs, calibrated_confidence 100, and
well above the calibrated flag threshold.
The assertion is deliberately below a literal 30: this fixture is a crop
(not a rotation), so transform evidence is ~0 and, under the UNCHANGED
0.3/0.7 block weighting and unchanged STRICT_MATCH_DISTANCE, the fixture's
structural ceiling is ~24 (2 agreeing blocks x 5-block mesh x 0.7). Pushing
it above 30 requires loosening STRICT_MATCH_DISTANCE or reweighting block
evidence - both out of scope for the multi-scale pass (report tradeoff).
Files live in the repo root; the test skips cleanly if they are not present.
"""
p1, p2 = crop_zoom_pair_paths()
if not (os.path.exists(p1) and os.path.exists(p2)):
pytest.skip("crop/zoom fixture images (image1.png/image2.png) not present")
with open(p1, "rb") as f1, open(p2, "rb") as f2:
h1 = phash.generate_hashes(f1)
h2 = phash.generate_hashes(f2)
result = phash.compare_hash_sets(h1, h2)
# legacy single-minimum still catches this pair (documents the gap)
assert result["raw_similarity_legacy"] > 60
# multi-scale now lands a genuine, meaningfully-positive block score that is
# ~5x the calibrated flag threshold and far above the (zero) related baseline
threshold = phash.plagiarism_threshold()
if threshold is not None:
assert result["raw_similarity"] > threshold * 2
assert result["raw_similarity"] >= threshold
else:
assert result["raw_similarity"] > 15
assert result["block_agreements"] >= 2
assert result["calibrated_confidence"] > 50
# =====================================================================
# 7. Rotation-aware global pre-filter + database scan
# =====================================================================
def artwork_row(art_id, hashes):
return {"id": art_id, "perceptual_hash": hashes,
"c_secure_url": f"https://example.com/art/{art_id}"}
def test_prefilter_keeps_rotated_copy():
img = noise_image(seed=91)
h_orig = phash.generate_hashes(to_stream(img))
h_rotated = phash.generate_hashes(to_stream(img.rotate(90, expand=True)))
# a rotated copy is close to one of the six stored variants -> kept
assert (phash.global_prefilter_distance(h_orig, h_rotated)
<= phash.GLOBAL_PREFILTER_MAX_DISTANCE)
def test_prefilter_handles_missing_payloads():
assert phash.global_prefilter_distance({}, {}) == phash.MAX_DISTANCE
assert (phash.global_prefilter_distance({"transforms": {}}, {"transforms": {}})
== phash.MAX_DISTANCE)
def test_scan_database_prefilter_skips_and_scores(monkeypatch):
"""
With a tight cutoff the pre-filter must skip the obviously-unrelated row
(never scoring it) while the identical and rotated copies pass through
and are scored by the full pipeline. Pre-filter is performance-only: it
never sets the scores of rows that pass.
"""
monkeypatch.setattr(phash, "GLOBAL_PREFILTER_MAX_DISTANCE", 5)
img = noise_image(seed=91)
h_query = phash.generate_hashes(to_stream(img))
rows = [
artwork_row("same", phash.generate_hashes(to_stream(img))),
artwork_row("rotated", phash.generate_hashes(
to_stream(img.rotate(90, expand=True)))),
artwork_row("unrelated", phash.generate_hashes(
to_stream(noise_image(seed=92)))),
]
results = phash.scan_database(h_query, rows)
ids = [m["artwork_id"] for m in results]
# unrelated row triaged away before the full pipeline
assert "unrelated" not in ids
# identical + rotated copies survive triage; identical ranks first
assert ids[0] == "same"
assert "rotated" in ids
best = results[0]
assert best["similarity"] > 95
for match in results:
for field in ("similarity", "raw_similarity", "raw_similarity_legacy",
"calibrated_confidence", "transform_consistency",
"content_blocks_used", "low_content_warning", "url"):
assert field in match
# rotated copy is still detectable through transform consensus
rotated = next(m for m in results if m["artwork_id"] == "rotated")
threshold = phash.plagiarism_threshold()
if threshold is not None:
assert rotated["raw_similarity"] >= threshold
def test_scan_database_scores_all_when_prefilter_lenient():
"""Default cutoff: rows passing triage get full pipeline scores."""
img = noise_image(seed=93)
h_query = phash.generate_hashes(to_stream(img))
rows = [artwork_row("same", phash.generate_hashes(to_stream(img)))]
results = phash.scan_database(h_query, rows)
assert len(results) == 1
assert results[0]["artwork_id"] == "same"
assert results[0]["similarity"] > 95
# =====================================================================
# 9. Multi-scale block matching (generate_multiscale_block_hashes +
# per-scale-pair consensus)
# =====================================================================
def test_multiscale_block_hashes_tag_every_scale():
"""generate_multiscale_block_hashes is independently unit-testable:
each scale's 2x2+center mesh is present, keyed as 'scale:position',
with entropy and the unchanged hash-algorithm keys intact."""
img = phash.preprocess_image(noise_image(seed=101))
blocks = phash.generate_multiscale_block_hashes(img)
scales = {name.split(":", 1)[0] for name in blocks}
assert scales == {f"{s}" for s in phash.SCALE_FACTORS}
positions = {name.split(":", 1)[1] for name in blocks}
assert positions == {"top_left", "top_right", "bottom_left",
"bottom_right", "center"}
# every scale carries the full 5-position mesh
for scale in phash.SCALE_FACTORS:
pos = {name.split(":", 1)[1] for name in blocks
if name.startswith(f"{scale}:")}
assert pos == {"top_left", "top_right", "bottom_left",
"bottom_right", "center"}
# entropy + hash algo keys retained, same as generate_block_hashes
for name, block in blocks.items():
assert "entropy" in block
for algo in ("phash", "dhash", "whash"):
assert algo in block
def test_multiscale_entropy_filtering_works_per_scale():
"""The entropy filter is applied independently at each scale: a
content-bearing region stays eligible at every scale it is cut in, and a
flat region is excluded at every scale."""
quadrant = phash.preprocess_image(noise_quadrant_image(seed=202))
blocks = phash.generate_multiscale_block_hashes(quadrant)
eligible = phash.blocks_with_content(blocks)
for scale in phash.SCALE_FACTORS:
assert f"{scale}:top_left" in eligible
assert f"{scale}:center" in eligible
assert f"{scale}:top_right" not in eligible
assert f"{scale}:bottom_left" not in eligible
assert f"{scale}:bottom_right" not in eligible
def test_multiscale_consensus_takes_best_scale_pair():
"""A single-scale alignment (a zoomed copy aligning with one scaled
version of the other image) must be reported at the winning scale-pair
with a 5-block mesh, not diluted across all scales."""
img = phash.preprocess_image(noise_image(seed=303))
# identical hashes -> every same-scale mesh agrees 5/5
result = phash.compare_multiscale_blocks(
phash.generate_multiscale_block_hashes(img),
phash.generate_multiscale_block_hashes(img),
)
assert result["similarity"] > 95
assert result["content_blocks_used"] == 5
assert result["best_scale_pair"] in [
(f"{s}", f"{s}") for s in phash.SCALE_FACTORS
]
# agreement count reflects the winning mesh, not every scale
assert len(result["agreements"]) == 5
def test_multiscale_rejects_unrelated_pair():
"""Multi-scale must still reject unrelated pairs cleanly despite the
larger block set and the best-scale-pair max over NxN meshes."""
h1 = phash.generate_hashes(to_stream(noise_image(seed=31)))
h2 = phash.generate_hashes(to_stream(noise_image(seed=32)))
result = phash.compare_hash_sets(h1, h2)
assert result["raw_similarity"] == 0
assert result["block_agreements"] == 0
assert result["calibrated_confidence"] == 0
def test_legacy_single_scale_rows_behave_identically():
"""Legacy DB rows store unprefixed single-scale block dicts. They must
be treated as a single implicit scale and produce identical results to
compare_blocks (so old data and the calibration dump stay valid)."""
legacy_a = {
"top_left": {"phash": "0" * 16, "dhash": "0" * 16, "whash": "0" * 16, "entropy": 20.0},
"center": {"phash": "f" * 16, "dhash": "f" * 16, "whash": "f" * 16, "entropy": 20.0},
}
legacy_b = {
"top_left": {"phash": "0" * 16, "dhash": "0" * 16, "whash": "0" * 16, "entropy": 20.0},
"center": {"phash": "0" * 16, "dhash": "0" * 16, "whash": "0" * 16, "entropy": 20.0},
}
old = phash.compare_blocks(legacy_a, legacy_b)
new = phash.compare_multiscale_blocks(legacy_a, legacy_b)
assert old["similarity"] == new["similarity"]
assert old["agreements"] == new["agreements"]
assert new["best_scale_pair"] == ("", "")
# =====================================================================
# Legacy fallback (Option B): zero consensus + strong legacy
# =====================================================================
def _zero_consensus_match(legacy_score):
return {
"similarity": 0,
"final_similarity": 0,
"raw_similarity": 0,
"raw_similarity_legacy": legacy_score,
"calibrated_confidence": 0,
}
def test_legacy_fallback_applies_for_reported_response_shape():
"""The pasted production response (0/0/0 + legacy 62.7-80.23) must arm
the fallback so it drives plagiarism decisions."""
for legacy in (62.7, 80.23):
match = _zero_consensus_match(legacy)
assert phash.legacy_fallback_applies(match) is True
assert phash.effective_score_for_plagiarism(match) == legacy
def test_legacy_fallback_rejects_weak_legacy():
"""A zero-consensus pair with a weak legacy score stays a clean
negative (no fallback) to avoid reintroducing background inflation."""
match = _zero_consensus_match(phash.LEGACY_FALLBACK_MIN_SCORE - 1.0)
assert phash.legacy_fallback_applies(match) is False
assert phash.effective_score_for_plagiarism(match) == 0
def test_legacy_fallback_ignores_nonzero_consensus():
"""A nonzero consensus score never falls back, even with high legacy."""
match = _zero_consensus_match(80.0)
match["similarity"] = 10.0
match["raw_similarity"] = 10.0
assert phash.legacy_fallback_applies(match) is False
assert phash.effective_score_for_plagiarism(match) == 10.0
def test_match_fields_carries_fallback_signal():
"""_match_fields must expose fallback_used/effective_similarity for the
API response without rewriting the stored score fields."""
result = {
"final_similarity": 0.0,
"raw_similarity": 0.0,
"raw_similarity_legacy": 62.7,
"calibrated_confidence": 0.0,
"transform_consistency": 0.0,
"transform_agreements": 0,
"block_agreements": 0,
"content_blocks_used": 5,
"low_content_warning": False,
"transform_evidence_status": "absent",
"block_evidence_status": "checked",
}
fields = phash._match_fields(result)
assert fields["similarity"] == 0.0
assert fields["raw_similarity"] == 0.0
assert fields["raw_similarity_legacy"] == 62.7
assert fields["fallback_used"] is True
assert fields["effective_similarity"] == 62.7
def test_ranking_prefers_strong_legacy_fallback_over_true_zero():
"""Fallback matches must sort above true-zero matches in top-N lists."""
fallback = dict(_zero_consensus_match(80.23))
fallback.update(phash._match_fields({
"final_similarity": 0.0,
"raw_similarity": 0.0,
"raw_similarity_legacy": 80.23,
"calibrated_confidence": 0.0,
"transform_consistency": 0.0,
"transform_agreements": 0,
"block_agreements": 0,
"content_blocks_used": 5,
"low_content_warning": False,
"transform_evidence_status": "absent",
"block_evidence_status": "checked",
}))
clean = dict(_zero_consensus_match(0.0))
clean.update({
"calibrated_confidence": 0.0,
"fallback_used": False,
"effective_similarity": 0.0,
})
ranked = sorted(
[clean, fallback], key=phash._ranking_score, reverse=True
)
assert ranked[0]["raw_similarity_legacy"] == 80.23