PyPatchMatch 2.1.0__tar.gz → 2.2.0b1__tar.gz

{pypatchmatch-2.1.0 → 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.0 → pypatchmatch-2.2.0b1}/CMakeLists.txt

@@ -57,8 +57,9 @@ if(PATCHMATCH_SANITIZE)
   endif()
   # GCC's -fsanitize=undefined leaves out float-cast-overflow
   set(PATCHMATCH_SANITIZERS -fsanitize=address,undefined,float-cast-overflow)
+  # -UNDEBUG keeps the asserts, which check the incremental distances of the propagation
   target_compile_options(patchmatch PRIVATE ${PATCHMATCH_SANITIZERS}
-    -fno-sanitize-recover=all -fno-omit-frame-pointer -g)
+    -fno-sanitize-recover=all -fno-omit-frame-pointer -g -UNDEBUG)
   target_link_options(patchmatch PRIVATE ${PATCHMATCH_SANITIZERS})
 endif()
 

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: PyPatchMatch
-Version: 2.1.0
+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.0/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.0 → 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.0 → 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.0 → 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.0'
-__version_tuple__ = version_tuple = (2, 1, 0)
+__version__ = version = '2.2.0b1'
+__version_tuple__ = version_tuple = (2, 2, 0, 'b1')
 
-__commit_id__ = commit_id = 'g2f558d40a'
+__commit_id__ = commit_id = 'gb66a4a1d8'

{pypatchmatch-2.1.0 → 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.0 → 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.0 → 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.0 → 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;
 };