""" 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