image-comparator

Compare sets of images side by side with keyboard navigation.

About

image-comparator is a desktop application for viewing multiple sets of plot or image files side by side and navigating through them synchronously with the keyboard.

It is useful when you have several versions or types of plots for the same datapoint. For example, different types of plots for the same biological sample, maybe showing some qc results and downstream analysis results for the same sample.

Load one or more directories of images, then use the arrow keys to move through the files. Each panel advances to the corresponding next image at the same time, making visual comparison fast and convenient.

How it works

You select the starting plot files, and the application infers all the plots in their respective directories, sorts them in ascending order, and accordingly obtains the index of each of the plots you chose in their respective directories. Then, in the visualizer mode, as you scroll up and down using arrow keys, all the plots switch to the next (down arrow) or previous (up arrow) plot simultaneously.

For reliable synchronized navigation, images should be named consistently across directories as the application sorts files alphabetically before displaying them. One reasonable approach is to have all the plot files named according to the identifier for a datapoint, and the parent directory indicating what type of plots are held in it.

For example, if you have two directories:

expression_plots/
├── sample_A.png
├── sample_B.png
└── sample_C.png

segmentation_plots/
├── sample_A.png
├── sample_B.png
└── sample_C.png

In this case, navigating forward will show something like this:

Position	Expression panel	Segmentation panel
1	sample_A.png	sample_A.png
2	sample_B.png	sample_B.png
3	sample_C.png	sample_C.png

Syncing directories

Sometimes you may not have plots corresponding to all the samples in each directory you want to navigate through. In this case, as you scroll through the directories in the visualizer mode, the plots may get out of sync. If you adopt the strategy of naming all the plot files with just the identifier of the datapoint, then we can simply have placeholder files for the missing datapoints in each directory, so that upon scrolling, we dont get out of sync. To do this, after you have selected the initial plots, simply press "Sync Direcories Now" button. This will create placeholder files in the directories of the selected plots for whichever datapoints were missing compared to the union of all the datapoints in the chosen plots' directories. Filenames are compared without their extensions, so sample_A.png and sample_A.pdf count as the same datapoint, and each placeholder takes the most common extension in its directory.

To see whether the directories are in sync without creating any files, press the "Check Sync Status" button. It reports, for each directory of the selected plots:

• Missing datapoints — filenames present in other directories but not in this one. These can be filled with placeholders using "Sync Directories Now".
• Duplicate datapoints — the same filename appearing more than once with different extensions (e.g. sample_A.png and sample_A.pdf). These shift that directory out of step during navigation and must be resolved manually, as syncing does not remove files.

Installation

• Ensure that pipx is installed. Depending on your platform, run one of the following in terminal:

  • macOS (python-tk adds tkinter, which Homebrew's Python doesn't include)

     brew install pipx python-tk
    

  • Windows

     py -m pip install --user pipx
    

  • Ubuntu/Debian

     sudo apt install pipx python3-tk
    

• Install image-comparator using pipx (requires Python 3.10 or newer):

   pipx install image-comparator
  

  • If you don't have Python 3.10 or newer, this command installs a standalone Python automatically (it may take a few minutes to complete):

     pipx install image-comparator --python 3.13 --fetch-python=missing
    

• To ensure that the .local/bin path is in your PATH env variable, run:

   pipx ensurepath
  

• Restart your terminal for the changes to take effect.

• Now you can simply use the tool by running:

   image-comparator
  

Getting started

When the application opens, configure the files and layout before starting the comparator:

1. Add files or directories

Click Add Files and select the plot files or collections you want to compare.

Use the list controls to organize your selection:

• Add Files — add plot files or image collections
• Remove Selected — remove the currently selected entry
• Clear All — remove every selected entry
• Move Up / Move Down — reorder selected entries in the comparison layout

The order of selected entries determines the order in which plot collections appear in the comparator.

2. Choose the grid layout

Set Number of columns in plot grid to control the number of plot panels shown in each row.

The application automatically arranges the selected collections in a row-major order into the grid.

3. Start comparing

Click Start Comparator.

The image-viewing window will open with the first files from each selected collection displayed together.

Use the keyboard arrow keys to navigate:

• Down Arrow — move forward to the next set of plots
• Up Arrow — move backward to the previous set of plots

All displayed plot collections move together, allowing you to compare corresponding samples or images efficiently.

PDF plots are rendered to fit their panel on screen, at twice the panel's size so that enlarging panels stays sharp (zooming in re-renders the visible region, see Viewer modes). To keep navigation fast, the PDFs of the next and previous steps are rendered in the background while you view the current one, and recently viewed ones are kept in memory. Very complex PDFs (e.g. scatter plots with hundreds of thousands of points) can still take a moment if you navigate faster than they can be rendered.

Resizing panels

Not every plot collection needs the same amount of space — for example, a collection of legends can be given less room than the spatial plots next to it. To resize panels, drag the gaps between them with the mouse. Draggable gaps are marked with thin gray lines, which turn blue when hovered (the cursor also changes to a resize arrow):

• Gap between two panels in a row — moves the boundary between those two panels. Each row is resized independently.
• Gap between two rows — moves the boundary between those rows.
• E — makes all panels equally sized again.

The panel sizes are kept as you navigate with the arrow keys. Dragging is disabled while the toolbar's zoom or pan mode is active.

Viewer modes

The viewer has three mouse modes, which can be switched with the keyboard instead of the toolbar buttons:

• D — default mode: drag the gaps between panels to resize them
• O — toggle zoom mode: drag a rectangle over a plot to zoom into it
• P — toggle pan mode: drag to pan around a plot (right-drag to zoom)
• H — reset the zoom and pan of all panels

When you zoom into a PDF plot, the visible region is re-rendered at full screen resolution shortly after you stop zooming or panning, so that text and fine lines stay sharp at any zoom level. Until it is ready (which can take a few seconds for very complex PDFs), the zoomed-in plot is shown slightly blurred.

Uninstalling

• If want to uninstall, simply run:

   pipx uninstall image-comparator