Ruzzel Mendoza commited on
Commit
f731132
·
1 Parent(s): 4b85872

Phase 2: consensus-based scoring - replace single-minimum-distance logic in compare_blocks/compare_transforms with per-component best-match consensus: count pairs below tunable STRICT_MATCH_DISTANCE (default 12.0), derive similarity from (agreement ratio, avg distance of agreeing pairs) - expose agreements/agreement_ratio/content_blocks_used in results - retain old algorithm as compare_blocks_legacy/compare_transforms_legacy; compare_hash_sets now returns raw_similarity (new method) and raw_similarity_legacy (old method) side by side for transition-period validation - tests: identical -> ~100, one shared block -> legacy ~90 but consensus capped ~20, unrelated -> low

Browse files
Files changed (2) hide show
  1. lib/phash.py +118 -11
  2. tests/test_phash.py +64 -0
lib/phash.py CHANGED
@@ -30,6 +30,11 @@ def _env_float(name, default):
30
  # threshold are excluded from block matching. Tune against calibration data.
31
  MIN_BLOCK_STDDEV = _env_float("PLAGIARISM_MIN_BLOCK_STDDEV", 5.0)
32
 
 
 
 
 
 
33
 
34
  # -----------------------------
35
  # IMAGE PREPROCESSING
@@ -186,7 +191,61 @@ def weighted_distance(hash1, hash2, weights=None):
186
  return total / weight_sum
187
 
188
 
 
 
 
 
 
 
 
 
 
 
 
 
 
189
  def compare_transforms(hashes1, hashes2):
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
190
  min_dist = float("inf")
191
  for t1 in hashes1:
192
  for t2 in hashes2:
@@ -198,7 +257,7 @@ def compare_transforms(hashes1, hashes2):
198
 
199
  def compare_blocks(blocks1, blocks2):
200
  """
201
- Compare blocks of two hash sets.
202
 
203
  Flat/low-detail blocks (entropy below MIN_BLOCK_STDDEV) are excluded from
204
  pairing because they hash to near-identical "empty" fingerprints
@@ -206,8 +265,16 @@ def compare_blocks(blocks1, blocks2):
206
  of an image is flat, all of its blocks are used as a fallback and
207
  low_content_warning is raised.
208
 
 
 
 
 
 
 
209
  Returns a dict:
210
- similarity 0-100 score (linear, uncalibrated)
 
 
211
  content_blocks_used number of eligible (content-bearing) blocks of the
212
  first image that were used in the comparison
213
  low_content_warning True when at least one image had no content-bearing
@@ -225,35 +292,75 @@ def compare_blocks(blocks1, blocks2):
225
  eligible2 = list(blocks2.keys())
226
  low_content_warning = True
227
 
228
- min_dist = float("inf")
229
  for b1 in eligible1:
 
230
  for b2 in eligible2:
231
  d = weighted_distance(blocks1[b1], blocks2[b2])
232
- if d < min_dist:
233
- min_dist = d
 
 
234
 
235
- if min_dist == float("inf"):
236
- similarity = 0.0
237
- else:
238
- similarity = (1 - min_dist / MAX_DISTANCE) * 100
239
 
240
  return {
241
  "similarity": similarity,
242
- "content_blocks_used": len(eligible1),
 
 
243
  "low_content_warning": low_content_warning,
244
  "eligible_blocks": eligible1,
245
  }
246
 
247
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
248
  def compare_hash_sets(hashset1, hashset2):
249
- transform_sim = compare_transforms(hashset1["transforms"], hashset2["transforms"])
 
 
 
 
 
 
 
 
 
 
 
250
  block_result = compare_blocks(hashset1["blocks"], hashset2["blocks"])
 
 
251
  block_sim = block_result["similarity"]
252
  final_score = 0.3 * transform_sim + 0.7 * block_sim
 
 
 
 
 
 
253
  return {
254
  "transform_similarity": round(transform_sim, 2),
255
  "block_similarity": round(block_sim, 2),
256
  "final_similarity": round(final_score, 2),
 
 
257
  "content_blocks_used": block_result["content_blocks_used"],
258
  "low_content_warning": block_result["low_content_warning"],
259
  }
 
30
  # threshold are excluded from block matching. Tune against calibration data.
31
  MIN_BLOCK_STDDEV = _env_float("PLAGIARISM_MIN_BLOCK_STDDEV", 5.0)
32
 
33
+ # Maximum weighted hash distance (0..MAX_DISTANCE) for a block/transform pair
34
+ # to count as an "agreement" in consensus scoring. Pairs farther apart than
35
+ # this are treated as non-matching instead of dragging the average.
36
+ STRICT_MATCH_DISTANCE = _env_float("PLAGIARISM_STRICT_MATCH_DISTANCE", 12.0)
37
+
38
 
39
  # -----------------------------
40
  # IMAGE PREPROCESSING
 
191
  return total / weight_sum
192
 
193
 
194
+ def _consensus_similarity(agreement_ratio, agreements):
195
+ """
196
+ Derive a 0-100 similarity from (agreement ratio, average distance of the
197
+ agreeing pairs). A single lucky match out of N eligible components can
198
+ contribute at most ~100/N, so coincidence is no longer rewarded.
199
+ """
200
+ if not agreements:
201
+ return 0.0
202
+ avg_dist = sum(a["dist"] for a in agreements) / len(agreements)
203
+ quality = max(0.0, 1.0 - avg_dist / MAX_DISTANCE)
204
+ return 100.0 * agreement_ratio * quality
205
+
206
+
207
  def compare_transforms(hashes1, hashes2):
208
+ """
209
+ Consensus-based whole-image transform comparison.
210
+
211
+ For each transform of image 1 the single best (minimum distance) match
212
+ among image 2's transforms is found. A pair "agrees" when that best
213
+ distance is below STRICT_MATCH_DISTANCE. Similarity derives from how many
214
+ transforms agree and how close the agreeing pairs are - not from the one
215
+ best pair out of 36 cross-comparisons, which rewarded coincidence
216
+ (multiple-comparisons problem).
217
+
218
+ Returns a dict:
219
+ similarity 0-100 consensus score (linear, uncalibrated)
220
+ agreements list of agreeing pairs {t1, t2, dist}
221
+ agreement_ratio fraction of image-1 transforms that agreed
222
+ """
223
+ agreements = []
224
+ for t1, h1 in hashes1.items():
225
+ best_t2, best_dist = None, float("inf")
226
+ for t2, h2 in hashes2.items():
227
+ d = weighted_distance(h1, h2)
228
+ if d < best_dist:
229
+ best_t2, best_dist = t2, d
230
+ if best_dist < STRICT_MATCH_DISTANCE:
231
+ agreements.append({"t1": t1, "t2": best_t2, "dist": best_dist})
232
+
233
+ n = len(hashes1)
234
+ ratio = len(agreements) / n if n else 0.0
235
+ similarity = _consensus_similarity(ratio, agreements)
236
+
237
+ return {
238
+ "similarity": similarity,
239
+ "agreements": agreements,
240
+ "agreement_ratio": ratio,
241
+ }
242
+
243
+
244
+ def compare_transforms_legacy(hashes1, hashes2):
245
+ """
246
+ Old single-minimum-distance transform scoring (kept for before/after
247
+ validation via the raw_similarity_legacy field and offline tooling).
248
+ """
249
  min_dist = float("inf")
250
  for t1 in hashes1:
251
  for t2 in hashes2:
 
257
 
258
  def compare_blocks(blocks1, blocks2):
259
  """
260
+ Consensus-based block comparison with entropy filtering.
261
 
262
  Flat/low-detail blocks (entropy below MIN_BLOCK_STDDEV) are excluded from
263
  pairing because they hash to near-identical "empty" fingerprints
 
265
  of an image is flat, all of its blocks are used as a fallback and
266
  low_content_warning is raised.
267
 
268
+ For each eligible block of image 1 the single best (minimum distance)
269
+ match among image 2's eligible blocks is found; a pair "agrees" when that
270
+ best distance is below STRICT_MATCH_DISTANCE. Similarity derives from the
271
+ agreement ratio and the average distance of agreeing pairs - not from the
272
+ one best pair out of all cross-comparisons (multiple-comparisons problem).
273
+
274
  Returns a dict:
275
+ similarity 0-100 consensus score (linear, uncalibrated)
276
+ agreements list of agreeing pairs {b1, b2, dist}
277
+ agreement_ratio fraction of eligible image-1 blocks that agreed
278
  content_blocks_used number of eligible (content-bearing) blocks of the
279
  first image that were used in the comparison
280
  low_content_warning True when at least one image had no content-bearing
 
292
  eligible2 = list(blocks2.keys())
293
  low_content_warning = True
294
 
295
+ agreements = []
296
  for b1 in eligible1:
297
+ best_b2, best_dist = None, float("inf")
298
  for b2 in eligible2:
299
  d = weighted_distance(blocks1[b1], blocks2[b2])
300
+ if d < best_dist:
301
+ best_b2, best_dist = b2, d
302
+ if best_dist < STRICT_MATCH_DISTANCE:
303
+ agreements.append({"b1": b1, "b2": best_b2, "dist": best_dist})
304
 
305
+ n_eligible = len(eligible1)
306
+ ratio = len(agreements) / n_eligible if n_eligible else 0.0
307
+ similarity = _consensus_similarity(ratio, agreements)
 
308
 
309
  return {
310
  "similarity": similarity,
311
+ "agreements": agreements,
312
+ "agreement_ratio": ratio,
313
+ "content_blocks_used": n_eligible,
314
  "low_content_warning": low_content_warning,
315
  "eligible_blocks": eligible1,
316
  }
317
 
318
 
319
+ def compare_blocks_legacy(blocks1, blocks2):
320
+ """
321
+ Old single-minimum-distance block scoring without entropy filtering (kept
322
+ for before/after validation via the raw_similarity_legacy field and
323
+ offline tooling).
324
+ """
325
+ min_dist = float("inf")
326
+ for b1 in blocks1:
327
+ for b2 in blocks2:
328
+ d = weighted_distance(blocks1[b1], blocks2[b2])
329
+ if d < min_dist:
330
+ min_dist = d
331
+ return (1 - min_dist / MAX_DISTANCE) * 100
332
+
333
+
334
  def compare_hash_sets(hashset1, hashset2):
335
+ """
336
+ Full consensus comparison of two hash sets.
337
+
338
+ Keeps the original field names (transform_similarity, block_similarity,
339
+ final_similarity) and adds:
340
+ raw_similarity new consensus algorithm, linear 0-100, uncalibrated
341
+ (same value as final_similarity)
342
+ raw_similarity_legacy old single-minimum algorithm, linear 0-100 (kept
343
+ during the transition so results can be validated
344
+ before/after; will be removed in a later cleanup)
345
+ """
346
+ transform_result = compare_transforms(hashset1["transforms"], hashset2["transforms"])
347
  block_result = compare_blocks(hashset1["blocks"], hashset2["blocks"])
348
+
349
+ transform_sim = transform_result["similarity"]
350
  block_sim = block_result["similarity"]
351
  final_score = 0.3 * transform_sim + 0.7 * block_sim
352
+
353
+ legacy_score = (
354
+ 0.3 * compare_transforms_legacy(hashset1["transforms"], hashset2["transforms"])
355
+ + 0.7 * compare_blocks_legacy(hashset1["blocks"], hashset2["blocks"])
356
+ )
357
+
358
  return {
359
  "transform_similarity": round(transform_sim, 2),
360
  "block_similarity": round(block_sim, 2),
361
  "final_similarity": round(final_score, 2),
362
+ "raw_similarity": round(final_score, 2),
363
+ "raw_similarity_legacy": round(legacy_score, 2),
364
  "content_blocks_used": block_result["content_blocks_used"],
365
  "low_content_warning": block_result["low_content_warning"],
366
  }
tests/test_phash.py CHANGED
@@ -116,3 +116,67 @@ def test_legacy_hashes_without_entropy_stay_eligible():
116
  "center": {"phash": "f" * 16, "dhash": "f" * 16, "whash": "f" * 16},
117
  }
118
  assert phash.blocks_with_content(legacy_blocks) == ["top_left", "center"]
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
116
  "center": {"phash": "f" * 16, "dhash": "f" * 16, "whash": "f" * 16},
117
  }
118
  assert phash.blocks_with_content(legacy_blocks) == ["top_left", "center"]
119
+
120
+
121
+ # =====================================================================
122
+ # 2. Consensus scoring vs single-minimum scoring
123
+ # =====================================================================
124
+ def quadrant_noise_image(seed_tl, seed_tr, seed_bl, seed_br, size=(256, 256)):
125
+ """Four independently-random noise quadrants (all blocks content-bearing)."""
126
+ img = Image.new("RGB", size)
127
+ half = (size[0] // 2, size[1] // 2)
128
+ img.paste(noise_image(seed=seed_tl, size=half), (0, 0))
129
+ img.paste(noise_image(seed=seed_tr, size=half), (half[0], 0))
130
+ img.paste(noise_image(seed=seed_bl, size=half), (0, half[1]))
131
+ img.paste(noise_image(seed=seed_br, size=half), (half[0], half[1]))
132
+ return img
133
+
134
+
135
+ def test_identical_images_score_near_100():
136
+ h1 = phash.generate_hashes(to_stream(noise_image(seed=7)))
137
+ h2 = phash.generate_hashes(to_stream(noise_image(seed=7)))
138
+ result = phash.compare_hash_sets(h1, h2)
139
+ assert result["block_similarity"] > 95
140
+ assert result["transform_similarity"] > 95
141
+ assert result["final_similarity"] > 95
142
+ assert result["raw_similarity"] == result["final_similarity"]
143
+ assert result["raw_similarity_legacy"] > 95
144
+ assert result["content_blocks_used"] == 5
145
+ assert result["low_content_warning"] is False
146
+
147
+
148
+ def test_consensus_vs_single_minimum_on_coincidental_match():
149
+ """
150
+ Image B shares exactly ONE block (top_left) with image A; everything else
151
+ is unrelated noise.
152
+
153
+ Old method: single best pair out of 25 cross-comparisons is the identical
154
+ block -> ~100% (multiple-comparisons problem, rewards coincidence).
155
+ New method: only 1 of 5 eligible blocks agrees -> capped around 100/5.
156
+ """
157
+ img_a = quadrant_noise_image(seed_tl=10, seed_tr=11, seed_bl=12, seed_br=13)
158
+ img_b = quadrant_noise_image(seed_tl=10, seed_tr=21, seed_bl=22, seed_br=23)
159
+
160
+ h1 = phash.generate_hashes(to_stream(img_a))
161
+ h2 = phash.generate_hashes(to_stream(img_b))
162
+
163
+ block_result = phash.compare_blocks(h1["blocks"], h2["blocks"])
164
+ # exactly the shared top-left block agrees; all content blocks were used
165
+ assert block_result["content_blocks_used"] == 5
166
+ agreeing = {a["b1"] for a in block_result["agreements"]}
167
+ assert agreeing == {"top_left"}
168
+
169
+ result = phash.compare_hash_sets(h1, h2)
170
+ # legacy method still reports a falsely-high score (documents old bug)
171
+ assert result["raw_similarity_legacy"] > 70
172
+ # consensus method suppresses the single coincidental match
173
+ assert result["raw_similarity"] < 40
174
+ assert result["raw_similarity"] < result["raw_similarity_legacy"] - 30
175
+
176
+
177
+ def test_unrelated_images_score_low():
178
+ h1 = phash.generate_hashes(to_stream(noise_image(seed=31)))
179
+ h2 = phash.generate_hashes(to_stream(noise_image(seed=32)))
180
+ result = phash.compare_hash_sets(h1, h2)
181
+ assert result["raw_similarity"] < 20
182
+