Flip through folders of plots, side by side.

image-comparator shows matching plots from several folders in one grid. Press ↓ and every panel moves to the next sample at the same time.

pipx install image-comparator
Setup instructions · PyPI · Source on GitHub
Image Comparator
A 2 by 2 grid of a QC histogram, a gene expression bar chart, a UMAP and a spatial heatmap, stepping through samples 1 to 5 together.
Four plot types for the same sample, stepping through samples together. Each plot's title shows its file and position.

The problem it solves

An analysis pipeline often writes one plot per sample into a separate folder for each plot type. Reviewing them means opening qc_plots/sample_07.png, then umap_plots/sample_07.pdf, then spatial_plots/sample_07.jpg, and doing it all again for sample 8. image-comparator puts each folder in its own panel and keeps the panels on the same sample while you step through with the arrow keys.

Files are matched by their position in each folder after sorting by name, so name plots by sample (the plot type is already in the folder name). PNG, JPEG, TIFF, BMP, GIF and PDF are supported, and can be mixed.

Use cases

Any time you have the same set of things plotted several ways, or the same plots produced several times.

QC next to results

Check each sample's quality metrics alongside its downstream analysis, so a strange cluster can be traced back to a poor-quality sample.

qc_plots/
umap_plots/
spatial_plots/

Before and after a change

Compare figures from two versions of a pipeline, or before and after a parameter change, to see which samples it actually affected.

results_v1/figures/
results_v2/figures/

Parameter sweeps and model runs

Put the same diagnostic plot from several runs (settings, seeds, checkpoints) in one grid and scan through every input.

run_lr0.01/plots/
run_lr0.001/plots/
run_lr0.0001/plots/

Reviewing many figures fast

Hundreds of samples to check by eye? Lay out the plot types you need, then hold ↓. Upcoming PDFs are rendered in the background so each step is quick.

sample_001 … sample_480

A walk through the tool

What each part of the app is for, and when you'd reach for it. All screenshots are produced by the app from the example data in the repository's sample_data/ folder.

1 · Start window

Pick a starting plot from each folder

Click Add Files and choose one plot from each folder you want to compare. The app finds every other plot in those folders, sorts them, and starts at the plots you picked.

  • Move Up / Move Down set the order of the panels in the grid (left to right, then top to bottom).
  • Number of columns sets the grid shape, e.g. 4 folders as 2×2 or 4×1.
  • Comparator starting index jumps straight to, say, sample 40 instead of starting at the plots you picked.
When to use it: every session starts here. Pick the files of a sample you're curious about to open the viewer right on it.
Image Comparator Configuration
The start window, listing four selected plot files, with starting index, layout and directory synchronization sections.
2 · Navigation

Step through samples together

↓ shows the next sample in every panel, ↑ the previous one. The window title shows where you are (e.g. Index 4/12), and each panel's title shows its file name and position in its folder.

The PDFs for the next and previous steps are rendered in the background while you look at the current one, so navigating stays fast even with heavy PDFs.

When to use it: this is the main loop. Panel sizes and the grid stay the same as you move, so your eye can go to the same spot in every plot.

You point it at

qc_plots/          umap_plots/
├── sample_01.png  ├── sample_01.pdf
├── sample_02.png  ├── sample_02.pdf
└── sample_03.png  └── sample_03.pdf

And step through

PressLeft panelRight panel
startsample_01.pngsample_01.pdf
↓sample_02.pngsample_02.pdf
↓sample_03.pngsample_03.pdf
3 · Directory synchronization

Keep folders in step when samples are missing

Because files are matched by position, a folder with a missing sample shifts everything after it. In the Out of sync view, the middle panel shows sample_03 while the others have already moved on to sample_04.

  • Check Sync Status lists, for each folder, the samples missing from it and any sample saved twice with different extensions. Nothing is changed.
  • Sync Directories Now creates a clearly labelled “Plot Not Found” placeholder for every missing sample, so all folders line up again.
When to use it: whenever some samples failed a step of the pipeline, or a plot type only exists for some samples. Files are matched by name without extension, so sample_02.png and sample_02.pdf count as the same sample.
Image Comparator (Index 3)
Three panels showing samples 4, 3 and 4: the folders have drifted out of step.
4 · Resizing panels

Give each plot the space it needs

Plots don't all share a shape. A genome coverage track is very wide, a dot plot of 60 genes is very tall, and a legend needs hardly any room. Drag the gap between two panels to move the boundary between them.

  • Gaps you can drag are marked with thin gray lines, which turn blue under the mouse.
  • Each row's columns are resized independently, and rows can be resized too.
  • E makes all panels equal again. Sizes are kept as you navigate.
When to use it: when an unusually wide or tall plot is shrunk to a sliver in an equal grid. In the example, the coverage track gets more width and the tall dot plot gives up width it can't use.
Image Comparator (Index 1/12)
The same grid after resizing: the wide plot spans most of the top row and the tall plot has a narrow column.
5 · Zoom and pan

Look closely, and stay sharp

Press O and drag a rectangle to zoom into a plot, or P to drag it around. H resets every panel, and D returns to resizing mode.

PDFs are vector graphics, so when you zoom into one, the visible region is re-rendered at screen resolution a moment after you stop. Small text, thin lines and overlapping points stay crisp at any zoom.

When to use it: dense scatter plots, small axis labels, or checking whether two clusters really overlap. Zoom is kept per panel, and is reset when you move to the next sample.
UMAP PDF, zoomed in 6×
The same region re-rendered: points and grid lines are sharp.

Keyboard shortcuts

In the plot window. The toolbar buttons at the bottom of the window do the same as O, P and H.

KeyAction
↓ / ↑Next / previous sample in every panel
DDefault mode: drag the gaps between panels to resize them
OToggle zoom mode: drag a rectangle to zoom in
PToggle pan mode: drag to pan, right-drag to zoom
HReset zoom and pan of all panels
EMake all panels equally sized again
Q / EscQuit

Install

image-comparator is a desktop app for macOS, Linux and Windows. It needs Python 3.10 or newer with tkinter. pipx installs it as a standalone command.

  1. Install pipx (and tkinter)

    macOS (Homebrew)
    brew install pipx python-tk
    Ubuntu / Debian
    sudo apt install pipx python3-tk
    Windows
    py -m pip install --user pipx

    Homebrew's and Debian's Python come without tkinter, which the app's windows are built with; python-tk / python3-tk add it.

  2. Install image-comparator

    pipx install image-comparator
pipx ensurepath   # makes the command available; restart your terminal afterwards

    No Python 3.10+ on your system? pipx install image-comparator --python 3.13 --fetch-python=missing downloads a standalone Python first.

  3. Run it

    image-comparator

    To try it out, clone the repository and open plots from sample_data/complete/, or sample_data/with_gaps/ to try directory sync.