imdiff 0.4.6__tar.gz → 2.1.0__tar.gz

imdiff-2.1.0/PKG-INFO

@@ -0,0 +1,148 @@
+Metadata-Version: 2.4
+Name: imdiff
+Version: 2.1.0
+Summary: Compare image files in different directories
+Author-email: "John T. Goetz" <theodore.goetz@gmail.com>
+Project-URL: homepage, https://gitlab.com/johngoetz/imdiff
+Keywords: image-diff,directory-comparison,visual-regression,golden-files,test-artifacts,qa
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
+Classifier: Natural Language :: English
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Multimedia :: Graphics :: Viewers
+Classifier: Topic :: Scientific/Engineering :: Image Processing
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Topic :: Software Development :: Testing
+Classifier: Topic :: Utilities
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy
+Requires-Dist: pillow
+Requires-Dist: ttkbootstrap
+Provides-Extra: dev
+Requires-Dist: ruff; extra == "dev"
+Requires-Dist: basedpyright; extra == "dev"
+Dynamic: license-file
+
+# 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:
+
+```bash
+python -m imdiff path/to/expected.png path/to/actual.png
+```
+
+Compare two directories and print a CI-friendly summary:
+
+```bash
+python -m imdiff --summary tests/baseline-images tests/generated-images
+```
+
+By default the normalized RMSE is measured over the whole image, which tolerates
+the many tiny GPU/driver rendering variations that show up across large images.
+To instead catch small but concentrated differences, select a sliding-window
+size with `--window`; the reported score becomes the worst-scoring window of that
+size:
+
+```bash
+python -m imdiff --window medium tests/baseline-images tests/generated-images
+```
+
+The available window sizes are `global` (the default, whole image), `small`
+(32x32), `medium` (64x64), `large` (128x128), and `xlarge` (256x256). You can
+also pass an explicit pixel size as `WIDTH,HEIGHT`, for example
+`--window 1024,1024`, when none of the presets fit. A window larger than the
+image is clamped to the image size. The flag applies to both the interactive
+windows and `--summary` mode.
+
+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.
+
+## Programmatic comparison
+
+The same comparison core is available to other Python code, such as test
+harnesses that compare a captured screenshot against a stored reference:
+
+```python
+from imdiff import ImageComparator, RmseWindow
+
+comparator = ImageComparator(reference_png, actual_png, RmseWindow.Medium)
+
+status = comparator.diff_info  # 'identical', 'missing', 'different-size', ...
+if isinstance(status, float):  # a same-size pair: status is the normalized RMSE
+    assert status <= 0.03, f'normalized RMSE {status:g} exceeded threshold'
+
+comparator.diff                # grayscale difference image (PIL.Image)
+comparator.high_contrast_diff  # histogram-stretched difference image
+```
+
+`diff_info` returns a symbolic status string for presence, size, and load
+problems, or the normalized RMSE (range `[0, 1]`) when both images decode at the
+same size. The metric honors the `window` passed to the constructor: `Global`
+scores the whole image, while any other `RmseWindow` reports the largest score
+found across every window position of that size. The `window` may also be an
+explicit `(width, height)` tuple instead of a preset. A window larger than the
+image is clamped to the image size. Decoded images and derived results are
+cached on first use and recomputed after `copy_left_to_right`,
+`copy_right_to_left`, `delete_files`, or an explicit `clear`.
+
+The `normalized_rmse(left_data, right_data, window)` function is also exported
+for callers that already hold equally sized RGBA arrays.
+
+## Repository Layout
+
+- `imdiff/image_comparator.py` is the comparison core: the `RmseWindow` sizes,
+  the `normalized_rmse` metric, and the lazy `ImageComparator` 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.

imdiff-2.1.0/README.md

@@ -0,0 +1,116 @@
+# 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:
+
+```bash
+python -m imdiff path/to/expected.png path/to/actual.png
+```
+
+Compare two directories and print a CI-friendly summary:
+
+```bash
+python -m imdiff --summary tests/baseline-images tests/generated-images
+```
+
+By default the normalized RMSE is measured over the whole image, which tolerates
+the many tiny GPU/driver rendering variations that show up across large images.
+To instead catch small but concentrated differences, select a sliding-window
+size with `--window`; the reported score becomes the worst-scoring window of that
+size:
+
+```bash
+python -m imdiff --window medium tests/baseline-images tests/generated-images
+```
+
+The available window sizes are `global` (the default, whole image), `small`
+(32x32), `medium` (64x64), `large` (128x128), and `xlarge` (256x256). You can
+also pass an explicit pixel size as `WIDTH,HEIGHT`, for example
+`--window 1024,1024`, when none of the presets fit. A window larger than the
+image is clamped to the image size. The flag applies to both the interactive
+windows and `--summary` mode.
+
+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.
+
+## Programmatic comparison
+
+The same comparison core is available to other Python code, such as test
+harnesses that compare a captured screenshot against a stored reference:
+
+```python
+from imdiff import ImageComparator, RmseWindow
+
+comparator = ImageComparator(reference_png, actual_png, RmseWindow.Medium)
+
+status = comparator.diff_info  # 'identical', 'missing', 'different-size', ...
+if isinstance(status, float):  # a same-size pair: status is the normalized RMSE
+    assert status <= 0.03, f'normalized RMSE {status:g} exceeded threshold'
+
+comparator.diff                # grayscale difference image (PIL.Image)
+comparator.high_contrast_diff  # histogram-stretched difference image
+```
+
+`diff_info` returns a symbolic status string for presence, size, and load
+problems, or the normalized RMSE (range `[0, 1]`) when both images decode at the
+same size. The metric honors the `window` passed to the constructor: `Global`
+scores the whole image, while any other `RmseWindow` reports the largest score
+found across every window position of that size. The `window` may also be an
+explicit `(width, height)` tuple instead of a preset. A window larger than the
+image is clamped to the image size. Decoded images and derived results are
+cached on first use and recomputed after `copy_left_to_right`,
+`copy_right_to_left`, `delete_files`, or an explicit `clear`.
+
+The `normalized_rmse(left_data, right_data, window)` function is also exported
+for callers that already hold equally sized RGBA arrays.
+
+## Repository Layout
+
+- `imdiff/image_comparator.py` is the comparison core: the `RmseWindow` sizes,
+  the `normalized_rmse` metric, and the lazy `ImageComparator` 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.

imdiff-2.1.0/imdiff/__init__.py

@@ -0,0 +1,8 @@
+"""Public package surface for embedding imdiff in other Python code."""
+
+# pyright: reportUnusedImport=none
+# ruff: noqa: F401
+
+from .directory_comparator import dir_diff
+from .image_comparator import ImageComparator, RmseWindow, Window, normalized_rmse
+from .version import __version__, version_info

{imdiff-0.4.6 → imdiff-2.1.0}/imdiff/__main__.py

@@ -1,7 +1,8 @@
+"""Module entry point for `python -m imdiff`."""
+
 import sys
 
 from .cli.main import main
 
-
 if __name__ == '__main__':
     sys.exit(main())

imdiff-2.1.0/imdiff/_compat.py

@@ -0,0 +1,19 @@
+"""Compatibility helpers for typing features that are optional at runtime."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import TYPE_CHECKING, TypeVar
+
+F = TypeVar('F', bound=Callable[..., object])
+
+if TYPE_CHECKING:
+    from typing_extensions import override
+else:
+
+    def override(method: F) -> F:
+        """Preserve the decorator shape when `typing_extensions` is unavailable."""
+        return method
+
+
+__all__ = ['override']

imdiff-2.1.0/imdiff/_types.py

@@ -0,0 +1,19 @@
+"""Shared type aliases for the comparison layer."""
+
+from __future__ import annotations
+
+import pathlib
+from os import PathLike
+from typing import Literal, Union
+
+PathInput = Union[str, PathLike[str], pathlib.Path]
+DiffStatus = Literal[
+    'identical',
+    'different-size',
+    'missing',
+    'new',
+    'failed-to-load',
+    'not-found',
+]
+DiffInfo = Union[DiffStatus, float]
+FileEntry = tuple[str, pathlib.Path, pathlib.Path]

imdiff-2.1.0/imdiff/cli/__init__.py

@@ -0,0 +1 @@
+"""CLI package for file and directory entry points."""

imdiff-2.1.0/imdiff/cli/_gui_runtime.py

@@ -0,0 +1,39 @@
+"""Helpers for lazy GUI startup and headless fallback."""
+
+from __future__ import annotations
+
+
+class GuiUnavailableError(RuntimeError):
+    """Raised when GUI support is unavailable but summary mode can continue."""
+
+
+def format_gui_warning(error: GuiUnavailableError) -> str:
+    """Render a concise warning for stderr when falling back to summary mode."""
+    return f'warning: GUI unavailable ({error}); running in summary mode'
+
+
+def normalize_gui_import_error(error: BaseException) -> GuiUnavailableError | None:
+    """Convert expected GUI import failures into a fallback-friendly error."""
+    if isinstance(error, ModuleNotFoundError):
+        module_name = error.name or str(error)
+        return GuiUnavailableError(f'missing Python module {module_name}')
+
+    if isinstance(error, ImportError):
+        module_name = getattr(error, 'name', None)
+        if module_name:
+            return GuiUnavailableError(f'failed to import Python module {module_name}')
+        return GuiUnavailableError(str(error))
+
+    return None
+
+
+def normalize_gui_startup_error(error: BaseException) -> GuiUnavailableError | None:
+    """Convert expected Tk startup failures into a fallback-friendly error."""
+    error_type = type(error)
+    if error_type.__name__ == 'TclError' and error_type.__module__ in {
+        'tkinter',
+        '_tkinter',
+    }:
+        return GuiUnavailableError(f'Tk startup failed: {error}')
+
+    return None

imdiff-2.1.0/imdiff/cli/dir_diff.py

@@ -0,0 +1,87 @@
+"""CLI adapters for directory comparison modes."""
+
+from __future__ import annotations
+
+import difflib
+import importlib
+import pathlib
+from typing import Optional
+
+from ..image_comparator import ImageComparator, RmseWindow, Window
+from ..list_files import is_image, list_files
+from ._gui_runtime import (
+    normalize_gui_import_error,
+    normalize_gui_startup_error,
+)
+
+
+def app(
+    leftdir: Optional[pathlib.Path] = None,
+    rightdir: Optional[pathlib.Path] = None,
+    window: Window = RmseWindow.Global,
+) -> None:
+    """Open the directory comparison window for the requested roots."""
+    try:
+        gui_module = importlib.import_module('imdiff.gui')
+        DirDiffMainWindow = gui_module.DirDiffMainWindow
+    except (ImportError, ModuleNotFoundError) as error:
+        gui_error = normalize_gui_import_error(error)
+        assert gui_error is not None
+        raise gui_error from error
+
+    try:
+        win = DirDiffMainWindow(window=window)
+    except Exception as error:
+        gui_error = normalize_gui_startup_error(error)
+        if gui_error is not None:
+            raise gui_error from error
+        raise
+
+    win.load(leftdir, rightdir)
+    win.mainloop()
+
+
+def print_diff(
+    leftdir: pathlib.Path,
+    rightdir: pathlib.Path,
+    window: Window = RmseWindow.Global,
+) -> int:
+    """Print a summary of directory differences and return the diff count."""
+    ndiffs = 0
+    assert leftdir.is_dir() and rightdir.is_dir(), 'Items must both be directories'
+
+    rmse_threshold = 0.02
+
+    for subpath, left, right in list_files(leftdir, rightdir):
+        # Summary mode reuses the same comparison rules as the GUI so CI output
+        # matches what a developer will see when opening the same directories.
+        if not left.is_file():
+            ndiffs += 1
+            print(f'Only in {right.parent}: {subpath}')
+        elif not right.is_file():
+            ndiffs += 1
+            print(f'Only in {left.parent}: {subpath}')
+        elif is_image(left) and is_image(right):
+            icmp = ImageComparator(left, right, window)
+            diff_info = icmp.diff_info
+            if diff_info != 'identical':
+                if isinstance(diff_info, str):
+                    ndiffs += 1
+                    print(f'{diff_info} (as image): {subpath}')
+                elif diff_info > rmse_threshold:
+                    ndiffs += 1
+                    print(f'image difference NRMSE {diff_info:.4f}: {subpath}')
+        else:
+            diff_output = list(
+                difflib.unified_diff(
+                    left.read_text().splitlines(),
+                    right.read_text().splitlines(),
+                    fromfile=str(left),
+                    tofile=str(right),
+                    lineterm='',
+                )
+            )
+            if diff_output:
+                ndiffs += 1
+                print('\n'.join(diff_output))
+    return ndiffs

imdiff-2.1.0/imdiff/cli/image_diff.py

@@ -0,0 +1,81 @@
+"""CLI adapters for single-image comparison modes."""
+
+from __future__ import annotations
+
+import difflib
+import importlib
+import pathlib
+from typing import Optional
+
+from ..image_comparator import ImageComparator, RmseWindow, Window
+from ..list_files import is_image
+from ._gui_runtime import (
+    normalize_gui_import_error,
+    normalize_gui_startup_error,
+)
+
+
+def app(
+    left: Optional[pathlib.Path] = None,
+    right: Optional[pathlib.Path] = None,
+    window: Window = RmseWindow.Global,
+) -> None:
+    """Open the single-image comparison window for the requested files."""
+    try:
+        gui_module = importlib.import_module('imdiff.gui')
+        ImageDiffMainWindow = gui_module.ImageDiffMainWindow
+    except (ImportError, ModuleNotFoundError) as error:
+        gui_error = normalize_gui_import_error(error)
+        assert gui_error is not None
+        raise gui_error from error
+
+    try:
+        win = ImageDiffMainWindow(window=window)
+    except Exception as error:
+        gui_error = normalize_gui_startup_error(error)
+        if gui_error is not None:
+            raise gui_error from error
+        raise
+
+    win.load(left, right)
+    win.mainloop()
+
+
+def print_diff(
+    left: pathlib.Path,
+    right: pathlib.Path,
+    window: Window = RmseWindow.Global,
+) -> int:
+    """Print a summary of a single file comparison and return the diff count."""
+    ndiffs = 0
+    assert left.is_file() and right.is_file(), 'Items must both be files'
+
+    rmse_threshold = 0.02
+    if is_image(left) and is_image(right):
+        icmp = ImageComparator(left, right, window)
+        diff_info = icmp.diff_info
+        if diff_info != 'identical':
+            ndiffs += 1
+            if diff_info == 'missing':
+                print(f'Only in {left.parent}: {left.name}')
+            elif diff_info == 'new':
+                print(f'Only in {right.parent}: {right.name}')
+            elif isinstance(diff_info, str):
+                print(f'Images {left} and {right} differ ({diff_info})')
+            elif diff_info > rmse_threshold:
+                print(f'Images {left} and {right} differ NRMSE: {diff_info}')
+    else:
+        diff_output = list(
+            difflib.unified_diff(
+                left.read_text().splitlines(),
+                right.read_text().splitlines(),
+                fromfile=str(left),
+                tofile=str(right),
+                lineterm='',
+            )
+        )
+        if diff_output:
+            ndiffs += 1
+            print('\n'.join(diff_output))
+
+    return ndiffs

imdiff-2.1.0/imdiff/cli/main.py

@@ -0,0 +1,135 @@
+"""Command-line dispatch for summary and GUI workflows."""
+
+from __future__ import annotations
+
+import argparse
+import pathlib
+import sys
+from typing import Optional
+
+from ..image_comparator import RmseWindow, Window
+from ..version import __version__
+from . import dir_diff, image_diff
+from ._gui_runtime import GuiUnavailableError, format_gui_warning
+
+# CLI tokens map to the preset window sizes; the keys are what users type.
+WINDOW_CHOICES = {window.name.lower(): window for window in RmseWindow}
+
+
+class ParsedArgs(argparse.Namespace):
+    """Typed namespace so downstream code can treat parsed paths precisely."""
+
+    summary: bool = False
+    window: Window = RmseWindow.Global
+    left: pathlib.Path = pathlib.Path('.')
+    right: pathlib.Path = pathlib.Path('.')
+
+
+def parse_window(value: str) -> Window:
+    """Resolve a ``--window`` token to a preset or an explicit pixel size.
+
+    Accepts a preset name (``global``, ``small``, ...) or two positive integers
+    such as ``1024,1024`` for an arbitrary window. Anything else is reported as
+    an argparse error so the user sees the valid forms.
+    """
+    name = value.strip().lower()
+    if name in WINDOW_CHOICES:
+        return WINDOW_CHOICES[name]
+
+    parts = value.split(',')
+    if len(parts) == 2:
+        try:
+            width, height = (int(part) for part in parts)
+        except ValueError:
+            width = height = -1
+        if width > 0 and height > 0:
+            return (width, height)
+
+    presets = ', '.join(WINDOW_CHOICES)
+    raise argparse.ArgumentTypeError(
+        f'invalid window {value!r}; expected one of {presets} '
+        + 'or two positive integers like 1024,1024'
+    )
+
+
+def parse_args() -> ParsedArgs:
+    """Parse the shared CLI flags for file and directory comparison modes."""
+    parser = argparse.ArgumentParser(
+        prog='imdiff',
+        description='Compare images one by one or directory by directory',
+    )
+    parser.add_argument(
+        '--version',
+        action='version',
+        version=f'%(prog)s {__version__}',
+    )
+    parser.add_argument(
+        '--summary',
+        action='store_true',
+        help=(
+            'Print diff result and exit. Disables the GUI. '
+            'Exits with non-zero if there are differences.'
+        ),
+    )
+    parser.add_argument(
+        '--window',
+        type=parse_window,
+        default=RmseWindow.Global,
+        metavar='{global,small,medium,large,xlarge | WIDTH,HEIGHT}',
+        help=(
+            'Normalized RMSE window. "global" scores the whole image; a preset '
+            'or an explicit WIDTH,HEIGHT (e.g. 1024,1024) reports the '
+            'worst-scoring window of that size.'
+        ),
+    )
+    parser.add_argument(
+        'left',
+        default='.',
+        type=pathlib.Path,
+        help='Image or directory of images to compare.',
+    )
+    parser.add_argument(
+        'right',
+        default='.',
+        type=pathlib.Path,
+        help='Image or directory of images to compare.',
+    )
+    return parser.parse_args(namespace=ParsedArgs())
+
+
+def main() -> Optional[int]:
+    """Dispatch to GUI or summary workflows, with summary fallback for headless use."""
+    args = parse_args()
+    window = args.window
+    if args.left.is_dir():
+        if not args.right.is_dir():
+            raise NotADirectoryError(
+                'Paths must be either both image files or both directories'
+            )
+        if args.summary:
+            ndiffs = dir_diff.print_diff(args.left, args.right, window)
+            return int(ndiffs > 0)
+        try:
+            dir_diff.app(args.left, args.right, window)
+            return None
+        except GuiUnavailableError as error:
+            print(format_gui_warning(error), file=sys.stderr)
+            ndiffs = dir_diff.print_diff(args.left, args.right, window)
+            return int(ndiffs > 0)
+
+    if args.left.is_file():
+        assert args.right.is_file(), (
+            'Paths must be either both image files or both directories'
+        )
+        if args.summary:
+            ndiffs = image_diff.print_diff(args.left, args.right, window)
+            return int(ndiffs > 0)
+        try:
+            image_diff.app(args.left, args.right, window)
+            return None
+        except GuiUnavailableError as error:
+            print(format_gui_warning(error), file=sys.stderr)
+            ndiffs = image_diff.print_diff(args.left, args.right, window)
+            return int(ndiffs > 0)
+
+    raise OSError(f'{args.left} is not a file or directory')