Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
71 changes: 71 additions & 0 deletions plugins/image-matcher/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,71 @@
# Image Matcher

A Stash UI plugin that finds images that look the same and lets you act on them:

- **Merge**: the look-alikes become one image in Stash. Every file stays where it is on disk, the better copy is the one shown, and the image appears in each folder's gallery.
- **Delete**: keep one copy, delete the others from disk. Their tags, ratings and details move to the kept copy first.
- **Folder sets**: when two folders share several look-alikes ("the same set in two places"), merge or dedupe the whole pair in one decision, and choose which folder wins.
Each set card says how close its pairs are ("25 same hash · 9 within 2 bits") and *Show all* lists every pair with its distance, furthest first. The hash describes how a picture looks; files with the same hash can still differ in size or quality.
- **Leave out**: any pair on a set card, or any image in a group, can be left out of a merge or delete. A group with two pictures in each folder is shown as two pairs, never merged into one image.
- **One detail different**: the page compares the two thumbnails of every pair. A resized or recompressed copy differs a little everywhere; two drawings that differ in one detail differ a lot in one place. Those are marked "differs in one area" with a red box on the spot and are left out until you put them back. A very small or faint change can still pass.
- **All on this page**: under the list on the Images tab, one button merges (or deletes the other copies in) every group on the page, as the cards are set.
- **Colour**: a black-and-white copy matches its colour original (the hash only sees brightness). The colour copy is the suggested keeper unless the black-and-white one has more than twice the pixels; folder rules still come first.
- **Zoom**: a slider in the toolbar enlarges every thumbnail up to 4×; the size is remembered in the browser.
- **Folders left out of sets**: list folders (one per line, under *Folder rules*) that should never be compared as a set, such as a year folder of loose images; or use *Leave this folder out of sets* on a card. Subfolders are still compared unless the line ends in `/*`.
- **Archives**: images inside a cbz or zip are left out and counted on the page. A file in an archive cannot be deleted or re-attached on its own, so neither merge nor delete can work on it.
- **Guide**: *How this works* on the page explains the tabs, the buttons, the labels and what is left out. It is open on a first visit. A set card whose folders mostly do not match carries a caution.
- **Folder rules**: an ordered list of folders that always win. Stored in Stash's plugin settings.

It opens from the stacked-squares button in the top bar, or at `/image-matcher`.

## Requirements

- Stash 0.31 or later (image perceptual hashes arrived in 0.31.0).
- Image phashes generated: Settings → Tasks → Generate → *Image perceptual hashes*. Images without one are skipped and counted on the page.

## Install

Install from the CommunityScripts source in Settings → Plugins → Available Plugins, or copy this folder into Stash's `plugins/` directory and press *Reload plugins*.

## How merge works

Stash has no "merge images" call, and this plugin does not write to the database or assume anything about the filesystem. It uses Stash's own scanner:

1. Both files get the same custom fingerprint (type `imagematch`) through `fileSetFingerprints`.
2. The lesser image's tags, performers, rating, details, URLs and hand-made gallery memberships are copied to the kept image.
3. The lesser image record is removed with its file kept (`imagesDestroy`, `delete_file: false`).
4. That file is rescanned. Stash's scanner attaches a file with no image to any image sharing a fingerprint, so it joins the kept image.
5. The plugin checks that the file landed on exactly the kept image.

The scanner matches on *any* shared fingerprint, including phash, so a detached file would also attach to every other look-alike with an equal phash. The plugin therefore hides the file's phash during the rescan and restores it afterwards.

Real content hashes (md5, oshash) are never touched. The `imagematch` stamp stays as the record that a person declared the files the same.

## Limits

- One merge or delete runs at a time; the other cards are locked until it finishes.
- Deleting an image deletes every file it holds. A copy that holds several files (one that was merged) lists every folder they are in, and the delete warning names those folders and gives the true file count.
- Stash deletes a file by first renaming it to `<name>.delete` ([stashapp/stash#3664](https://github.com/stashapp/stash/issues/3664)), so a file whose name is over 248 bytes cannot be deleted. Delete leaves those copies alone and labels them; merge them instead.
- **No undo.** Stash has no "split image" call. A merge can only be reversed by hand; a delete cannot be reversed at all.
- Matching uses the phash Stash already stores. It finds resized and recompressed copies well; crops, rotations and mirrors mostly not.
- Groups are chains: if A looks like B and B looks like C, all three are shown together even when A and C are further apart.
- Folder and zip galleries cannot be edited in Stash, so "merging galleries" means their details (tags, performers, rating, and so on) are synced; their contents converge because the merged images belong to both folders.
- Very loose accuracy on very large libraries is slow. At *High* a 200,000-image library compares in well under a second; at *Low* a 34,000-image library takes about a third of a second on a desktop.
- `custom_fields` are not merged.

## How it was tested

- Unit tests of the matching and decision logic (18), end-to-end tests of merge, delete and folder sets against a throwaway Stash in Docker (13), and a scripted browser pass. All three pass on Stash v0.31.1 (release) and v0.32.0-12 (development image).
- Used by its author on a real library.
- The test files are kept with the development copy, not shipped here, so they are not installed with the plugin. They can be added to this folder if that is preferred.

## Prior art and credit

- The interface follows the closed Stash PR #6675 (image duplicate checker) and the scene duplicate checker in spirit; no code was copied.
- The merge-on-resolve rules (highest rating, union of tags, combined details, merge only when exactly one copy is kept) follow Immich's duplicates utility.
- "Folders that win" is the reference-folder idea from dupeGuru.
- The task-computes / page-displays split in RyanAtNight's DuplicateScorer informed the layout, though here everything runs in the page.

## License

AGPL-3.0-or-later, compatible with this repository's AGPL-3.0 licence.
82 changes: 82 additions & 0 deletions plugins/image-matcher/image-matcher.css
Original file line number Diff line number Diff line change
@@ -0,0 +1,82 @@
.imt-page { --imt-zoom: 1; max-width: 1100px; margin: 0 auto; padding: 1rem; }
.imt-zoom { margin-left: auto !important; }
.imt-zoom input { width: 9rem; }
.imt-muted { opacity: 0.7; font-size: 0.875rem; }
.imt-toolbar { display: flex; flex-wrap: wrap; align-items: center; gap: 0.75rem; margin: 1rem 0; }
.imt-toolbar label { display: flex; align-items: center; gap: 0.5rem; margin: 0; }
.imt-toolbar select { width: auto; }
.imt-summary { margin: 0.5rem 0; }
.imt-tabs { display: flex; gap: 0.5rem; margin: 0.75rem 0 1rem; }
.imt-card { padding: 1rem; margin-bottom: 1rem; }
.imt-message { padding: 0.5rem 0.75rem; margin: 0.5rem 0; border-left: 3px solid #4caf50; background: rgba(76, 175, 80, 0.12); }
.imt-toast { position: fixed; z-index: 1050; left: 50%; bottom: calc(1rem + env(safe-area-inset-bottom, 0px)); transform: translateX(-50%); width: min(40rem, calc(100vw - 2rem));
display: flex; align-items: flex-start; gap: 0.25rem; border-radius: 4px; background: #202b33; box-shadow: 0 4px 16px rgba(0, 0, 0, 0.6); }
.imt-toast .imt-message { flex: 1; margin: 0; background: rgba(76, 175, 80, 0.18); }
.imt-toast-close { font-size: 1.25rem; line-height: 1; padding: 0.4rem 0.6rem; }
.imt-folders div:first-child { opacity: 0.7; }
.imt-error { padding: 0.5rem 0.75rem; margin: 0.5rem 0; border-left: 3px solid #db3737; background: rgba(219, 55, 55, 0.12); word-break: break-word; }
.imt-busy { display: flex; align-items: center; gap: 0.5rem; padding: 0.5rem 0; }
.imt-spinner { width: 1rem; height: 1rem; border: 2px solid currentColor; border-right-color: transparent; border-radius: 50%; animation: imt-spin 0.8s linear infinite; }
@keyframes imt-spin { to { transform: rotate(360deg); } }

.imt-tiles { display: grid; grid-template-columns: repeat(auto-fill, minmax(min(100%, calc(170px * var(--imt-zoom))), 1fr)); gap: 0.75rem; margin-bottom: 0.75rem; }
.imt-tile { display: flex; flex-direction: column; gap: 0.4rem; padding: 0.5rem; border: 2px solid transparent; border-radius: 4px; background: rgba(0, 0, 0, 0.15); }
.imt-tile.imt-keep, .imt-side.imt-keep { border-color: #4caf50; }
.imt-thumb { display: flex; align-items: center; justify-content: center; container-type: size; height: calc(150px * var(--imt-zoom)); background: rgba(0, 0, 0, 0.3); border-radius: 3px; overflow: hidden; }
.imt-fit { position: relative; display: block; width: min(100cqw, calc(100cqh * var(--imt-ar))); height: min(100cqh, calc(100cqw / var(--imt-ar))); }
.imt-fit img { display: block; width: 100%; height: 100%; object-fit: contain; }
.imt-spot { position: absolute; box-sizing: border-box; border: 2px solid #ff5252; border-radius: 3px; box-shadow: 0 0 0 1px rgba(0, 0, 0, 0.7); pointer-events: none; }
.imt-diff { font-size: 0.8rem; color: #ff8a80; }
.imt-long { font-size: 0.8rem; color: #ffb74d; }
.imt-pair-dist.imt-diff { opacity: 1; font-size: 0.75rem; }
.imt-out .imt-pair-dist.imt-diff, .imt-out .imt-diff { text-decoration: none; opacity: 1; }
.imt-thumb-sm { height: calc(72px * var(--imt-zoom)); width: calc(96px * var(--imt-zoom)); max-width: 100%; }
.imt-pair { max-width: 100%; }
.imt-facts { font-size: 0.875rem; line-height: 1.35; }
.imt-path { font-size: 0.8rem; word-break: break-all; }
.imt-badge { align-self: flex-start; padding: 0.1rem 0.5rem; border-radius: 3px; font-size: 0.8rem; background: #4caf50; color: #fff; }

.imt-sides { display: grid; grid-template-columns: repeat(auto-fit, minmax(260px, 1fr)); gap: 0.75rem; margin-bottom: 0.75rem; }
.imt-side { display: flex; align-items: flex-start; gap: 0.6rem; margin: 0; padding: 0.6rem; border: 2px solid transparent; border-radius: 4px; background: rgba(0, 0, 0, 0.15); cursor: pointer; }
.imt-side input { margin-top: 0.25rem; }
.imt-side .imt-badge { display: inline-block; margin-top: 0.3rem; }
.imt-pairs { display: flex; flex-wrap: wrap; align-items: center; gap: 0.5rem; margin-bottom: 0.75rem; }
.imt-pair { display: flex; flex-direction: column; gap: 2px; }
.imt-pair-row { display: flex; gap: 2px; }
.imt-more { padding: 0 0.5rem; }
.imt-pair-dist { font-size: 0.75rem; opacity: 0.7; text-align: center; }
.imt-out .imt-thumb img { opacity: 0.6; }
.imt-out .imt-pair-dist, .imt-out .imt-facts { text-decoration: line-through; opacity: 0.5; }
.imt-pair-out { padding: 0; font-size: 0.75rem; }
.imt-tile-btns { display: flex; flex-wrap: wrap; align-items: center; gap: 0.25rem; }
.imt-pair-dist.imt-pair-off { opacity: 1; color: #ffb74d; }
.imt-mix { font-size: 0.875rem; margin-bottom: 0.75rem; }

.imt-skip { display: block; padding: 0; font-size: 0.75rem; }
.imt-rules h5 { margin-top: 0.75rem; }
.imt-found { max-height: 16rem; overflow-y: auto; margin-bottom: 0.6rem; padding: 0.25rem 0.5rem; background: rgba(0, 0, 0, 0.15); border-radius: 4px; }
.imt-found-row { display: flex; align-items: baseline; gap: 0.5rem; margin: 0; padding: 0.15rem 0; cursor: pointer; }
.imt-found-row .imt-muted { margin-left: auto; white-space: nowrap; }
.imt-help h5 { margin: 0.75rem 0 0.25rem; font-size: 1rem; }
.imt-help h5:first-child { margin-top: 0; }
.imt-help ul { margin: 0 0 0.25rem; padding-left: 1.2rem; }
.imt-help li { margin-bottom: 0.2rem; font-size: 0.9rem; line-height: 1.4; }
.imt-help-link { padding: 0; vertical-align: baseline; font-size: inherit; }
.imt-caution { padding: 0.5rem 0.75rem; margin-bottom: 0.75rem; border-left: 3px solid #ffb74d; background: rgba(255, 183, 77, 0.12); font-size: 0.875rem; }
.imt-bulk { border: 1px solid rgba(255, 255, 255, 0.25); }
.imt-actions { display: flex; flex-wrap: wrap; align-items: center; gap: 0.5rem; }
.imt-remember { margin: 0 0 0 auto; font-size: 0.875rem; cursor: pointer; }
.imt-confirm { padding: 0.75rem; border: 1px solid #db3737; border-radius: 4px; }
.imt-confirm p { margin: 0 0 0.6rem; }
.imt-confirm .btn { margin-right: 0.5rem; }
.imt-rules textarea { font-family: monospace; margin-bottom: 0.6rem; }
.imt-pager { display: flex; align-items: center; justify-content: center; gap: 1rem; margin: 1rem 0; }

@media (max-width: 576px) {
.imt-page { padding: 0.5rem; }
.imt-tiles { grid-template-columns: repeat(auto-fill, minmax(min(100%, calc(150px * var(--imt-zoom))), 1fr)); }
.imt-thumb { height: calc(120px * var(--imt-zoom)); }
.imt-zoom { margin-left: 0 !important; }
.imt-remember { margin-left: 0; }
.imt-toast { bottom: calc(4.5rem + env(safe-area-inset-bottom, 0px)); }
}
11 changes: 11 additions & 0 deletions plugins/image-matcher/image-matcher.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,11 @@
name: Image Matcher
description: Finds images that look the same (perceptual hash). Merge them into one image with every file kept, or delete the lesser copies, one group or one folder pair at a time.
version: 0.11.0
url: https://github.com/stashapp/CommunityScripts/tree/main/plugins/image-matcher
ui:
javascript:
- imcore.js
- imops.js
- imui.js
css:
- image-matcher.css
Loading
Loading