PyPatchMatch 2.0.1__tar.gz → 2.0.2__tar.gz

{pypatchmatch-2.0.1 → pypatchmatch-2.0.2}/CLAUDE.md

@@ -84,10 +84,13 @@ Other entry points:
    every name in `patch_match.__all__` is re-exported.
 2. `patchmatch/patch_match.py` is the public API. It validates and canonicalizes the
    inputs (`_prepare_inputs`, `_check_patch_size`, the `ijmap` and `guide_weight`
-   checks), picks the entry point (`PM_inpaint`, `PM_inpaint2` with a global mask, and
-   their `_regularity` variants) and runs it through `_call`. It loads the library at
-   import time; on `OSError` it logs a warning and sets `patchmatch_available = False`,
-   and every function then raises `RuntimeError` through `_get_lib()`.
+   checks), returns a copy of the image without a native call if `_has_holes` finds no
+   hole outside the global mask, picks the entry point (`PM_inpaint`, `PM_inpaint2`
+   with a global mask, and their `_regularity` variants) and runs it through `_call`.
+   It loads the library at import time; on `OSError` (no library) or `AttributeError`
+   (one without the `PM_*` symbols) it logs a warning and sets
+   `patchmatch_available = False`, and every function then raises `RuntimeError`
+   through `_get_lib()`.
 3. `patchmatch/_lib.py` is the ctypes layer: the `CShapeT`/`CMatT` structures, the dtype
    table, `np_to_pymat`/`pymat_to_np`, `find_library` (looks for `libpatchmatch.so`,
    `libpatchmatch.dylib` or `patchmatch.dll` in every directory of `patchmatch.__path__`)

{pypatchmatch-2.0.1 → pypatchmatch-2.0.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: PyPatchMatch
-Version: 2.0.1
+Version: 2.0.2
 Summary: This library implements the PatchMatch based inpainting algorithm.
 Keywords: inpainting,patchmatch,image-processing,opencv
 Author-Email: The InvokeAI Project <lincoln.stein@gmail.com>, Jiayuan Mao <maojiayuan@gmail.com>, Kyle Schouviller <kyle0654@hotmail.com>, Matthias Wild <mauwii@outlook.de>, Younesse ANDAM <younesse.andam@gmail.com>
@@ -42,7 +42,7 @@ and Python interfaces. This implementation is heavily based on the implementatio
 Younesse ANDAM: [younesse-cv/PatchMatch](https://github.com/younesse-cv/PatchMatch),
 with some bug fixes, and updates.
 
-![Birdhouses removed from a photo by patchmatch.inpaint](https://raw.githubusercontent.com/mauwii/PyPatchMatch/v2.0.1/examples/images/readme_example.jpg)
+![Birdhouses removed from a photo by patchmatch.inpaint](https://raw.githubusercontent.com/mauwii/PyPatchMatch/v2.0.2/examples/images/readme_example.jpg)
 
 From left to right: the photo, the input of
 [examples/py_example.py](https://github.com/mauwii/PyPatchMatch/blob/main/examples/py_example.py)
@@ -99,11 +99,12 @@ The previous import path `from patchmatch import patch_match` keeps working.
 pixels in each direction. Larger patches follow larger structures but are much slower;
 the default of 15 compares 31x31 patches, the examples use 3.
 
-`patchmatch.set_random_seed(seed)` sets the seed of the randomized search and
-`patchmatch.set_verbose(True)` prints the progress of the native code to stderr.
-`patchmatch.inpaint_regularity(image, mask, ijmap)` additionally guides the search with
-a regularity map, an HxWx3 float32 array with the regularity coordinates of each pixel
-in its first two channels. Its `guide_weight` must be at least 0.
+`patchmatch.set_random_seed(seed)` sets the seed of the randomized search, modulo
+`2**32`, and `patchmatch.set_verbose(True)` prints the progress of the native code to
+stderr. `patchmatch.inpaint_regularity(image, mask, ijmap)` additionally guides the
+search with a regularity map, an HxWx3 float32 array with the regularity coordinates of
+each pixel in its first two channels. Its `guide_weight` must be between 0 and the
+largest float32, about 3.4e38.
 
 C++ (see
 [examples/cpp_example.cpp](https://github.com/mauwii/PyPatchMatch/blob/main/examples/cpp_example.cpp),

{pypatchmatch-2.0.1 → pypatchmatch-2.0.2}/README.md

@@ -69,11 +69,12 @@ The previous import path `from patchmatch import patch_match` keeps working.
 pixels in each direction. Larger patches follow larger structures but are much slower;
 the default of 15 compares 31x31 patches, the examples use 3.
 
-`patchmatch.set_random_seed(seed)` sets the seed of the randomized search and
-`patchmatch.set_verbose(True)` prints the progress of the native code to stderr.
-`patchmatch.inpaint_regularity(image, mask, ijmap)` additionally guides the search with
-a regularity map, an HxWx3 float32 array with the regularity coordinates of each pixel
-in its first two channels. Its `guide_weight` must be at least 0.
+`patchmatch.set_random_seed(seed)` sets the seed of the randomized search, modulo
+`2**32`, and `patchmatch.set_verbose(True)` prints the progress of the native code to
+stderr. `patchmatch.inpaint_regularity(image, mask, ijmap)` additionally guides the
+search with a regularity map, an HxWx3 float32 array with the regularity coordinates of
+each pixel in its first two channels. Its `guide_weight` must be between 0 and the
+largest float32, about 3.4e38.
 
 C++ (see
 [examples/cpp_example.cpp](https://github.com/mauwii/PyPatchMatch/blob/main/examples/cpp_example.cpp),

{pypatchmatch-2.0.1 → pypatchmatch-2.0.2}/patchmatch/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '2.0.1'
-__version_tuple__ = version_tuple = (2, 0, 1)
+__version__ = version = '2.0.2'
+__version_tuple__ = version_tuple = (2, 0, 2)
 
-__commit_id__ = commit_id = 'g995b76749'
+__commit_id__ = commit_id = 'g38b611eb9'

{pypatchmatch-2.0.1 → pypatchmatch-2.0.2}/patchmatch/csrc/masked_image.cpp

@@ -1,6 +1,7 @@
 #include "masked_image.h"
 
 #include <algorithm>
+#include <cstdint>
 
 const cv::Size MaskedImage::kDownsampleKernelSize = cv::Size(6, 6);
 const std::array<int, 6> MaskedImage::kDownsampleKernel = {1, 5, 10, 10, 5, 1};
@@ -107,8 +108,9 @@ MaskedImage MaskedImage::upsample(int new_w, int new_h) const
     {
         for (int x = 0; x < new_w; ++x)
         {
-            const int yy = y * size.height / new_h;
-            const int xx = x * size.width / new_w;
+            // In 64 bits: the products overflow an int from 65,537 pixels on.
+            const auto yy = static_cast<int>(std::int64_t{y} * size.height / new_h);
+            const auto xx = static_cast<int>(std::int64_t{x} * size.width / new_w);
 
             if (is_globally_masked(yy, xx))
             {

{pypatchmatch-2.0.1 → pypatchmatch-2.0.2}/patchmatch/csrc/nnf.cpp

@@ -296,12 +296,17 @@ int RegularityGuidedPatchDistanceMetricV2::operator()(
     if (target_y < 0 || target_y >= target.size().height || target_x < 0 || target_x >= target.size().width)
         return PatchDistanceMetric::kDistanceScale;
 
-    // Map pyramid-level coordinates to the full-resolution ijmap. Height and width are
-    // scaled independently and clamped, since the pyramid sizes are rounded per axis.
+    // Map pyramid-level coordinates to the full-resolution ijmap, height and width
+    // independently; a coordinate inside the image stays inside the map. In 64 bits:
+    // the products overflow an int from 46,342 pixels on.
     const int map_h = m_ijmap.size().height;
     const int map_w = m_ijmap.size().width;
-    auto map_y = [&](const MaskedImage &img, int y) { return std::min(y * map_h / img.size().height, map_h - 1); };
-    auto map_x = [&](const MaskedImage &img, int x) { return std::min(x * map_w / img.size().width, map_w - 1); };
+    auto map_y = [&](const MaskedImage &img, int y) {
+        return static_cast<int>(std::int64_t{y} * map_h / img.size().height);
+    };
+    auto map_x = [&](const MaskedImage &img, int x) {
+        return static_cast<int>(std::int64_t{x} * map_w / img.size().width);
+    };
 
     double score1 = PatchDistanceMetric::kDistanceScale;
     if (!source.is_globally_masked(source_y, source_x) && !target.is_globally_masked(target_y, target_x))

{pypatchmatch-2.0.1 → pypatchmatch-2.0.2}/patchmatch/patch_match.py

@@ -17,7 +17,6 @@ from __future__ import annotations
 
 import ctypes
 import logging
-import math
 import operator
 from collections.abc import Callable
 from typing import SupportsIndex, TypeAlias
@@ -44,7 +43,9 @@ ImageLike: TypeAlias = np.ndarray | Image.Image
 
 try:
     _lib: ctypes.CDLL | None = load_library()
-except OSError as e:
+except (OSError, AttributeError) as e:
+    # AttributeError: a library without the PM_* functions, e.g. one that 1.x
+    # compiled into the package directory and that pip does not remove on upgrade
     _lib = None
     logger.warning("patchmatch failed to load: %s", e)
 
@@ -54,6 +55,9 @@ patchmatch_available = _lib is not None
 # The native code computes 2 * patch_size + 1 as a C int.
 _MAX_PATCH_SIZE = (2**31 - 2) // 2
 
+# The native code takes a C float, which turns larger weights into infinity.
+_MAX_GUIDE_WEIGHT = float(np.finfo(np.float32).max)
+
 
 def _get_lib() -> ctypes.CDLL:
     if _lib is None:
@@ -62,10 +66,17 @@ def _get_lib() -> ctypes.CDLL:
 
 
 def set_random_seed(seed: int) -> None:
+    """Set the seed of the randomized search of all following inpaintings.
+
+    Every inpainting starts from this seed, so equal inputs give equal results. The
+    native code keeps it as a 32-bit unsigned int, so ``seed`` is taken modulo
+    ``2**32``: ``2**32`` behaves like 0 and -1 like ``2**32 - 1``.
+    """
     _get_lib().PM_set_random_seed(ctypes.c_uint(seed))
 
 
 def set_verbose(verbose: bool) -> None:
+    """Print the progress of all following inpaintings to stderr if ``verbose``."""
     _get_lib().PM_set_verbose(ctypes.c_int(verbose))
 
 
@@ -96,8 +107,7 @@ def inpaint(
     lib = _get_lib()
     patch_size = _check_patch_size(patch_size)
     image, mask, global_mask = _prepare_inputs(image, mask, global_mask)
-    # OpenCV 4.6 turns an empty image into one of shape (0, 0, 1)
-    if image.size == 0:
+    if not _has_holes(mask, global_mask):
         return image.copy()
 
     if global_mask is None:
@@ -140,15 +150,16 @@ def inpaint_regularity(
         raise ValueError("ijmap must only contain finite values")
     ijmap = np.ascontiguousarray(ijmap)
 
-    # the native code divides by 1 + guide_weight and indexes a table with the result
+    # the native code divides by 1 + guide_weight and indexes a table with the result;
+    # the comparison also rejects NaN
     guide_weight = float(guide_weight)
-    if not (math.isfinite(guide_weight) and guide_weight >= 0):
+    if not 0 <= guide_weight <= _MAX_GUIDE_WEIGHT:
         raise ValueError(
-            f"guide_weight must be a finite number >= 0, got {guide_weight}"
+            f"guide_weight must be between 0 and {_MAX_GUIDE_WEIGHT:g}, "
+            f"got {guide_weight}"
         )
 
-    # OpenCV 4.6 turns an empty image into one of shape (0, 0, 1)
-    if image.size == 0:
+    if not _has_holes(mask, global_mask):
         return image.copy()
 
     args = (ijmap, ctypes.c_int(patch_size), ctypes.c_float(guide_weight))
@@ -194,6 +205,19 @@ def _prepare_inputs(
     return image, mask, global_mask
 
 
+def _has_holes(mask: np.ndarray, global_mask: np.ndarray | None) -> bool:
+    """Whether a hole lies outside the global mask.
+
+    Otherwise the result equals the input, but the native code still runs every
+    level of the pyramid. This also covers empty images, which OpenCV 4.6 would
+    return with the shape (0, 0, 1).
+    """
+    holes = mask != 0
+    if global_mask is not None:
+        holes &= global_mask == 0
+    return bool(holes.any())
+
+
 def _call(func: Callable[..., CMatT], *args: object) -> np.ndarray:
     """Call ``func`` with arrays converted to pymats and copy the result."""
     lib = _get_lib()

{pypatchmatch-2.0.1 → pypatchmatch-2.0.2}/tests/test_patch_match.py

@@ -14,6 +14,7 @@ from patchmatch import _lib, patch_match
 
 HEIGHT, WIDTH = 48, 64
 HOLE = (slice(20, 28), slice(24, 36))
+AROUND_HOLE = (slice(14, 34), slice(18, 42))
 
 
 @pytest.fixture
@@ -27,6 +28,21 @@ def image() -> np.ndarray:
     return img
 
 
+@pytest.fixture
+def regular_image() -> np.ndarray:
+    """Noisy pattern that repeats every 8 pixels, as ijmap describes, with the hole.
+
+    The regularity term copies from whole periods away, which in the gradient of
+    ``image`` shifted the fill by up to 35 color values.
+    """
+    rng = np.random.default_rng(0)
+    tile = rng.integers(80, 120, (8, 8, 3))
+    noise = rng.integers(0, 8, (HEIGHT, WIDTH, 3))
+    img = (np.tile(tile, (HEIGHT // 8, WIDTH // 8, 1)) + noise).astype(np.uint8)
+    img[HOLE] = 255
+    return img
+
+
 @pytest.fixture
 def hole_mask() -> np.ndarray:
     mask = np.zeros((HEIGHT, WIDTH), dtype=np.uint8)
@@ -48,14 +64,21 @@ def seed():
 
 
 def assert_filled(result: np.ndarray, source: np.ndarray) -> None:
-    """The hole is filled and all other pixels keep their values."""
+    """The hole is filled to blend in, and all other pixels keep their values."""
     assert result.shape == source.shape
     assert result.dtype == np.uint8
-    assert not (result[HOLE] == 255).all(axis=-1).any()
     known = np.ones(source.shape[:2], dtype=bool)
     known[HOLE] = False
     np.testing.assert_array_equal(result[known], source[known])
 
+    # a hole that is not filled stays black, see _initialize_pyramid
+    ring = np.zeros_like(known)
+    ring[AROUND_HOLE] = True
+    ring[HOLE] = False
+    fill = result[HOLE].reshape(-1, 3).mean(axis=0)
+    color_diff = np.abs(fill - source[ring].mean(axis=0))
+    assert color_diff.max() < 10, color_diff
+
 
 # --- package ----------------------------------------------------------------
 
@@ -83,11 +106,7 @@ def test_inpaint_default_mask_fills_white_pixels(image):
 
 def test_inpaint_explicit_mask(image, hole_mask):
     image[HOLE] = 0  # not white: only the explicit mask marks the hole
-    result = patchmatch.inpaint(image, hole_mask, patch_size=3)
-    assert result.shape == image.shape
-    assert (result[HOLE] != 0).any()
-    known = hole_mask == 0
-    np.testing.assert_array_equal(result[known], image[known])
+    assert_filled(patchmatch.inpaint(image, hole_mask, patch_size=3), image)
 
 
 def test_inpaint_global_mask(image, hole_mask):
@@ -127,6 +146,33 @@ def test_inpaint_empty_image(shape, ijmap):
         assert result is not empty
 
 
+@pytest.mark.parametrize("covered", [False, True], ids=["no-hole", "global-mask"])
+@pytest.mark.parametrize(
+    "func",
+    [patchmatch.inpaint, patchmatch.inpaint_regularity],
+    ids=lambda f: f.__name__,
+)
+def test_input_without_holes_skips_the_native_code(
+    monkeypatch, image, hole_mask, ijmap, func, covered
+):
+    """The result equals the input, but the native code ran every level.
+
+    That took 14 s for a 512 x 512 image with the default patch size.
+    """
+
+    def native_call(*args):
+        pytest.fail("the native code was called")
+
+    monkeypatch.setattr(patch_match, "_call", native_call)
+    mask = hole_mask if covered else np.zeros_like(hole_mask)
+    kwargs = {"ijmap": ijmap} if func is patchmatch.inpaint_regularity else {}
+
+    result = func(image, mask, global_mask=hole_mask if covered else None, **kwargs)
+
+    np.testing.assert_array_equal(result, image)
+    assert not np.shares_memory(result, image)
+
+
 @pytest.mark.parametrize("patch_size", [1, 3, 7])
 def test_inpaint_patch_sizes(image, patch_size):
     assert_filled(patchmatch.inpaint(image, patch_size=patch_size), image)
@@ -154,6 +200,30 @@ def test_inpaint_thin_hole_takes_the_colors_beside_it():
         assert np.abs(fill - plain).max() < 10, (seed, fill)
 
 
+@pytest.mark.parametrize("regularity", [False, True], ids=["inpaint", "regularity"])
+@pytest.mark.parametrize("tall", [True, False], ids=["tall", "wide"])
+def test_inpaint_very_large_image(tall, regularity):
+    """Coordinate products overflowed a C int near the end of very large images.
+
+    The regularity metric crashed from 46,342 pixels on, and the upsampling filled
+    a hole near the bottom black from 65,537 pixels on.
+    """
+    image = np.random.default_rng(0).integers(90, 110, (70_000, 4, 3), dtype=np.uint8)
+    image[-30:-20, 1:3] = 255
+    if not tall:
+        image = image.transpose(1, 0, 2)
+    holes = (image == 255).all(axis=2)
+
+    if regularity:
+        ijmap = np.zeros(image.shape, dtype=np.float32)
+        result = patchmatch.inpaint_regularity(image, None, ijmap, patch_size=1)
+    else:
+        result = patchmatch.inpaint(image, patch_size=1)
+
+    np.testing.assert_array_equal(result[~holes], image[~holes])
+    assert np.abs(result[holes].mean(axis=0) - 100).max() < 10
+
+
 def test_inpaint_does_not_modify_inputs(image, hole_mask):
     image_before, mask_before = image.copy(), hole_mask.copy()
     patchmatch.inpaint(image, hole_mask, global_mask=hole_mask, patch_size=3)
@@ -205,19 +275,19 @@ def test_set_verbose_prints_progress(verbose):
 @pytest.mark.parametrize("use_global_mask", [False, True], ids=["", "global"])
 @pytest.mark.parametrize("guide_weight", [0.0, 0.25, 1.0])
 def test_inpaint_regularity(
-    image, hole_mask, ijmap, use_mask, use_global_mask, guide_weight
+    regular_image, hole_mask, ijmap, use_mask, use_global_mask, guide_weight
 ):
     global_mask = np.zeros_like(hole_mask)
     global_mask[:8] = 1
     result = patchmatch.inpaint_regularity(
-        image,
+        regular_image,
         hole_mask if use_mask else None,
         ijmap,
         global_mask=global_mask if use_global_mask else None,
         patch_size=3,
         guide_weight=guide_weight,
     )
-    assert_filled(result, image)
+    assert_filled(result, regular_image)
 
 
 def test_inpaint_regularity_scales_smaller_ijmap(image):
@@ -347,10 +417,10 @@ def test_inpaint_regularity_invalid_ijmap(image, bad_ijmap):
         patchmatch.inpaint_regularity(image, None, bad_ijmap)
 
 
-@pytest.mark.parametrize("guide_weight", [-1.0, -0.5, float("nan"), float("inf")])
+@pytest.mark.parametrize("guide_weight", [-1.0, -0.5, float("nan"), float("inf"), 1e39])
 def test_inpaint_regularity_invalid_guide_weight(image, ijmap, guide_weight):
     # a weight of -1 used to crash the native code, other negative weights made it
-    # read outside of the similarity table
+    # read outside of the similarity table, and 1e39 became infinity as a C float
     with pytest.raises(ValueError, match="guide_weight"):
         patchmatch.inpaint_regularity(image, None, ijmap, guide_weight=guide_weight)
 
@@ -447,6 +517,28 @@ def test_import_without_native_library():
     assert "--no-cache-dir" in process.stderr
 
 
+def test_import_with_incompatible_library():
+    """A library without the PM_* functions must not break the import either.
+
+    1.x compiled the library into the package directory, and pip keeps it there.
+    Pillow's extension module stands in for it.
+    """
+    code = (
+        "import importlib\n"
+        "from pathlib import Path\n"
+        "import PIL._imaging\n"
+        "from patchmatch import _lib, patch_match\n"
+        "_lib.find_library = lambda: Path(PIL._imaging.__file__)\n"
+        "importlib.reload(patch_match)\n"
+        "assert not patch_match.patchmatch_available\n"
+    )
+    process = subprocess.run(
+        [sys.executable, "-c", code], capture_output=True, text=True, check=True
+    )
+    assert "patchmatch failed to load" in process.stderr
+    assert "PM_" in process.stderr
+
+
 # --- ctypes conversion ------------------------------------------------------