|
| 1 | +Perceptual-Hash Image Dedupe |
| 2 | +============================ |
| 3 | + |
| 4 | +A screen recording or a step report often contains many nearly identical frames. |
| 5 | +Perceptual hashes (average-hash and difference-hash) map visually similar images |
| 6 | +to numerically close fingerprints, so frames can be clustered by Hamming distance |
| 7 | +and collapsed — keeping one representative per distinct view. |
| 8 | + |
| 9 | +The hashing functions use **Pillow** (already a core dependency — no extra |
| 10 | +package required); the dedupe/compare logic is pure Python and the ``hasher`` is |
| 11 | +injectable, so clustering is unit-testable without any image. Imports no |
| 12 | +``PySide6``. |
| 13 | + |
| 14 | +Headless API |
| 15 | +------------ |
| 16 | + |
| 17 | +.. code-block:: python |
| 18 | +
|
| 19 | + from je_auto_control import ( |
| 20 | + average_hash, dhash, hamming_distance, images_similar, dedupe_images) |
| 21 | +
|
| 22 | + h1 = average_hash("frame1.png") # hex fingerprint |
| 23 | + h2 = average_hash("frame2.png") |
| 24 | + hamming_distance(h1, h2) # bits that differ |
| 25 | + images_similar(h1, h2, max_distance=5) # within tolerance? |
| 26 | +
|
| 27 | + dedupe_images(["a.png", "b.png", "c.png"], max_distance=5) |
| 28 | + # -> keeps one image per near-duplicate cluster (first wins) |
| 29 | +
|
| 30 | +``average_hash`` compares each pixel to the mean brightness; ``dhash`` compares |
| 31 | +each pixel to its right neighbour (more robust to gamma shifts). ``dedupe_images`` |
| 32 | +accepts a ``hasher`` hook (defaulting to ``average_hash``) so the clustering can |
| 33 | +be tested with precomputed hashes. |
| 34 | + |
| 35 | +Executor commands |
| 36 | +----------------- |
| 37 | + |
| 38 | +================================ =================================================== |
| 39 | +Command Effect |
| 40 | +================================ =================================================== |
| 41 | +``AC_image_hash`` ``{hash}`` of an image (``algo``: average/dhash). |
| 42 | +``AC_dedupe_images`` ``{unique}`` with near-duplicate images collapsed. |
| 43 | +================================ =================================================== |
| 44 | + |
| 45 | +``paths`` accepts a list or a JSON-string list (so the visual builder works). The |
| 46 | +same operations are exposed as MCP tools (``ac_image_hash`` / ``ac_dedupe_images``) |
| 47 | +and as Script Builder commands under **Image**. |
0 commit comments