imdiff 2.0.0

Compare image files in different directories

ImDiff: Compare Directories of Images

ImDiff compares either two image files or two directory trees that contain image files with matching relative paths. It is intended for workflows where generated images need visual review as part of test development, golden-file updates, or artifact triage.

The project exposes the same comparison engine through two interfaces:

• python -m imdiff LEFT RIGHT opens a Tk-based review window when the GUI stack is available, or warns and falls back to summary mode when it is not.
• python -m imdiff --summary LEFT RIGHT prints a non-interactive summary and exits with a non-zero status when differences are found without importing any GUI-only modules.

When both arguments are directories, ImDiff walks the union of both directory trees, pairs files by relative path, and classifies each entry as:

• identical: byte-identical files or text files with no unified diff output
• similar: images whose normalized RMSE is below the project threshold
• different: images or text files whose contents differ materially
• different-size: image pairs with different dimensions
• missing or new: a file exists on only one side
• failed-to-load: a file exists but Pillow could not decode it as an image

The interactive directory view combines a file tree, image panes, and file operations so a reviewer can inspect left, right, and diff images, switch zoom policies, and copy or delete files directly from the comparison session.

This utility requires that the Tk Python packages be installed on the system. Hint for those running Ubuntu:

apt install python3-pil python3-pil.imagetk python3-tk

The application also depends on numpy and ttkbootstrap for image math and themed Tk widgets.

Usage

Compare two image files:

python -m imdiff path/to/expected.png path/to/actual.png

Compare two directories and print a CI-friendly summary:

python -m imdiff --summary tests/baseline-images tests/generated-images

When the GUI cannot be imported or Tk cannot start, the default interactive command warns on stderr and continues in the same summary mode used by --summary. This makes headless CI environments safe without changing the CLI command line.

Repository Layout

• imdiff/image_comparator.py contains the lazy comparison model shared by the CLI and GUI.
• imdiff/list_files.py pairs files across directory trees.
• imdiff/cli/ contains the command-line entry points and summary printing.
• imdiff/gui/ contains the Tk windows, canvases, menus, and directory browser.
• developing/architecture.md describes the component relationships in more detail.