PyPatchMatch 2.1.1__tar.gz → 2.2.0b1__tar.gz

{pypatchmatch-2.1.1 → pypatchmatch-2.2.0b1}/CLAUDE.md

@@ -1,10 +1,9 @@
 # CLAUDE.md
 
-This file provides guidance to Claude Code (claude.ai/code) when working with code in
-this repository. The details of the native code, the C interface, packaging and CI are
-path-scoped rules in `.claude/rules/`, which load when a matching file is read or
-edited; read the rule before changing such a file through Bash. The sanitizer, C++
-coverage and fill-quality runs are skills in `.claude/skills/`.
+The details of the native code, the C interface, packaging and CI are path-scoped rules
+in `.claude/rules/`, which load when a matching file is read or edited; read the rule
+before changing such a file through Bash. The sanitizer, C++ coverage and fill-quality
+runs are skills in `.claude/skills/`.
 
 ## Project
 
@@ -27,24 +26,18 @@ uv run pre-commit install
 uv run pytest                              # all tests, with the coverage gate
 uv run pytest -m "not e2e"                 # fast unit tests only
 uv run pytest -m e2e --no-cov              # end-to-end tests only
-uv run pytest tests/test_patch_match.py::test_inpaint_global_mask --no-cov
-uv run pytest -k regularity --no-cov
 uv run mypy                                # strict, also a pre-commit hook
 uv run pre-commit run --all-files          # what the CI lint job runs
-uv run ruff check --fix . && uv run ruff format .
 uv build                                   # sdist and wheel into dist/
 ```
 
 - Pass `--no-cov` for any partial run: `addopts` always enables coverage, and
   `fail_under = 95` (branch coverage, subprocesses included through
   `patch = ["subprocess"]`) fails the run otherwise.
-- Use `uv run pytest`, not `python -m pytest`. The latter puts the repository root on
-  `sys.path`, which imports the source tree `patchmatch/` without the compiled library;
-  the symptoms are the warning `patchmatch failed to load: libpatchmatch.* not found`
-  and `RuntimeError: the patchmatch native library is not available` in every test.
-- `--cov=patchmatch` measures the source tree, so coverage only works with the editable
-  install that `uv sync` creates. With a non-editable install (`uv sync --no-editable`,
-  `uv pip install .`) it reports 0 % and the gate fails.
+- Keep the editable install that `uv sync` creates. With a non-editable one
+  (`uv sync --no-editable`, `uv pip install .`), `--cov=patchmatch` measures the unused
+  source tree and reports 0 %, and `python -m pytest` imports the source tree from the
+  repository root, without the compiled library.
 - `uv sync` rebuilds the library only when a `tool.uv.cache-keys` entry changes
   (`CMakeLists.txt`, `patchmatch/csrc/*`, `pyproject.toml`, git commit or tags). Force it
   with `uv sync --reinstall-package pypatchmatch`.
@@ -69,11 +62,8 @@ Other entry points:
 - `uv run python scripts/render_readme_example.py` runs `py_example.py` and renders the
   picture at the top of the README, `examples/images/readme_example.jpg`; rerun it and
   commit the picture after changes that affect the fills.
-- CMake options: `PATCHMATCH_BUILD_EXAMPLES` (OFF), `PATCHMATCH_FAST_MATH` (ON,
-  `-ffast-math` or `/fp:fast`), `PATCHMATCH_SANITIZE` (OFF, ASan and UBSan with
-  `float-cast-overflow`, every finding aborts; turns off fast math, which lets the
-  compiler drop checks; GCC and Clang only), `PATCHMATCH_COVERAGE` (OFF, gcov counters
-  at `-Og`; GCC and Clang only).
+- CMake options: the `option()` lines of `CMakeLists.txt`. `PATCHMATCH_SANITIZE` turns
+  off fast math, which lets the compiler drop checks.
 
 ## Architecture
 
@@ -114,7 +104,8 @@ CMake installs the shared library into the package directory.
   goes through a test parameter instead of a `# type: ignore`.
 - Backwards compatibility: `from patchmatch import patch_match` and
   `patch_match.CShapeT`/`CMatT` keep working (tested).
-- Comments explain why: which crash a check prevents, why a construct is avoided.
+- Comments explain why, in one short line where the code would otherwise be misread or
+  wrongly simplified; details and measurements go into the commit message.
 - No `NOSONAR` markers: change the code so that the SonarCloud rule is satisfied, and ask
   when that seems impossible. The only exception is `nnf.cpp`: cpp:S2245 flags every
   declaration of `std::mt19937`, which only drives the randomized search.

{pypatchmatch-2.1.1 → pypatchmatch-2.2.0b1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: PyPatchMatch
-Version: 2.1.1
+Version: 2.2.0b1
 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>
@@ -43,7 +43,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.1.1/examples/images/readme_example.jpg)
+![Birdhouses removed from a photo by patchmatch.inpaint](https://raw.githubusercontent.com/mauwii/PyPatchMatch/v2.2.0b1/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)
@@ -98,7 +98,9 @@ The previous import path `from patchmatch import patch_match` keeps working.
 
 `patch_size` is the radius of the compared patches, which span `2 * patch_size + 1`
 pixels in each direction. Larger patches follow larger structures but are much slower;
-the default of 15 compares 31x31 patches, the examples use 3.
+the default of 15 compares 31x31 patches, the examples use 3. Below 5, the coarse levels
+that lay out the fill are also tried with a radius of 5, which is kept where it fits
+the surroundings better, so that repeating patterns continue across larger holes.
 
 `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

{pypatchmatch-2.1.1 → pypatchmatch-2.2.0b1}/README.md

@@ -68,7 +68,9 @@ The previous import path `from patchmatch import patch_match` keeps working.
 
 `patch_size` is the radius of the compared patches, which span `2 * patch_size + 1`
 pixels in each direction. Larger patches follow larger structures but are much slower;
-the default of 15 compares 31x31 patches, the examples use 3.
+the default of 15 compares 31x31 patches, the examples use 3. Below 5, the coarse levels
+that lay out the fill are also tried with a radius of 5, which is kept where it fits
+the surroundings better, so that repeating patterns continue across larger holes.
 
 `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

{pypatchmatch-2.1.1 → pypatchmatch-2.2.0b1}/patchmatch/_lib.py

@@ -82,8 +82,9 @@ def find_library() -> Path:
     )
 
 
-def load_library() -> ctypes.CDLL:
-    lib = ctypes.CDLL(str(find_library()))
+def load_library(path: Path | None = None) -> ctypes.CDLL:
+    """Load the installed library, or the build at ``path``."""
+    lib = ctypes.CDLL(str(path or find_library()))
 
     lib.PM_set_random_seed.argtypes = [ctypes.c_uint]
     lib.PM_set_random_seed.restype = None

{pypatchmatch-2.1.1 → pypatchmatch-2.2.0b1}/patchmatch/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '2.1.1'
-__version_tuple__ = version_tuple = (2, 1, 1)
+__version__ = version = '2.2.0b1'
+__version_tuple__ = version_tuple = (2, 2, 0, 'b1')
 
-__commit_id__ = commit_id = 'gef1a63c74'
+__commit_id__ = commit_id = 'gb66a4a1d8'

{pypatchmatch-2.1.1 → pypatchmatch-2.2.0b1}/patchmatch/csrc/inpaint.cpp

@@ -58,6 +58,17 @@ namespace
         return count > 0 ? sum / count : sum;
     }
 
+    // The pixel loops read three channels and index the masks with the image coordinates.
+    void check_inputs(const MaskedImage &image)
+    {
+        if (image.image().empty())
+            return;
+        CV_Assert(image.image().type() == CV_8UC3);
+        CV_Assert(image.mask().type() == CV_8UC1 && image.mask().size() == image.size());
+        if (image.has_global_mask())
+            CV_Assert(image.global_mask().type() == CV_8UC1 && image.global_mask().size() == image.size());
+    }
+
     bool is_known(const MaskedImage &image, int y, int x)
     {
         return !image.is_masked(y, x) && !image.is_globally_masked(y, x);
@@ -68,6 +79,28 @@ namespace
         return image.is_masked(y, x) && !image.is_globally_masked(y, x);
     }
 
+    bool has_hole(const MaskedImage &image)
+    {
+        for (int y = 0; y < image.size().height; ++y)
+        {
+            for (int x = 0; x < image.size().width; ++x)
+            {
+                if (is_hole(image, y, x))
+                    return true;
+            }
+        }
+        return false;
+    }
+
+    // A patch smaller than a structure cannot tell where it continues: on the coarsest level
+    // with a hole, holes wider than the patches were filled from several shifted copies.
+    constexpr int kCoarsePatchSize = 5;
+
+    int nnf_iterations(int level)
+    {
+        return std::min(7, 1 + level);
+    }
+
     // Chessboard distance of the hole pixels to the nearest known pixel, 0 beyond radius.
     cv::Mat hole_depths(const MaskedImage &image, int radius)
     {
@@ -328,6 +361,8 @@ Inpainting::Inpainting(
 
 void Inpainting::_initialize_pyramid()
 {
+    check_inputs(m_initial);
+
     // The colors under the holes would reach the fill through the gradients of their
     // neighbors and the target of a single-level pyramid. Black, like on coarser levels.
     auto source = m_initial.clone();
@@ -347,22 +382,62 @@ void Inpainting::_initialize_pyramid()
         source = source.downsample();
         m_pyramid.push_back(source);
     }
+
+    for (int level = 0; level < static_cast<int>(m_pyramid.size()); ++level)
+    {
+        if (has_hole(m_pyramid[level]))
+            m_coarsest_hole_level = level;
+    }
+    if (m_distance_metric->patch_size() < kCoarsePatchSize)
+        m_coarse_metric = m_distance_metric->with_patch_size(kCoarsePatchSize);
 }
 
 cv::Mat Inpainting::run(bool verbose, unsigned int random_seed)
 {
     NearestNeighborField::seed_random(random_seed);
-    const auto nr_levels = static_cast<int>(m_pyramid.size());
 
-    MaskedImage source;
+    int level = static_cast<int>(m_pyramid.size()) - 1;
     MaskedImage target;
-    for (int level = nr_levels - 1; level >= 0; --level)
+    // Below level 2 no level is left to compare the fills on.
+    if (m_coarse_metric && m_coarsest_hole_level >= 2)
     {
-        trace(verbose, "Inpainting level: ", level);
+        target = _run_levels(level, m_coarsest_hole_level + 1, target, m_distance_metric, verbose);
+        target = _fill_coarse_levels(target, verbose);
+        level = m_coarsest_hole_level - 2;
+    }
+    target = _run_levels(level, 0, target, m_distance_metric, verbose);
+
+    // Only the holes are filled. The maximization step of level 0 keeps the known pixels,
+    // but the pyramid leaves globally masked pixels black, which are neither filled nor
+    // used as a source. Copy every pixel outside the holes from the input.
+    // A plain loop instead of OpenCV matrix expressions: those pull OpenCV's whole
+    // expression module into the statically linked library, 40 % more on disk.
+    cv::Mat result = target.image();
+    for (int y = 0; y < result.rows; ++y)
+    {
+        for (int x = 0; x < result.cols; ++x)
+        {
+            if (m_initial.is_masked(y, x) && !m_initial.is_globally_masked(y, x))
+                continue;
+            const unsigned char *input = m_initial.get_image(y, x);
+            std::copy(input, input + 3, result.ptr<unsigned char>(y, x));
+        }
+    }
+    blend_hole_borders(result, m_initial);
+    return result;
+}
 
-        source = m_pyramid[level];
+// Runs the levels from `from` down to `to`; target is empty on the coarsest level.
+MaskedImage Inpainting::_run_levels(
+    int from, int to, MaskedImage target, const PatchDistanceMetric *metric, bool verbose)
+{
+    m_level_metric = metric;
+    for (int level = from; level >= to; --level)
+    {
+        trace(verbose, "Inpainting level: ", level);
 
-        const bool coarsest = level == nr_levels - 1;
+        const MaskedImage &source = m_pyramid[level];
+        const bool coarsest = level == static_cast<int>(m_pyramid.size()) - 1;
         if (coarsest)
         {
             target = source.clone();
@@ -373,34 +448,70 @@ cv::Mat Inpainting::run(bool verbose, unsigned int random_seed)
         if (level < 2)
             m_source2target.reset();
         else
-            m_source2target = coarsest ? NearestNeighborField(source, target, m_distance_metric)
-                                       : NearestNeighborField(source, target, m_distance_metric, *m_source2target);
-        m_target2source = coarsest ? NearestNeighborField(target, source, m_distance_metric)
-                                   : NearestNeighborField(target, source, m_distance_metric, m_target2source);
+            m_source2target = coarsest ? NearestNeighborField(source, target, metric)
+                                       : NearestNeighborField(source, target, metric, *m_source2target);
+        m_target2source = coarsest ? NearestNeighborField(target, source, metric)
+                                   : NearestNeighborField(target, source, metric, m_target2source);
 
         trace(verbose, "Initialization done.");
 
         target = _expectation_maximization(source, target, level, verbose);
     }
+    return target;
+}
 
-    // Only the holes are filled. The maximization step of level 0 keeps the known pixels,
-    // but the pyramid leaves globally masked pixels black, which are neither filled nor
-    // used as a source. Copy every pixel outside the holes from the input.
-    // A plain loop instead of OpenCV matrix expressions: those pull OpenCV's whole
-    // expression module into the statically linked library, 40 % more on disk.
-    cv::Mat result = target.image();
-    for (int y = 0; y < result.rows; ++y)
+// Fills the coarsest level with a hole and the next one with patch_size and with the
+// larger patches, and keeps the fill with the lower energy on the following level. The
+// larger patches lock onto repeating structures but pick flat sources elsewhere, which
+// made fills of foliage gray.
+MaskedImage Inpainting::_fill_coarse_levels(const MaskedImage &target, bool verbose)
+{
+    const int level = m_coarsest_hole_level;
+    const auto source2target = m_source2target;
+    const auto target2source = m_target2source;
+
+    const MaskedImage plain = _run_levels(level, level - 1, target, m_distance_metric, verbose);
+    const double plain_energy = _hole_energy(level - 2, plain);
+    const auto plain_source2target = m_source2target;
+    const auto plain_target2source = m_target2source;
+
+    m_source2target = source2target;
+    m_target2source = target2source;
+    MaskedImage coarse = _run_levels(level, level - 1, target, m_coarse_metric.get(), verbose);
+    const double coarse_energy = _hole_energy(level - 2, coarse);
+    trace(verbose, "Energy with patch_size: ", plain_energy, ", with larger patches: ", coarse_energy);
+    m_level_metric = m_distance_metric;
+    if (coarse_energy < plain_energy)
+        return coarse;
+    m_source2target = plain_source2target;
+    m_target2source = plain_target2source;
+    return plain;
+}
+
+// The mean distance of the patches with holes after a search with patch_size on the level,
+// started from the field of the level above, like the first iteration of that level.
+double Inpainting::_hole_energy(int level, const MaskedImage &target) const
+{
+    const MaskedImage &source = m_pyramid[level];
+    NearestNeighborField field(target, source, m_distance_metric, m_target2source);
+    field.minimize(nnf_iterations(level));
+
+    const int patch_size = m_distance_metric->patch_size();
+    const auto size = source.size();
+    double sum = 0;
+    int count = 0;
+    for (int i = 0; i < size.height; ++i)
     {
-        for (int x = 0; x < result.cols; ++x)
+        for (int j = 0; j < size.width; ++j)
         {
-            if (m_initial.is_masked(y, x) && !m_initial.is_globally_masked(y, x))
-                continue;
-            const unsigned char *input = m_initial.get_image(y, x);
-            std::copy(input, input + 3, result.ptr<unsigned char>(y, x));
+            if (source.contains_mask(i, j, patch_size) && !source.is_globally_masked(i, j))
+            {
+                sum += field.at(i, j, 2);
+                ++count;
+            }
         }
     }
-    blend_hole_borders(result, m_initial);
-    return result;
+    return count > 0 ? sum / count : 0;
 }
 
 // EM-Like algorithm (see "PatchMatch" - page 6).
@@ -409,7 +520,7 @@ MaskedImage Inpainting::_expectation_maximization(
     const MaskedImage &source, MaskedImage target, int level, bool verbose)
 {
     const int nr_iters_em = 1 + 2 * level;
-    const int nr_iters_nnf = std::min(7, 1 + level);
+    const int nr_iters_nnf = nnf_iterations(level);
 
     MaskedImage new_source;
     MaskedImage new_target;
@@ -491,7 +602,7 @@ void Inpainting::_update_links(const MaskedImage &source, bool image_changed)
             update(*m_source2target);
         update(m_target2source);
     };
-    const int patch_size = m_distance_metric->patch_size();
+    const int patch_size = m_level_metric->patch_size();
     const auto size = source.size();
     for (int i = 0; i < size.height; ++i)
     {
@@ -516,6 +627,7 @@ void Inpainting::_expectation_step(
         holes.emplace(source);
     const VoteCaster caster(
         nnf, source2target, vote, source, upscaled, best_only, holes.has_value() ? &holes.value() : nullptr);
+    // The larger patches of m_coarse_metric would average more votes, which blurred the fills.
     const int patch_size = m_distance_metric->patch_size();
     const auto &kDistance2Similarity = distance2similarity();
     const auto source_size = nnf.source_size();

{pypatchmatch-2.1.1 → pypatchmatch-2.2.0b1}/patchmatch/csrc/inpaint.h

@@ -1,5 +1,6 @@
 #pragma once
 
+#include <memory>
 #include <optional>
 #include <vector>
 
@@ -16,6 +17,9 @@ public:
 
 private:
     void _initialize_pyramid(void);
+    MaskedImage _run_levels(int from, int to, MaskedImage target, const PatchDistanceMetric *metric, bool verbose);
+    MaskedImage _fill_coarse_levels(const MaskedImage &target, bool verbose);
+    double _hole_energy(int level, const MaskedImage &target) const;
     MaskedImage _expectation_maximization(const MaskedImage &source, MaskedImage target, int level, bool verbose);
     void _update_links(const MaskedImage &source, bool image_changed);
     void _expectation_step(
@@ -29,4 +33,9 @@ private:
     std::optional<NearestNeighborField> m_source2target;
     NearestNeighborField m_target2source;
     const PatchDistanceMetric *m_distance_metric;
+    // Searches on the levels that lay out the fill, if patch_size is smaller than kCoarsePatchSize.
+    std::unique_ptr<PatchDistanceMetric> m_coarse_metric;
+    int m_coarsest_hole_level = -1;
+    // Searches on the current level; the votes use patch_size.
+    const PatchDistanceMetric *m_level_metric = nullptr;
 };

{pypatchmatch-2.1.1 → pypatchmatch-2.2.0b1}/patchmatch/csrc/masked_image.cpp

@@ -52,19 +52,31 @@ namespace
 
 bool MaskedImage::contains_mask(int y, int x, int patch_size) const
 {
-    auto mask_size = size();
-    for (int dy = -patch_size; dy <= patch_size; ++dy)
+    const auto size = this->size();
+    if (!m_hole_sums_computed)
     {
-        for (int dx = -patch_size; dx <= patch_size; ++dx)
+        m_hole_sums = cv::Mat(size.height + 1, size.width + 1, CV_32S, cv::Scalar(0));
+        for (int yy = 0; yy < size.height; ++yy)
         {
-            const int yy = y + dy;
-            const int xx = x + dx;
-            if (yy >= 0 && yy < mask_size.height && xx >= 0 && xx < mask_size.width && is_masked(yy, xx) &&
-                !is_globally_masked(yy, xx))
-                return true;
+            for (int xx = 0; xx < size.width; ++xx)
+            {
+                const int hole = is_masked(yy, xx) && !is_globally_masked(yy, xx) ? 1 : 0;
+                m_hole_sums.at<int>(yy + 1, xx + 1) = hole + m_hole_sums.at<int>(yy, xx + 1) +
+                                                      m_hole_sums.at<int>(yy + 1, xx) - m_hole_sums.at<int>(yy, xx);
+            }
         }
+        m_hole_sums_computed = true;
     }
-    return false;
+    // In 64 bits: patch_size may be close to the largest int.
+    const auto clip = [](std::int64_t value, int limit) {
+        return static_cast<int>(std::clamp<std::int64_t>(value, 0, limit));
+    };
+    const int top = clip(std::int64_t{y} - patch_size, size.height);
+    const int bottom = clip(std::int64_t{y} + patch_size + 1, size.height);
+    const int left = clip(std::int64_t{x} - patch_size, size.width);
+    const int right = clip(std::int64_t{x} + patch_size + 1, size.width);
+    const auto sum = [this](int yy, int xx) { return m_hole_sums.at<int>(yy, xx); };
+    return sum(bottom, right) - sum(top, right) - sum(bottom, left) + sum(top, left) > 0;
 }
 
 MaskedImage MaskedImage::downsample() const

{pypatchmatch-2.1.1 → pypatchmatch-2.2.0b1}/patchmatch/csrc/masked_image.h

@@ -12,13 +12,6 @@ public:
         : m_image(image), m_mask(mask), m_global_mask(global_mask), m_has_global_mask(!global_mask.empty())
     {
     }
-    MaskedImage(
-        const cv::Mat &image, const cv::Mat &mask, const cv::Mat &global_mask, const cv::Mat &grady,
-        const cv::Mat &gradx, bool grad_computed)
-        : m_image(image), m_mask(mask), m_global_mask(global_mask), m_has_global_mask(!global_mask.empty()),
-          m_image_grady(grady), m_image_gradx(gradx), m_image_grad_computed(grad_computed)
-    {
-    }
     MaskedImage(int width, int height)
         : m_image(cv::Size(width, height), CV_8UC3, cv::Scalar::all(0)),
           m_mask(cv::Size(width, height), CV_8U, cv::Scalar::all(0))
@@ -31,11 +24,10 @@ public:
     MaskedImage &operator=(MaskedImage &&) noexcept = default;
     ~MaskedImage() = default;
 
+    // Without the gradients, which would be outdated once the clone is changed.
     MaskedImage clone() const
     {
-        return MaskedImage(
-            m_image.clone(), m_mask.clone(), m_global_mask.clone(), m_image_grady.clone(), m_image_gradx.clone(),
-            m_image_grad_computed);
+        return MaskedImage(m_image.clone(), m_mask.clone(), m_global_mask.clone());
     }
 
     cv::Size size() const
@@ -74,11 +66,13 @@ public:
         m_global_mask = cv::Mat(m_mask.size(), CV_8U);
         m_global_mask.setTo(cv::Scalar(0));
         m_has_global_mask = !m_global_mask.empty();
+        m_hole_sums_computed = false;
     }
     void set_global_mask_mat(const cv::Mat &other)
     {
         m_global_mask = other;
         m_has_global_mask = !other.empty();
+        m_hole_sums_computed = false;
     }
 
     bool is_masked(int y, int x) const
@@ -92,14 +86,17 @@ public:
     void set_mask(int y, int x, bool value)
     {
         m_mask.at<unsigned char>(y, x) = static_cast<unsigned char>(value);
+        m_hole_sums_computed = false;
     }
     void set_global_mask(int y, int x, bool value)
     {
         m_global_mask.at<unsigned char>(y, x) = static_cast<unsigned char>(value);
+        m_hole_sums_computed = false;
     }
     void clear_mask()
     {
         m_mask.setTo(cv::Scalar(0));
+        m_hole_sums_computed = false;
     }
 
     const unsigned char *get_image(int y, int x) const
@@ -127,4 +124,9 @@ private:
     mutable cv::Mat m_image_grady;
     mutable cv::Mat m_image_gradx;
     mutable bool m_image_grad_computed = false;
+    // computed on first use by contains_mask: the masked pixels outside the global mask
+    // above and left of each pixel. Copies share them with the masks, so change a mask only
+    // through an image that nothing has copied yet, as downsample and upsample do.
+    mutable cv::Mat m_hole_sums;
+    mutable bool m_hole_sums_computed = false;
 };

{pypatchmatch-2.1.1 → pypatchmatch-2.2.0b1}/patchmatch/csrc/nnf.cpp

@@ -200,13 +200,7 @@ void NearestNeighborField::_allocate_sums()
 NearestNeighborField::Measured NearestNeighborField::_measure(int y, int x, int y_target, int x_target, int bound) const
 {
     if (m_sums.empty())
-    {
-        const int distance =
-            bound < PatchDistanceMetric::kDistanceScale
-                ? m_distance_metric->distance_below(m_source, y, x, m_target, y_target, x_target, bound)
-                : (*m_distance_metric)(m_source, y, x, m_target, y_target, x_target);
-        return {distance, -1};
-    }
+        return {(*m_distance_metric)(m_source, y, x, m_target, y_target, x_target), -1};
     const int patch_size = m_distance_metric->patch_size();
     const std::int64_t sum = patch_sum(m_source, {y, x}, m_target, {y_target, x_target}, patch_size, bound);
     if (sum < 0)
@@ -259,6 +253,7 @@ void NearestNeighborField::_initialize_field_from(const NearestNeighborField &ot
     const auto &other_size = other.source_size();
     double fi = static_cast<double>(this_size.height) / other_size.height;
     double fj = static_cast<double>(this_size.width) / other_size.width;
+    const int patch_size = m_distance_metric->patch_size();
 
     for (int i = 0; i < this_size.height; ++i)
     {
@@ -266,6 +261,12 @@ void NearestNeighborField::_initialize_field_from(const NearestNeighborField &ot
         {
             if (m_source.is_globally_masked(i, j))
                 continue;
+            // The inpainting links them to themselves (_update_links); measuring them first took half its time.
+            if (!m_source.contains_mask(i, j, patch_size) && !m_target.contains_mask(i, j, patch_size))
+            {
+                set_identity(i, j);
+                continue;
+            }
 
             auto ilow = static_cast<int>(std::min(i / fi, static_cast<double>(other_size.height - 1)));
             auto jlow = static_cast<int>(std::min(j / fj, static_cast<double>(other_size.width - 1)));
@@ -283,8 +284,7 @@ void NearestNeighborField::_initialize_field_from(const NearestNeighborField &ot
 
             // A hole that is new on this level: search near the patch before a neighbor's link replaces its own.
             const bool linked_to_itself = other_value[0] == ilow && other_value[1] == jlow;
-            if (linked_to_itself && measured.distance > 0 &&
-                m_target.contains_mask(y_target, x_target, m_distance_metric->patch_size()))
+            if (linked_to_itself && measured.distance > 0 && m_target.contains_mask(y_target, x_target, patch_size))
                 _random_search(i, j);
         }
     }
@@ -400,13 +400,6 @@ int PatchSSDDistanceMetric::operator()(
         source, {source_y, source_x}, target, {target_y, target_x}, patch_size(), PatchDistanceMetric::kDistanceScale);
 }
 
-int PatchSSDDistanceMetric::distance_below(
-    const MaskedImage &source, int source_y, int source_x, const MaskedImage &target, int target_y, int target_x,
-    int bound) const
-{
-    return distance_masked_images(source, {source_y, source_x}, target, {target_y, target_x}, patch_size(), bound);
-}
-
 int RegularityGuidedPatchDistanceMetricV2::operator()(
     const MaskedImage &source, int source_y, int source_x, const MaskedImage &target, int target_y, int target_x) const
 {

{pypatchmatch-2.1.1 → pypatchmatch-2.2.0b1}/patchmatch/csrc/nnf.h

@@ -2,6 +2,8 @@
 
 #include <algorithm>
 #include <cstdint>
+#include <limits>
+#include <memory>
 #include <opencv2/core.hpp>
 #include <stdexcept>
 #include <vector>
@@ -11,7 +13,11 @@
 class PatchDistanceMetric
 {
 public:
-    explicit PatchDistanceMetric(int patch_size) : m_patch_size(patch_size) {}
+    explicit PatchDistanceMetric(int patch_size) : m_patch_size(patch_size)
+    {
+        // 0 crashes, negative sizes never terminate, and 2 * patch_size + 1 has to fit an int.
+        CV_Assert(patch_size >= 1 && patch_size <= (std::numeric_limits<int>::max() - 1) / 2);
+    }
     virtual ~PatchDistanceMetric() = default;
 
     int patch_size() const
@@ -21,12 +27,10 @@ public:
     virtual int operator()(
         const MaskedImage &source, int source_y, int source_x, const MaskedImage &target, int target_y,
         int target_x) const = 0;
-    // The distance if it is below bound, otherwise any value >= bound.
-    virtual int distance_below(
-        const MaskedImage &source, int source_y, int source_x, const MaskedImage &target, int target_y, int target_x,
-        int /* bound */) const
+    // The same metric with another patch size, or nullptr if it has none.
+    virtual std::unique_ptr<PatchDistanceMetric> with_patch_size(int) const
     {
-        return (*this)(source, source_y, source_x, target, target_y, target_x);
+        return nullptr;
     }
     static const int kDistanceScale;
 
@@ -110,12 +114,6 @@ public:
     static void seed_random(unsigned int seed);
 
 private:
-    // Private: a link written from outside would not update its sum.
-    int *mutable_ptr(int y, int x)
-    {
-        return m_field.ptr<int>(y, x);
-    }
-
     // A distance and the sum of the pixel costs behind it, -1 if unknown.
     struct Measured
     {
@@ -137,7 +135,7 @@ private:
     }
     void _set(int y, int x, int y_target, int x_target, Measured measured)
     {
-        auto ptr = mutable_ptr(y, x);
+        auto ptr = m_field.ptr<int>(y, x);
         ptr[0] = y_target;
         ptr[1] = x_target;
         ptr[2] = measured.distance;
@@ -173,9 +171,10 @@ public:
     int operator()(
         const MaskedImage &source, int source_y, int source_x, const MaskedImage &target, int target_y,
         int target_x) const override;
-    int distance_below(
-        const MaskedImage &source, int source_y, int source_x, const MaskedImage &target, int target_y, int target_x,
-        int bound) const override;
+    std::unique_ptr<PatchDistanceMetric> with_patch_size(int patch_size) const override
+    {
+        return std::make_unique<PatchSSDDistanceMetric>(patch_size);
+    }
     static const int kSSDScale;
 };
 
@@ -188,10 +187,16 @@ public:
         // The distance is divided by 1 + weight, so a negative weight flips its sign.
         if (!(weight >= 0))
             throw std::invalid_argument("the guide weight must be >= 0");
+        // operator() reads the first two channels at coordinates scaled to the map.
+        CV_Assert(!ijmap.empty() && ijmap.depth() == CV_32F && ijmap.channels() >= 2);
     }
     int operator()(
         const MaskedImage &source, int source_y, int source_x, const MaskedImage &target, int target_y,
         int target_x) const override;
+    std::unique_ptr<PatchDistanceMetric> with_patch_size(int patch_size) const override
+    {
+        return std::make_unique<RegularityGuidedPatchDistanceMetricV2>(patch_size, m_ijmap, m_weight);
+    }
 
 private:
     cv::Mat m_ijmap;

{pypatchmatch-2.1.1 → pypatchmatch-2.2.0b1}/patchmatch/csrc/pyinterface.cpp

@@ -9,10 +9,6 @@
 
 #include "inpaint.h"
 
-int _dtype_py_to_cv(PM_dtype_e dtype_py);
-cv::Mat _py_to_cv2(PM_mat_t pymat);
-PM_mat_t _cv2_to_py(cv::Mat cvmat);
-
 namespace
 {
     // The settings are set by one thread while others may be inpainting, since ctypes
@@ -68,6 +64,41 @@ namespace
         return PM_mat_t{nullptr, {0, 0, 0}, PM_dtype_e::PM_UINT8};
     }
 
+    int _dtype_py_to_cv(PM_dtype_e dtype_py)
+    {
+        switch (dtype_py)
+        {
+        case PM_dtype_e::PM_UINT8:
+            return CV_8U;
+        case PM_dtype_e::PM_FLOAT32:
+            return CV_32F;
+        default:
+            throw std::invalid_argument("unsupported dtype");
+        }
+    }
+
+    cv::Mat _py_to_cv2(PM_mat_t pymat)
+    {
+        int dtype = CV_MAKETYPE(_dtype_py_to_cv(pymat.dtype), pymat.shape.channels);
+        return cv::Mat(cv::Size(pymat.shape.width, pymat.shape.height), dtype, pymat.data_ptr).clone();
+    }
+
+    PM_mat_t _cv2_to_py(const cv::Mat &cvmat)
+    {
+        CV_Assert(cvmat.depth() == CV_8U);
+        PM_shape_t shape = {cvmat.size().width, cvmat.size().height, cvmat.channels()};
+        size_t dsize = cvmat.total() * cvmat.elemSize();
+
+        // A null pointer reports an error to Python, so allocate at least one byte. A failed
+        // allocation throws std::bad_alloc, which guarded() reports.
+        auto data = std::make_unique<unsigned char[]>(dsize > 0 ? dsize : 1);
+        if (dsize > 0)
+            std::memcpy(data.get(), cvmat.data, dsize);
+
+        // Python passes the buffer back to PM_free_pymat, which frees it.
+        return PM_mat_t{data.release(), shape, PM_dtype_e::PM_UINT8};
+    }
+
     PM_mat_t inpaint(
         PM_mat_t source_py, PM_mat_t mask_py, const PM_mat_t *global_mask_py, const PatchDistanceMetric &metric)
     {
@@ -134,41 +165,3 @@ PM_mat_t PM_inpaint2_regularity(
             RegularityGuidedPatchDistanceMetricV2(patch_size, _py_to_cv2(ijmap_py), guide_weight));
     });
 }
-
-int _dtype_py_to_cv(PM_dtype_e dtype_py)
-{
-    switch (dtype_py)
-    {
-    case PM_dtype_e::PM_UINT8:
-        return CV_8U;
-    case PM_dtype_e::PM_FLOAT32:
-        return CV_32F;
-    default:
-        throw std::invalid_argument("unsupported dtype");
-    }
-}
-
-cv::Mat _py_to_cv2(PM_mat_t pymat)
-{
-    int dtype = CV_MAKETYPE(_dtype_py_to_cv(pymat.dtype), pymat.shape.channels);
-    return cv::Mat(cv::Size(pymat.shape.width, pymat.shape.height), dtype, pymat.data_ptr).clone();
-}
-
-PM_mat_t _cv2_to_py(cv::Mat cvmat)
-{
-    if (!cvmat.isContinuous())
-        cvmat = cvmat.clone();
-
-    CV_Assert(cvmat.depth() == CV_8U);
-    PM_shape_t shape = {cvmat.size().width, cvmat.size().height, cvmat.channels()};
-    size_t dsize = cvmat.total() * cvmat.elemSize();
-
-    // A null pointer reports an error to Python, so allocate at least one byte. A failed
-    // allocation throws std::bad_alloc, which guarded() reports.
-    auto data = std::make_unique<unsigned char[]>(dsize > 0 ? dsize : 1);
-    if (dsize > 0)
-        std::memcpy(data.get(), cvmat.data, dsize);
-
-    // Python passes the buffer back to PM_free_pymat, which frees it.
-    return PM_mat_t{data.release(), shape, PM_dtype_e::PM_UINT8};
-}

{pypatchmatch-2.1.1 → pypatchmatch-2.2.0b1}/pyproject.toml

@@ -92,7 +92,7 @@ fallback_version = "0.0.0"
 
 [tool.cibuildwheel]
 # The wheels are Python-version independent (py3-none-<platform>), so each platform
-# is built and tested once; the CI workflow covers the other Python versions.
+# is built and tested once; the CI workflow covers the newest Python version.
 build = "cp311-*"
 skip = "*-musllinux_*"
 # OpenCV is built once per job in before-all, only for the runner's native arch

{pypatchmatch-2.1.1 → pypatchmatch-2.2.0b1}/scripts/evaluate_inpainting.py

@@ -5,9 +5,11 @@ in examples/images/SOURCES.md. forest_pruned.bmp and every ``*_pruned.*`` image
 git-ignored examples/images/local/ are added as object removals without a ground
 truth; their pure white pixels are the holes. grass-edge cuts a band at the right
 border, as in outpainting; brick-large and grass-large cut a circle of radius 242 into
-the center, 70 % of the image. forest-global and brick-global add a global mask,
-darkened in the report: the plant of examples/py_example_global_mask.py and the left
-third of brick.png.
+the center, 70 % of the image. pattern repeats almost exactly, so its error tells a fill
+that continues it (2 to 6) from a broken one; pattern-wide widens the hole to a radius
+of 60, where patch size 3 mixed the rings before 2.2 (error 37). forest-global and
+brick-global add a global mask, darkened in the report: the plant of
+examples/py_example_global_mask.py and the left third of brick.png.
 
 Usage:
     uv run python scripts/evaluate_inpainting.py
@@ -66,6 +68,7 @@ HOLES = {
     "gravel": (256, 256, 60, 60),
     "coffee": (260, 85, 55, 60),
     "chelsea": (52, 215, 24, 40),
+    "pattern": (320, 320, 40, 40),
 }
 COLUMNS = ("seam", "detail", "error")
 
@@ -127,6 +130,8 @@ def cases() -> Iterator[Case]:
     for name in ("brick", "grass"):
         truth = load(IMAGES / f"{name}.png")
         yield cut(f"{name}-large", truth, ellipse(truth.shape, 256, 256, 242, 242))
+    pattern = load(IMAGES / "pattern.png")
+    yield cut("pattern-wide", pattern, ellipse(pattern.shape, 320, 320, 60, 60))
     plant = np.zeros(pruned.shape[:2], dtype=bool)
     plant[290:, 100:180] = True
     yield Case("forest-global", pruned, white(pruned), None, plant)
@@ -194,12 +199,6 @@ def measure(
     return values
 
 
-def load_library(path: Path) -> ctypes.CDLL:
-    """Load another build of the library than the installed one."""
-    _lib.find_library = lambda: path
-    return _lib.load_library()
-
-
 def evaluate(library: ctypes.CDLL, case: Case, patch_size: int, seeds: int) -> Result:
     patch_match._lib = library
     mask = case.holes.astype(np.uint8)
@@ -523,12 +522,14 @@ def main() -> None:
     if args.seeds < 1:
         parser.error("--seeds must be at least 1")
 
-    current = load_library(args.library.resolve()) if args.library else patch_match._lib
+    current = (
+        _lib.load_library(args.library.resolve()) if args.library else patch_match._lib
+    )
     if current is None:
         parser.error("the installed package has no native library, pass --library")
     libraries, labels = [current], ["fill"]
     if args.baseline:
-        libraries.insert(0, load_library(args.baseline.resolve()))
+        libraries.insert(0, _lib.load_library(args.baseline.resolve()))
         labels = ["baseline", "current"]
     selected = set(args.cases.split(",")) if args.cases else None
 

{pypatchmatch-2.1.1 → pypatchmatch-2.2.0b1}/tests/test_e2e.py

@@ -1,5 +1,6 @@
 """End-to-end tests of the user workflows shown in examples/ and the README."""
 
+import functools
 import importlib.util
 from pathlib import Path
 
@@ -59,6 +60,21 @@ def assert_plausible_fill(
     assert color_diff.max() < 10, color_diff
 
 
+@functools.cache
+def fill(
+    image: str, hole: tuple[int, int, int, int] | None, patch_size: int
+) -> tuple[np.ndarray, np.ndarray]:
+    """``image`` with white holes and its fill with seed 0, shared by several tests."""
+    source = evaluation.load(IMAGES / image)
+    if hole is not None:
+        source[evaluation.ellipse(source.shape, *hole)] = 255
+    patchmatch.set_random_seed(0)
+    result = patchmatch.inpaint(source, patch_size=patch_size)
+    source.setflags(write=False)
+    result.setflags(write=False)
+    return source, result
+
+
 @pytest.fixture
 def pruned_image() -> Image.Image:
     return Image.open(IMAGES / "forest_pruned.bmp")
@@ -69,18 +85,15 @@ def seed():
     patchmatch.set_random_seed(0)
 
 
-@pytest.mark.parametrize("as_array", [False, True], ids=["pil", "numpy"])
-def test_remove_white_regions(pruned_image, tmp_path, as_array):
+def test_remove_white_regions(tmp_path):
     """examples/py_example.py: white pixels are the holes, the result is saved."""
-    image = np.array(pruned_image) if as_array else pruned_image
-
-    result = patchmatch.inpaint(image, patch_size=3)
+    source, result = fill("forest_pruned.bmp", None, 3)
 
     output = tmp_path / "forest_recovered.bmp"
     Image.fromarray(result).save(output)
     saved = np.array(Image.open(output))
     np.testing.assert_array_equal(saved, result)
-    assert_plausible_fill(np.array(pruned_image), saved)
+    assert_plausible_fill(source, saved)
 
 
 def test_global_mask(pruned_image):
@@ -117,14 +130,10 @@ def test_global_mask_is_not_used_as_source(pruned_image):
     np.testing.assert_array_equal(result[excluded], source[excluded])
 
 
-def test_fill_is_as_detailed_as_its_surroundings(pruned_image):
+def test_fill_is_as_detailed_as_its_surroundings():
     """The weighted mean of all overlapping patches blurred the fill (detail 0.69)."""
-    source = np.array(pruned_image)
-    holes = evaluation.white(source)
-
-    result = patchmatch.inpaint(source, patch_size=3)
-
-    assert evaluation.measure(result, holes)["detail"] > 0.8
+    source, result = fill("forest_pruned.bmp", None, 3)
+    assert evaluation.measure(result, evaluation.white(source))["detail"] > 0.8
 
 
 @pytest.mark.parametrize(
@@ -142,14 +151,8 @@ def test_no_seam_at_the_hole_border(image, hole, patch_size, limit):
     side of it (seam 2.03). Keeping them still left the colors of the fill off along
     the border: seam 1.73 for forest with patch size 3, 3.24 for chelsea with 15.
     """
-    source = evaluation.load(IMAGES / image)
-    if hole is not None:
-        source[evaluation.ellipse(source.shape, *hole)] = 255
-    holes = evaluation.white(source)
-
-    result = patchmatch.inpaint(source, patch_size=patch_size)
-
-    assert evaluation.measure(result, holes)["seam"] < limit
+    source, result = fill(image, hole, patch_size)
+    assert evaluation.measure(result, evaluation.white(source))["seam"] < limit
 
 
 @pytest.mark.parametrize(
@@ -176,16 +179,14 @@ def test_stem_is_filled_with_meadow(pruned_image, seed, use_global_mask):
     assert result[stem].mean() > 0.85 * source[beside].mean()
 
 
-@pytest.mark.parametrize("hole_value", [1, 255])
-def test_explicit_mask_matches_implicit_white_mask(pruned_image, hole_value):
+def test_explicit_mask_matches_implicit_white_mask(pruned_image):
     """README: an explicit mask behaves like the default mask of white pixels."""
     holes = evaluation.white(np.array(pruned_image))
-    mask = Image.fromarray(holes.astype(np.uint8) * hole_value)
+    mask = Image.fromarray(holes.astype(np.uint8) * 255)
 
     explicit = patchmatch.inpaint(pruned_image, mask, patch_size=3)
-    implicit = patchmatch.inpaint(pruned_image, patch_size=3)
 
-    np.testing.assert_array_equal(explicit, implicit)
+    np.testing.assert_array_equal(explicit, fill("forest_pruned.bmp", None, 3)[1])
 
 
 # Regions of pure background in forest_pruned.bmp as (y, x, height, width).

{pypatchmatch-2.1.1 → pypatchmatch-2.2.0b1}/tests/test_patch_match.py

@@ -112,23 +112,9 @@ def test_inpaint_explicit_mask(image, hole_mask):
 def test_inpaint_global_mask(image, hole_mask):
     global_mask = np.zeros_like(hole_mask)
     global_mask[:8] = 1
-    result = patchmatch.inpaint(image, global_mask=global_mask, patch_size=3)
-    assert_filled(result, image)
-    # excluded pixels keep their values instead of the zeros of the pyramid
-    np.testing.assert_array_equal(result[:8], image[:8])
-
-
-def test_inpaint_ignores_colors_under_global_mask(image, hole_mask):
-    global_mask = np.zeros_like(hole_mask)
-    global_mask[16:32, :24] = 1  # touches the hole
-    results = []
-    for color in (0, 255):
-        image[global_mask == 1] = color
-        patchmatch.set_random_seed(0)
-        results.append(
-            patchmatch.inpaint(image, hole_mask, global_mask=global_mask, patch_size=3)
-        )
-    np.testing.assert_array_equal(results[0][HOLE], results[1][HOLE])
+    assert_filled(
+        patchmatch.inpaint(image, global_mask=global_mask, patch_size=3), image
+    )
 
 
 @pytest.mark.parametrize("shape", [(0, 0, 3), (0, 10, 3), (10, 0, 3)])
@@ -224,6 +210,24 @@ def test_inpaint_textures_the_image_border(patch_size, transpose):
     assert outermost > 0.5 * known, outermost / known
 
 
+def test_inpaint_continues_a_repeating_pattern():
+    """A hole over the center of concentric rings that repeat every 64 pixels.
+
+    The 7x7 patches of patch_size 3 were smaller than the hole on its coarsest
+    level, so they filled it from several shifted copies (error 56 to 60).
+    """
+    palette = np.array([[230, 60, 90], [40, 70, 140], [250, 240, 190], [90, 200, 190]])
+    y, x = np.mgrid[0:128, 0:128]
+    rings = np.hypot(y % 64 - 32, x % 64 - 32) // 8
+    image = palette[rings.astype(int) % 4].astype(np.uint8)
+    mask = (np.hypot(y - 96, x - 96) < 20).astype(np.uint8)
+
+    result = patchmatch.inpaint(image, mask, patch_size=3)
+
+    error = np.abs(result.astype(int) - image)[mask == 1].mean()
+    assert error < 5, error
+
+
 @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):
@@ -255,14 +259,6 @@ def test_inpaint_does_not_modify_inputs(image, hole_mask):
     np.testing.assert_array_equal(hole_mask, mask_before)
 
 
-def test_inpaint_is_deterministic_with_seed(image):
-    patchmatch.set_random_seed(42)
-    first = patchmatch.inpaint(image, patch_size=3)
-    patchmatch.set_random_seed(42)
-    second = patchmatch.inpaint(image, patch_size=3)
-    np.testing.assert_array_equal(first, second)
-
-
 def test_concurrent_inpaint_is_deterministic(image):
     # the native code runs without the GIL, so the threads really overlap
     expected = patchmatch.inpaint(image, patch_size=3)
@@ -475,6 +471,52 @@ def test_native_rejects_negative_guide_weight(image, hole_mask, ijmap):
         patch_match._call(lib.PM_inpaint_regularity, *args)
 
 
+@pytest.mark.parametrize(
+    ("argument", "value"),
+    [
+        ("image", np.zeros((HEIGHT, WIDTH, 3), dtype=np.float32)),
+        ("image", np.zeros((HEIGHT, WIDTH, 4), dtype=np.uint8)),
+        ("mask", np.zeros((HEIGHT, WIDTH, 3), dtype=np.uint8)),
+        ("mask", np.zeros((HEIGHT // 2, WIDTH, 1), dtype=np.uint8)),
+        ("global_mask", np.zeros((HEIGHT, WIDTH, 1), dtype=np.float32)),
+        ("global_mask", np.zeros((HEIGHT, WIDTH // 2, 1), dtype=np.uint8)),
+        ("ijmap", np.zeros((0, WIDTH, 3), dtype=np.float32)),
+        ("ijmap", np.zeros((HEIGHT, WIDTH, 3), dtype=np.uint8)),
+        ("ijmap", np.zeros((HEIGHT, WIDTH, 1), dtype=np.float32)),
+        ("patch_size", ctypes.c_int(0)),
+        ("patch_size", ctypes.c_int(2**30)),
+    ],
+    ids=[
+        "image-float",
+        "image-rgba",
+        "mask-3-channel",
+        "mask-size",
+        "global-mask-float",
+        "global-mask-size",
+        "ijmap-empty",
+        "ijmap-uint8",
+        "ijmap-1-channel",
+        "patch-size-0",
+        "patch-size-2**30",
+    ],
+)
+def test_native_rejects_invalid_inputs(image, hole_mask, ijmap, argument, value):
+    """The C++ code checks what it indexes, for callers that bypass Python."""
+    args = {
+        "image": image,
+        "mask": hole_mask[..., np.newaxis],
+        "global_mask": np.zeros_like(hole_mask)[..., np.newaxis],
+        "ijmap": ijmap,
+        "patch_size": ctypes.c_int(3),
+        "guide_weight": ctypes.c_float(0.25),
+    }
+    args[argument] = value
+    func = patch_match._get_lib().PM_inpaint2_regularity
+    values = list(args.values())
+    with pytest.raises(RuntimeError, match="Assertion failed"):
+        patch_match._call(func, *values)
+
+
 def test_native_accepts_empty_image():
     # Python returns empty images before the native call; C callers still get an
     # empty result instead of a failure. OpenCV 4.6 returns it with shape (0, 0, 1).