imdiff 2.0.0__tar.gz → 2.1.0__tar.gz

{imdiff-2.0.0 → imdiff-2.1.0}/PKG-INFO

@@ -1,11 +1,11 @@
 Metadata-Version: 2.4
 Name: imdiff
-Version: 2.0.0
+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 :: 4 - Beta
+Classifier: Development Status :: 5 - Production/Stable
 Classifier: Environment :: Console
 Classifier: Intended Audience :: Developers
 Classifier: Intended Audience :: End Users/Desktop
@@ -14,10 +14,6 @@ Classifier: Natural Language :: English
 Classifier: Operating System :: OS Independent
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3 :: Only
-Classifier: Programming Language :: Python :: 3.9
-Classifier: Programming Language :: Python :: 3.10
-Classifier: Programming Language :: Python :: 3.11
-Classifier: Programming Language :: Python :: 3.12
 Classifier: Topic :: Multimedia :: Graphics :: Viewers
 Classifier: Topic :: Scientific/Engineering :: Image Processing
 Classifier: Topic :: Software Development :: Quality Assurance
@@ -87,15 +83,64 @@ Compare two directories and print a CI-friendly summary:
 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` contains the lazy comparison model shared by the
-  CLI and GUI.
+- `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.

{imdiff-2.0.0 → imdiff-2.1.0}/README.md

@@ -51,15 +51,64 @@ Compare two directories and print a CI-friendly summary:
 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` contains the lazy comparison model shared by the
-  CLI and GUI.
+- `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.

{imdiff-2.0.0 → imdiff-2.1.0}/imdiff/__init__.py

@@ -4,5 +4,5 @@
 # ruff: noqa: F401
 
 from .directory_comparator import dir_diff
-from .image_comparator import ImageComparator
+from .image_comparator import ImageComparator, RmseWindow, Window, normalized_rmse
 from .version import __version__, version_info

{imdiff-2.0.0 → imdiff-2.1.0}/imdiff/cli/dir_diff.py

@@ -7,7 +7,7 @@ import importlib
 import pathlib
 from typing import Optional
 
-from ..image_comparator import ImageComparator
+from ..image_comparator import ImageComparator, RmseWindow, Window
 from ..list_files import is_image, list_files
 from ._gui_runtime import (
     normalize_gui_import_error,
@@ -16,7 +16,9 @@ from ._gui_runtime import (
 
 
 def app(
-    leftdir: Optional[pathlib.Path] = None, rightdir: Optional[pathlib.Path] = None
+    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:
@@ -28,7 +30,7 @@ def app(
         raise gui_error from error
 
     try:
-        win = DirDiffMainWindow()
+        win = DirDiffMainWindow(window=window)
     except Exception as error:
         gui_error = normalize_gui_startup_error(error)
         if gui_error is not None:
@@ -39,7 +41,11 @@ def app(
     win.mainloop()
 
 
-def print_diff(leftdir: pathlib.Path, rightdir: pathlib.Path) -> int:
+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'
@@ -56,7 +62,7 @@ def print_diff(leftdir: pathlib.Path, rightdir: pathlib.Path) -> int:
             ndiffs += 1
             print(f'Only in {left.parent}: {subpath}')
         elif is_image(left) and is_image(right):
-            icmp = ImageComparator(left, right)
+            icmp = ImageComparator(left, right, window)
             diff_info = icmp.diff_info
             if diff_info != 'identical':
                 if isinstance(diff_info, str):

{imdiff-2.0.0 → imdiff-2.1.0}/imdiff/cli/image_diff.py

@@ -7,7 +7,7 @@ import importlib
 import pathlib
 from typing import Optional
 
-from ..image_comparator import ImageComparator
+from ..image_comparator import ImageComparator, RmseWindow, Window
 from ..list_files import is_image
 from ._gui_runtime import (
     normalize_gui_import_error,
@@ -16,7 +16,9 @@ from ._gui_runtime import (
 
 
 def app(
-    left: Optional[pathlib.Path] = None, right: Optional[pathlib.Path] = None
+    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:
@@ -28,7 +30,7 @@ def app(
         raise gui_error from error
 
     try:
-        win = ImageDiffMainWindow()
+        win = ImageDiffMainWindow(window=window)
     except Exception as error:
         gui_error = normalize_gui_startup_error(error)
         if gui_error is not None:
@@ -39,14 +41,18 @@ def app(
     win.mainloop()
 
 
-def print_diff(left: pathlib.Path, right: pathlib.Path) -> int:
+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)
+        icmp = ImageComparator(left, right, window)
         diff_info = icmp.diff_info
         if diff_info != 'identical':
             ndiffs += 1

{imdiff-2.0.0 → imdiff-2.1.0}/imdiff/cli/main.py

@@ -7,19 +7,51 @@ 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(
@@ -39,6 +71,17 @@ def parse_args() -> ParsedArgs:
             '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='.',
@@ -57,20 +100,21 @@ def parse_args() -> 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)
+            ndiffs = dir_diff.print_diff(args.left, args.right, window)
             return int(ndiffs > 0)
         try:
-            dir_diff.app(args.left, args.right)
+            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)
+            ndiffs = dir_diff.print_diff(args.left, args.right, window)
             return int(ndiffs > 0)
 
     if args.left.is_file():
@@ -78,14 +122,14 @@ def main() -> Optional[int]:
             'Paths must be either both image files or both directories'
         )
         if args.summary:
-            ndiffs = image_diff.print_diff(args.left, args.right)
+            ndiffs = image_diff.print_diff(args.left, args.right, window)
             return int(ndiffs > 0)
         try:
-            image_diff.app(args.left, args.right)
+            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)
+            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')

{imdiff-2.0.0 → imdiff-2.1.0}/imdiff/directory_comparator.py

@@ -8,12 +8,14 @@ import filecmp
 import pathlib
 
 from ._types import PathInput
-from .image_comparator import ImageComparator
+from .image_comparator import ImageComparator, RmseWindow, Window, check_window
 from .list_files import is_image, list_files
 
 
 def dir_diff(
-    leftdir: PathInput, rightdir: PathInput
+    leftdir: PathInput,
+    rightdir: PathInput,
+    window: Window = RmseWindow.Global,
 ) -> collections.defaultdict[str, list[str]]:
     """Group directory entries by comparison status for summary-style reporting.
 
@@ -22,6 +24,7 @@ def dir_diff(
     It mirrors the GUI thresholds so command-line output and interactive review
     describe the same files as identical, similar, or different.
     """
+    check_window(window)
     leftdir_path = pathlib.Path(leftdir)
     rightdir_path = pathlib.Path(rightdir)
     if not leftdir_path.is_dir():
@@ -42,7 +45,7 @@ def dir_diff(
         elif filecmp.cmp(left, right, shallow=False):
             dinfo['identical'].append(subpath)
         elif is_image(left) and is_image(right):
-            icmp = ImageComparator(left, right)
+            icmp = ImageComparator(left, right, window)
             diff_info = icmp.diff_info
             if isinstance(diff_info, str):
                 dinfo[diff_info].append(subpath)

{imdiff-2.0.0 → imdiff-2.1.0}/imdiff/gui/_types.py

@@ -13,7 +13,7 @@ from .image_scaling import ImageScaling
 
 CanvasName = Literal['left', 'right', 'diff']
 ImageData = Optional[Image.Image]
-Event = tk.Event[tk.Misc]
+Event = tk.Event  # [tk.Misc]
 SelectCallback = Callable[[Optional[ImageComparator]], None]
 UpdateItemPath = Union[str, pathlib.Path, None]
 UpdateItemCallback = Callable[[UpdateItemPath, Optional[ImageComparator]], None]

{imdiff-2.0.0 → imdiff-2.1.0}/imdiff/gui/dir_diff_main_window.py

@@ -11,7 +11,7 @@ from typing import Optional, final
 import ttkbootstrap as ttk
 
 from .._compat import override
-from ..image_comparator import ImageComparator
+from ..image_comparator import ImageComparator, RmseWindow, Window
 from ._types import Event, UpdateItemPath
 from .file_list_frame import FileListFrame
 from .image_frame import ImageFrame
@@ -24,7 +24,12 @@ log = logging.getLogger(__name__)
 class DirDiffMainWindow(ttk.Window):
     """Combine the directory browser, shared image frame, and status bar."""
 
-    def __init__(self, left_label: str = 'left', right_label: str = 'right') -> None:
+    def __init__(
+        self,
+        left_label: str = 'left',
+        right_label: str = 'right',
+        window: Window = RmseWindow.Global,
+    ) -> None:
         super().__init__(title='Image Comparator', themename='sandstone')
         self.pane_window = tk.PanedWindow(self, orient=tk.HORIZONTAL, sashwidth=8)
         self.file_list_frame = FileListFrame(
@@ -32,6 +37,7 @@ class DirDiffMainWindow(ttk.Window):
             on_select=self.on_select,
             left_label=left_label,
             right_label=right_label,
+            window=window,
         )
         self.image_frame = ImageFrame(self.pane_window, update_item=self.update_item)
         self.image_frame.add_standard_operate_buttons(

{imdiff-2.0.0 → imdiff-2.1.0}/imdiff/gui/file_list_frame.py

@@ -15,7 +15,7 @@ from typing import Generic, Optional, TypeVar, final
 
 import ttkbootstrap as ttk
 
-from ..image_comparator import ImageComparator
+from ..image_comparator import ImageComparator, RmseWindow, Window
 from ..list_files import is_image, list_files
 from ..util import Size, separate_thread
 from ._types import Event, SelectCallback
@@ -77,12 +77,14 @@ class FileListFrame(ttk.Frame):
         on_select: Optional[SelectCallback] = None,
         left_label: str = 'left',
         right_label: str = 'right',
+        window: Window = RmseWindow.Global,
     ) -> None:
         super().__init__(parent)
 
         self.on_select_command = on_select
         self.left_label = left_label
         self.right_label = right_label
+        self.window = window
 
         self.files: dict[str, ImageComparator] = {}
         self.file_entries: list[str] = []
@@ -259,7 +261,7 @@ class FileListFrame(ttk.Frame):
         if self.leftdir is not None and self.rightdir is not None:
             for file_path, left, right in list_files(self.leftdir, self.rightdir):
                 if is_image(left) or is_image(right):
-                    file_cmp = ImageComparator(left, right)
+                    file_cmp = ImageComparator(left, right, self.window)
                     self.files[file_path] = file_cmp
                     self.file_queue.put(file_path)
                 elif self.text_file_queue.status == IterableQueue.Status.Filling:

{imdiff-2.0.0 → imdiff-2.1.0}/imdiff/gui/image_diff_main_window.py

@@ -9,6 +9,7 @@ import tkinter as tk
 from typing import Optional, final
 
 from .._compat import override
+from ..image_comparator import RmseWindow, Window
 from ._types import Event
 from .image_frame import ImageFrame
 from .status_bar import StatusBar
@@ -20,11 +21,16 @@ log = logging.getLogger(__name__)
 class ImageDiffMainWindow(tk.Tk):
     """Compose the shared image frame and status bar for single-file use."""
 
-    def __init__(self, left_label: str = 'left', right_label: str = 'right') -> None:
+    def __init__(
+        self,
+        left_label: str = 'left',
+        right_label: str = 'right',
+        window: Window = RmseWindow.Global,
+    ) -> None:
         super().__init__()
         self.title('Image Comparator')
         self.image_frame = ImageFrame(
-            self, left_label=left_label, right_label=right_label
+            self, left_label=left_label, right_label=right_label, window=window
         )
         self.image_frame.add_standard_operate_buttons()
         self.status_bar = StatusBar(self)

{imdiff-2.0.0 → imdiff-2.1.0}/imdiff/gui/image_frame.py

@@ -10,7 +10,7 @@ from typing import Optional, final
 
 import ttkbootstrap as ttk
 
-from ..image_comparator import ImageComparator
+from ..image_comparator import ImageComparator, RmseWindow, Window
 from ..util import Coordinates, Size, separate_thread
 from ._types import ActionCallback, CanvasName, Event, ImageData, UpdateItemCallback
 from .image_canvas import ImageCanvas
@@ -35,9 +35,11 @@ class ImageFrame(ttk.Frame):
         update_item: Optional[UpdateItemCallback] = None,
         left_label: str = 'left',
         right_label: str = 'right',
+        window: Window = RmseWindow.Global,
     ) -> None:
         super().__init__(parent)
         self.update_item_command = update_item
+        self.window = window
         self.left_label = tk.StringVar(value=left_label)
         self.right_label = tk.StringVar(value=right_label)
 
@@ -343,7 +345,7 @@ class ImageFrame(ttk.Frame):
         self, left: Optional[pathlib.Path], right: Optional[pathlib.Path]
     ) -> None:
         """Construct a comparator for a file pair and hand it to the loader."""
-        comparator = ImageComparator(left, right)
+        comparator = ImageComparator(left, right, self.window)
         self.load_comparator(comparator)
 
     def clear(self) -> None: