PyPatchMatch 2.0.0rc6__tar.gz → 2.0.2__tar.gz

pypatchmatch-2.0.2/CLAUDE.md

@@ -0,0 +1,158 @@
+# 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/`.
+
+## Project
+
+PyPatchMatch implements PatchMatch based image inpainting (Barnes et al., SIGGRAPH 2009):
+a C++17 library on top of OpenCV core, and a thin Python package that loads it through
+`ctypes`. It is published on PyPI as `PyPatchMatch` (import name `patchmatch`) and used
+by InvokeAI. This repository (`mauwii/PyPatchMatch`) is the maintained fork of
+`invoke-ai/PyPatchMatch`, which derives from `vacancy/PyPatchMatch` and
+`younesse-cv/PatchMatch`.
+
+## Commands
+
+The project is managed with uv (`.python-version` pins 3.12 for the local venv). Building
+needs a C++17 compiler, CMake >= 3.21 and an OpenCV that `find_package(OpenCV)` finds:
+Homebrew `opencv`, `libopencv-dev`, or an installation prefix in `OpenCV_ROOT`.
+
+```sh
+uv sync                                    # .venv, editable install, compiles the library
+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.
+- `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`.
+- CI builds the library with warnings as errors. Locally:
+  `SKBUILD_CMAKE_DEFINE=CMAKE_COMPILE_WARNING_AS_ERROR=ON uv sync --reinstall-package pypatchmatch`.
+
+Build against the same static, core-only OpenCV as the release wheels:
+
+```sh
+export OpenCV_ROOT=/tmp/opencv
+uv run --no-project python scripts/build_opencv.py   # pinned version and SHA-256
+uv sync --reinstall-package pypatchmatch
+```
+
+Other entry points:
+
+- `examples/cpp_example_run.sh` builds the library and `examples/cpp_example.cpp` with
+  CMake into `build/cpp` and runs it. It needs OpenCV `imgcodecs`, so a full OpenCV, not
+  the core-only build of the script.
+- `uv run python examples/py_example.py` (and `py_example_global_mask.py`) write
+  `examples/images/forest_recovered.bmp`, which is git-ignored.
+- `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).
+
+## Architecture
+
+### Layers, in the call order of `patchmatch.inpaint`
+
+1. `patchmatch/__init__.py` re-exports the public API of `patch_match.py` and
+   `__version__` from the generated `_version.py`. `test_top_level_exports` checks that
+   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), 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__`)
+   and `load_library` (argtypes and restype of every `PM_*` function).
+4. `patchmatch/csrc/pyinterface.{h,cpp}` is the `extern "C"` API: the `PM_*` functions,
+   the conversion between `PM_mat_t` and `cv::Mat`, the global settings and the error
+   reporting.
+5. `csrc/inpaint.{h,cpp}`: `Inpainting`, the image pyramid and the EM loop.
+6. `csrc/nnf.{h,cpp}`: `NearestNeighborField` (propagation and random search) and the
+   distance metrics `PatchSSDDistanceMetric` and `RegularityGuidedPatchDistanceMetricV2`.
+7. `csrc/masked_image.{h,cpp}`: `MaskedImage`, an image with its hole mask and optional
+   global mask, down- and upsampling, gradients.
+
+The C++ headers double as the C++ API: `examples/cpp_example.cpp` uses `Inpainting` and
+`PatchSSDDistanceMetric` directly.
+
+### ctypes instead of a CPython extension
+
+The library does not use the CPython ABI, so the wheels are tagged
+`py3-none-<platform>` (`wheel.py-api = "py3"`): one wheel per platform serves all Python
+versions, and cibuildwheel only builds `cp311-*`. Keep `csrc` free of `Python.h`,
+pybind11 or nanobind. The C++ sources are excluded from the wheel (`wheel.exclude`);
+CMake installs the shared library into the package directory.
+
+## Conventions
+
+- Python >= 3.11: keep `from __future__ import annotations`. Ruff targets py311 with the
+  rules B, C4, E, F, I, RUF, SIM, UP and W, and formats at 88 columns. `patchmatch/csrc`
+  is excluded from ruff. C++ is formatted by clang-format (Microsoft style, 120 columns,
+  includes grouped as own header, `<...>`, `"..."`); naming is not checked: `m_`
+  members, `k` constants. Commit a reformat separately and add its hash to
+  `.git-blame-ignore-revs`.
+- The package ships `py.typed`; public functions are fully annotated. mypy checks
+  `patchmatch` and `tests` in strict mode (`[tool.mypy]`); the tests have to use the
+  API correctly but need no annotations of their own. A deliberately wrong argument
+  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.
+- 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.
+- Tests check invariants instead of golden images: holes filled, all other pixels
+  unchanged, determinism with `set_random_seed`, fills that blend in with their
+  surroundings. `test_patch_match.py` and `test_e2e.py` seed through an autouse fixture.
+  Unit tests use a small synthetic image; the `e2e` tests use
+  `examples/images/forest_pruned.bmp` and mirror the workflows of the README and the
+  examples. `test_properties.py` checks the invariants on random inputs with Hypothesis
+  (in the `test` group, so the wheel tests run it too); it seeds inside the tests,
+  because Hypothesis rejects function-scoped fixtures, and has no deadline, because
+  the sanitizer and coverage builds are much slower.
+- The README documents the behavior (mask semantics, `patch_size` as a radius, the
+  fallback installation); update it together with API or installation changes.
+- Commit messages: imperative subject in sentence case without a prefix (e.g. "Reject
+  invalid patch sizes and empty regularity maps"), and a body that explains the reason,
+  with measurements where relevant. Changes go through PRs from branches such as
+  `fix/<topic>`.
+
+## Git and GitHub
+
+- `origin` is `mauwii/PyPatchMatch`, where PRs and releases go; `upstream` is
+  `invoke-ai/PyPatchMatch`. `gh` resolves the default repository to upstream, so pass
+  `-R mauwii/PyPatchMatch`.
+- Releases: creating a GitHub release with a tag like `v2.0.0` (or `v2.0.0rc2` for
+  pre-releases) builds the wheels and publishes them to PyPI.

{pypatchmatch-2.0.0rc6 → pypatchmatch-2.0.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: PyPatchMatch
-Version: 2.0.0rc6
+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,6 +42,12 @@ 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.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)
+with the birdhouses painted out in white, and its result.
+
 ## Installation
 
 ```sh
@@ -93,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.0rc6 → pypatchmatch-2.0.2}/README.md

@@ -12,6 +12,12 @@ 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](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)
+with the birdhouses painted out in white, and its result.
+
 ## Installation
 
 ```sh
@@ -63,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.0rc6 → 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.0rc6'
-__version_tuple__ = version_tuple = (2, 0, 0, 'rc6')
+__version__ = version = '2.0.2'
+__version_tuple__ = version_tuple = (2, 0, 2)
 
-__commit_id__ = commit_id = 'g7cfa5cb5b'
+__commit_id__ = commit_id = 'g38b611eb9'

{pypatchmatch-2.0.0rc6 → 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.0rc6 → 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.0rc6 → 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.0rc6 → pypatchmatch-2.0.2}/pyproject.toml

@@ -1,11 +1,10 @@
 [build-system]
 build-backend = "scikit_build_core.build"
-requires = ["scikit-build-core>=0.11", "setuptools-scm>=8"]
+requires = ["scikit-build-core>=0.11.2", "setuptools-scm>=8"]
 
 [project]
 name = "PyPatchMatch"
 description = "This library implements the PatchMatch based inpainting algorithm."
-readme = "README.md"
 license = "MIT"
 license-files = ["LICENSE"]
 authors = [
@@ -34,7 +33,7 @@ classifiers = [
     "Typing :: Typed",
 ]
 dependencies = ["numpy>=1.23.2", "pillow>=9.2.0"]
-dynamic = ["version"]
+dynamic = ["version", "readme"]
 
 [project.urls]
 "Source Code" = "https://github.com/mauwii/PyPatchMatch"
@@ -56,6 +55,7 @@ wheel.py-api = "py3"
 wheel.packages = ["patchmatch"]
 wheel.exclude = ["patchmatch/csrc/**"]
 metadata.version.provider = "scikit_build_core.metadata.setuptools_scm"
+metadata.readme.provider = "scikit_build_core.metadata.fancy_pypi_readme"
 # The release wheels are built from the sdist, so it has to contain the tests
 # and their input image; _version.py is generated and therefore git-ignored.
 sdist.include = ["examples/images/forest_pruned.bmp", "patchmatch/_version.py"]
@@ -70,6 +70,17 @@ if.from-sdist = true
 if.failed = true
 wheel.cmake = false
 
+[tool.hatch.metadata.hooks.fancy-pypi-readme]
+content-type = "text/markdown"
+
+[[tool.hatch.metadata.hooks.fancy-pypi-readme.fragments]]
+path = "README.md"
+
+# PyPI does not resolve relative image paths
+[[tool.hatch.metadata.hooks.fancy-pypi-readme.substitutions]]
+pattern = '!\[([^\]]*)\]\((?!https?:)([^)]+)\)'
+replacement = '![\1](https://raw.githubusercontent.com/mauwii/PyPatchMatch/v$HFPR_VERSION/\2)'
+
 [tool.setuptools_scm]
 version_file = "patchmatch/_version.py"
 # used when building without git metadata, e.g. from a GitHub source archive

{pypatchmatch-2.0.0rc6 → pypatchmatch-2.0.2}/scripts/build_opencv.py

@@ -5,8 +5,8 @@ wheels small and free of OpenCV's GUI/codec dependencies.
 
 Usage: python build_opencv.py  (installs into $OpenCV_ROOT)
 
-PATCHMATCH_OPENCV_VERSION selects another pinned version, which CI tests because
-builds from the sdist link whatever OpenCV the system has.
+PATCHMATCH_OPENCV_VERSION selects another pinned version, e.g. 4.14.0 to rebuild the
+wheels of PyPatchMatch 2.0.0.
 """
 
 import hashlib
@@ -27,7 +27,7 @@ OPENCV_SHA256S = {
     "5.0.0": "b0528f5a1d379d59d4701cb28c36e22214cc51cf64594e5b56f2d3e6c0233095",
 }
 # the version of the release wheels
-OPENCV_VERSION = os.environ.get("PATCHMATCH_OPENCV_VERSION") or "4.14.0"
+OPENCV_VERSION = os.environ.get("PATCHMATCH_OPENCV_VERSION") or "5.0.0"
 if OPENCV_VERSION not in OPENCV_SHA256S:
     sys.exit(f"OpenCV {OPENCV_VERSION} is not pinned, known: {sorted(OPENCV_SHA256S)}")
 OPENCV_SHA256 = OPENCV_SHA256S[OPENCV_VERSION]
@@ -73,6 +73,8 @@ CMAKE_OPTIONS = {
     "WITH_QT": "OFF",
     "WITH_TIFF": "OFF",
     "WITH_V4L": "OFF",
+    # an installed VTK adds OpenGL to the link interface of core (OpenCV 5)
+    "WITH_VTK": "OFF",
     "WITH_WEBP": "OFF",
     "WITH_IPP": "OFF",
     "WITH_ITT": "OFF",
@@ -90,6 +92,8 @@ WINDOWS_CMAKE_OPTIONS = {
     "OPENCV_CONFIG_INSTALL_PATH": "cmake",
     "OPENCV_INSTALL_BINARIES_PREFIX": "",
     "OPENCV_SKIP_CMAKE_ROOT_CONFIG": "ON",
+    # skips OpenCV 5's assembler check: MinGW's would set MINGW and link pthread
+    "CMAKE_ASM_COMPILER": "CMAKE_ASM_COMPILER-NOTFOUND",
 }
 
 
@@ -159,8 +163,10 @@ def main() -> None:
         return
 
     cmake = find_cmake()
-    with tempfile.TemporaryDirectory() as tmp:
-        archive = Path(tmp) / "opencv.tar.gz"
+    with tempfile.TemporaryDirectory() as tmp_name:
+        # OpenCV 5 compares paths as strings, which fails with 8.3 names (RUNNER~1)
+        tmp = Path(tmp_name).resolve()
+        archive = tmp / "opencv.tar.gz"
         print(f"Downloading {OPENCV_URL}", flush=True)
         urllib.request.urlretrieve(OPENCV_URL, archive)
         verify_archive(archive)
@@ -171,8 +177,8 @@ def main() -> None:
             else:
                 tar.extractall(tmp)
 
-        source = Path(tmp) / f"opencv-{OPENCV_VERSION}"
-        build = Path(tmp) / "build"
+        source = tmp / f"opencv-{OPENCV_VERSION}"
+        build = tmp / "build"
         options = {**CMAKE_OPTIONS, "CMAKE_INSTALL_PREFIX": prefix.as_posix()}
         if sys.platform == "win32":
             options.update(WINDOWS_CMAKE_OPTIONS)

pypatchmatch-2.0.2/scripts/render_readme_example.py

@@ -0,0 +1,36 @@
+"""Render examples/images/readme_example.jpg, the picture at the top of the README.
+
+It runs examples/py_example.py and shows, from left to right, the photo forest.bmp,
+the input forest_pruned.bmp with the birdhouses painted out in white, and the result.
+The PyPI description links the picture at the release tag, so rerun the script and
+commit the picture after changes that affect the fills.
+
+Usage:
+    uv run python scripts/render_readme_example.py
+"""
+
+from __future__ import annotations
+
+import runpy
+from pathlib import Path
+
+import numpy as np
+from PIL import Image
+
+import patchmatch
+
+EXAMPLES = Path(__file__).resolve().parents[1] / "examples"
+IMAGES = EXAMPLES / "images"
+
+if __name__ == "__main__":
+    patchmatch.set_random_seed(0)
+    runpy.run_path(str(EXAMPLES / "py_example.py"), run_name="__main__")
+    panels = [
+        np.asarray(Image.open(IMAGES / f"forest{suffix}.bmp"))
+        for suffix in ("", "_pruned", "_recovered")
+    ]
+    gap = np.full((panels[0].shape[0], 8, 3), 255, dtype=np.uint8)
+    picture = np.hstack([panels[0], gap, panels[1], gap, panels[2]])
+    Image.fromarray(picture).save(
+        IMAGES / "readme_example.jpg", quality=85, optimize=True
+    )

{pypatchmatch-2.0.0rc6 → 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 ------------------------------------------------------
 
 

pypatchmatch-2.0.0rc6/CLAUDE.md

@@ -1,479 +0,0 @@
-# CLAUDE.md
-
-This file provides guidance to Claude Code (claude.ai/code) when working with code in
-this repository.
-
-## Project
-
-PyPatchMatch implements PatchMatch based image inpainting (Barnes et al., SIGGRAPH 2009):
-a C++17 library on top of OpenCV core, and a thin Python package that loads it through
-`ctypes`. It is published on PyPI as `PyPatchMatch` (import name `patchmatch`) and used
-by InvokeAI. This repository (`mauwii/PyPatchMatch`) is the maintained fork of
-`invoke-ai/PyPatchMatch`, which derives from `vacancy/PyPatchMatch` and
-`younesse-cv/PatchMatch`.
-
-## Commands
-
-The project is managed with uv (`.python-version` pins 3.12 for the local venv). Building
-needs a C++17 compiler, CMake >= 3.21 and an OpenCV that `find_package(OpenCV)` finds:
-Homebrew `opencv`, `libopencv-dev`, or an installation prefix in `OpenCV_ROOT`.
-
-```sh
-uv sync                                    # .venv, editable install, compiles the library
-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.
-- `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`.
-- CI builds the library with warnings as errors. Locally:
-  `SKBUILD_CMAKE_DEFINE=CMAKE_COMPILE_WARNING_AS_ERROR=ON uv sync --reinstall-package pypatchmatch`.
-
-Build against the same static, core-only OpenCV as the release wheels:
-
-```sh
-export OpenCV_ROOT=/tmp/opencv
-uv run --no-project python scripts/build_opencv.py   # pinned version and SHA-256
-uv sync --reinstall-package pypatchmatch
-```
-
-ASan and UBSan, like the CI job `sanitizers` (Linux):
-
-```sh
-SKBUILD_CMAKE_DEFINE=PATCHMATCH_SANITIZE=ON uv sync --reinstall-package pypatchmatch
-ASAN="$(gcc -print-file-name=libasan.so) $(gcc -print-file-name=libstdc++.so)"
-ASAN_OPTIONS=detect_leaks=0 uv run env LD_PRELOAD="$ASAN" pytest --no-cov --capture=sys
-uv sync --reinstall-package pypatchmatch             # back to the normal library
-```
-
-- Python is not instrumented, so the ASan runtime has to be loaded at startup; without
-  it every test aborts with `Interceptors are not working`. On Linux `libstdc++` has to
-  follow it: ASan looks up the real `__cxa_throw` at startup, and without it the first
-  C++ exception aborts with `CHECK failed: ... real___cxa_throw`. The leak check would
-  report the interpreter's own allocations.
-- `--capture=sys` is required: pytest's default capture of the file descriptors keeps
-  the report of an abort, and only `Fatal Python error: Aborted` reaches the terminal.
-- On macOS, inject the runtime with
-  `DYLD_INSERT_LIBRARIES="$(xcrun clang -print-resource-dir)/lib/darwin/libclang_rt.asan_osx_dynamic.dylib"`,
-  add `strip_env=0` to `ASAN_OPTIONS` (ASan removes the variable, and the tests that
-  start a subprocess abort), and start pytest as `.venv/bin/python .venv/bin/pytest`:
-  SIP drops the variable for `/usr/bin/env` and `/bin/sh`, which uv uses as the
-  shebang of scripts in long paths.
-- The run takes about 80 s locally. Calling `PM_inpaint` through ctypes with a shape
-  larger than the buffer (ASan) or a `patch_size` of `2**31 - 1` (UBSan, `nnf.cpp`)
-  shows that both report and abort.
-
-C++ coverage, like the CI job `coverage` (gcovr comes from the `coverage` group):
-
-```sh
-SKBUILD_CMAKE_DEFINE=PATCHMATCH_COVERAGE=ON uv sync --reinstall-package pypatchmatch
-find build -name '*.gcda' -delete                    # the counts add up across runs
-uv run --group coverage pytest --no-cov
-uv run --group coverage gcovr --filter patchmatch/csrc/ --print-summary \
-    --exclude-throw-branches --exclude-unreachable-branches \
-    --gcov-suspicious-hits-threshold 0
-uv sync --reinstall-package pypatchmatch             # back to the normal library
-```
-
-- The Python tests are the C++ tests: there is no C++ test framework, the coverage of
-  the native code is measured while they run.
-- The build uses `-Og` with atomic counters (a test inpaints in several threads at once);
-  the run takes about 90 s locally. `-O0` reports one more line (the masked branch of
-  `MaskedImage::upsample`, which `-Og` merges) but triples the time. The distance loop
-  runs more than 2**32 times, which gcovr rejects as a gcov bug without
-  `--gcov-suspicious-hits-threshold 0`.
-- On macOS add `--gcov-executable "xcrun llvm-cov gcov"`. Clang's counts are not
-  reliable: they report a closing brace after a `return` as a missed line, and hundreds
-  of millions of returns through the clamp at the end of `distance_masked_images`,
-  which recomputing the distances showed to be unreachable. Judge by GCC (the CI job,
-  or Docker with `ubuntu:24.04`).
-- Missed on purpose: the `catch (...)` blocks of `guarded()` and `set_last_error()`,
-  the `clone()` of a non-continuous result in `_cv2_to_py`, the clamps at the end of
-  `distance_masked_images` and for targets outside the image in
-  `RegularityGuidedPatchDistanceMetricV2`, and the masked branch of
-  `MaskedImage::upsample` (only called on targets, which have no holes). GCC also
-  reports the closing braces of the functions that return a `MaskedImage`, where it
-  puts the cleanup for exceptions.
-- GCC 13 (Docker arm64, `-Og`): 97.0 % of the lines, 95.2 % of the branches. The gates
-  are these values rounded down to 5 % with at least two points of margin.
-
-Fill quality (`scripts/evaluate_inpainting.py`, its docstring explains the columns):
-
-```sh
-uv run --no-sync python scripts/evaluate_inpainting.py --baseline <library of main>
-uv run --no-sync python scripts/evaluate_inpainting.py --patch-size 15 --seeds 1 \
-    --cases forest,brick
-```
-
-- It cuts holes into `forest.bmp` and the CC0 images of `examples/images` (sources in
-  `SOURCES.md`) and adds `forest_pruned.bmp` and every `*_pruned.*` of the git-ignored
-  `examples/images/local/` as object removals without a ground truth. That folder is
-  for your own images; never commit them.
-- For `--baseline`, build the library of `main` outside the checkout:
-
-  ```sh
-  mkdir -p /tmp/main-lib
-  git archive main CMakeLists.txt patchmatch/csrc | tar -x -C /tmp/main-lib
-  cmake -S /tmp/main-lib -B /tmp/main-lib/build -DCMAKE_BUILD_TYPE=Release
-  cmake --build /tmp/main-lib/build   # libpatchmatch.so, .dylib or patchmatch.dll
-  ```
-
-- Judge changes on all cases and look at the fills in `examples/images/evaluation.html`
-  (git-ignored, it embeds the images of `examples/images/local/` too): fixes for one
-  image regressed others before.
-
-Other entry points:
-
-- `examples/cpp_example_run.sh` builds the library and `examples/cpp_example.cpp` with
-  CMake into `build/cpp` and runs it. It needs OpenCV `imgcodecs`, so a full OpenCV, not
-  the core-only build of the script.
-- `uv run python examples/py_example.py` (and `py_example_global_mask.py`) write
-  `examples/images/forest_recovered.bmp`, which is git-ignored.
-- 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).
-- The fallback wheel of the CI job `sdist-fallback`:
-  `uv build --wheel dist/<sdist>.tar.gz --out-dir fallback -C cmake.define.CMAKE_DISABLE_FIND_PACKAGE_OpenCV=ON`
-  must produce a `py3-none-any` wheel with the Python package but without the library.
-
-## Architecture
-
-### Layers, in the call order of `patchmatch.inpaint`
-
-1. `patchmatch/__init__.py` re-exports the public API of `patch_match.py` and
-   `__version__` from the generated `_version.py`. `test_top_level_exports` checks that
-   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()`.
-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__`)
-   and `load_library` (argtypes and restype of every `PM_*` function).
-4. `patchmatch/csrc/pyinterface.{h,cpp}` is the `extern "C"` API: the `PM_*` functions,
-   the conversion between `PM_mat_t` and `cv::Mat`, the global settings and the error
-   reporting.
-5. `csrc/inpaint.{h,cpp}`: `Inpainting`, the image pyramid and the EM loop.
-6. `csrc/nnf.{h,cpp}`: `NearestNeighborField` (propagation and random search) and the
-   distance metrics `PatchSSDDistanceMetric` and `RegularityGuidedPatchDistanceMetricV2`.
-7. `csrc/masked_image.{h,cpp}`: `MaskedImage`, an image with its hole mask and optional
-   global mask, down- and upsampling, gradients.
-
-The C++ headers double as the C++ API: `examples/cpp_example.cpp` uses `Inpainting` and
-`PatchSSDDistanceMetric` directly.
-
-### ctypes instead of a CPython extension
-
-The library does not use the CPython ABI, so the wheels are tagged
-`py3-none-<platform>` (`wheel.py-api = "py3"`): one wheel per platform serves all Python
-versions, and cibuildwheel only builds `cp311-*`. Keep `csrc` free of `Python.h`,
-pybind11 or nanobind. The C++ sources are excluded from the wheel (`wheel.exclude`);
-CMake installs the shared library into the package directory.
-
-### The C interface contract
-
-A change on one side has to be mirrored on the other:
-
-- `PM_mat_t`/`PM_shape_t` in `pyinterface.h` and `CMatT`/`CShapeT` in `_lib.py` (field
-  order and types).
-- The order of `PM_dtype_e` and of the `_PYMAT_DTYPES` list: uint8 and float32, the
-  only types the native code reads; `_py_to_cv2` rejects others.
-- Every `PM_*` function needs its `argtypes` and `restype` in `load_library()`; without
-  them ctypes silently assumes `int`.
-- Symbols are exported by `extern "C"` and `CMAKE_WINDOWS_EXPORT_ALL_SYMBOLS`, there are
-  no export macros.
-
-A new entry point is declared in `pyinterface.h`, implemented in `pyinterface.cpp`
-inside `guarded(...)`, registered in `load_library()` and called through `_call()`.
-
-Memory ownership: `np_to_pymat` wraps a C-contiguous array without copying it, so
-callers convert with `np.ascontiguousarray` first and keep the array alive during the
-call. `_py_to_cv2` clones it into a `cv::Mat`, so the inputs are never modified.
-`_cv2_to_py` hands a heap buffer (a released `std::unique_ptr<unsigned char[]>`) to
-Python; `pymat_to_np` copies it, and `_call` always returns it through `PM_free_pymat` in
-a `finally`. It allocates at least one byte, because a null `data_ptr` signals failure.
-
-Errors: a C++ exception that reaches ctypes aborts the process. `guarded()` catches
-everything, stores the message in a thread-local string and returns a null `data_ptr`;
-`_call` turns that into `RuntimeError("patchmatch failed: <PM_last_error()>")`. Most
-input validation lives in Python because the native code crashes or hangs on bad input:
-`patch_size` 0 crashes, negative sizes never terminate, sizes >= 2**31 wrap to negative
-C ints, negative guide weights index outside the similarity table, NaN or infinity in the
-`ijmap` produce out-of-range distances. `RegularityGuidedPatchDistanceMetricV2` also
-throws on a negative weight, for C++ callers.
-
-### Threading and determinism
-
-ctypes releases the GIL during native calls, so inpaintings run truly concurrently
-(`test_concurrent_inpaint_is_deterministic`). Therefore:
-
-- The seed and the verbose flag are `std::atomic` globals, read when a call starts.
-- The random generator is a function-local `thread_local std::mt19937`, seeded at the
-  start of every `Inpainting::run`, so each call is reproducible from the seed on any
-  thread.
-- `random_int` uses `engine() % n` instead of `std::uniform_int_distribution` to keep
-  the sequence identical on all platforms and standard libraries. Keep it that way.
-- Lookup tables are function-local statics (thread-safe initialization). Do not add
-  mutable shared state.
-
-### Algorithm
-
-- `patch_size` is a radius: patches span `(2 * patch_size + 1)` pixels in each
-  direction. The pyramid halves the image until one side is <= `patch_size`.
-- From the coarsest level to the finest, two nearest-neighbor fields are kept:
-  source to target (completeness) and target to source (coherence). They start random
-  at the coarsest level and are upscaled from the previous level afterwards, keeping the
-  offset within the coarse pixel so that neighbors still point to neighbors.
-- Each level runs `1 + 2 * level` EM iterations with `min(7, 1 + level)` NNF passes
-  (propagation and random search), an expectation step (votes of both fields, weighted
-  through the `distance2similarity` table) and a maximization step, which sets each
-  pixel to the weighted mean of its votes. On levels 0 and 1 the known pixels keep their
-  input values instead; without that the votes change the pixels around the holes, and a
-  seam appears when `run()` restores them. On coarser levels the known pixels next to
-  the holes are averages of partially masked kernels, and keeping them made fills copy
-  smooth regions into textured ones (57 % instead of 17 % of the fill in one case). The
-  last iteration of a level votes directly into the upsampled image of the next level,
-  which is less blurry than upsampling the result. The last iteration at level 0 keeps
-  only the heaviest vote of each pixel instead of the mean, which blurs.
-- The coarse levels mark a pixel as a hole only if its whole downsampling kernel is
-  one, so the holes shrink quickly and are filled smoothly from their border; the finer
-  levels add the texture. Marking every pixel that touches a hole instead was tried and
-  made the fills worse: it leaves the coarsest levels without valid source patches,
-  because the similarity table gives zero weight to patches with more than about 10 %
-  masked or border pixels.
-- A hole, and later each thin part of it, therefore has a level on which it appears for
-  the first time. The patches around it arrive there with the link of a patch without
-  holes, the one to itself, which now points into the hole. `_initialize_field_from`
-  runs a random search around such a patch before the first pass. Otherwise the first
-  propagation replaces the link with the one of a neighbor, the random search goes on
-  around that link, and with a radius of half the smaller image side it does not find
-  the way back to the surroundings of the patch: the stem of `forest_pruned.bmp` was
-  filled with forest instead of meadow in 31 of 200 seeds (36 of 48 with `patch_size`
-  7), and the `meadow` case had an error above 12 in 9 of 96 seeds, now at most 9.7
-  (`test_inpaint_thin_hole_takes_the_colors_beside_it`). Tried and rejected: searching
-  before propagating in every pass, which no longer refines a propagated link, the way
-  a structure is followed along a hole (brick error +9 %); and a search radius of the
-  larger image side, as in the paper, which blurs the fills (coffee detail 0.30 instead
-  of 0.53).
-- Distances are ints in `[0, PatchDistanceMetric::kDistanceScale]` (65535): an SSD over
-  the colors and the x/y gradients, where masked pixels and pixels at the border count
-  as maximal. The distance indexes `distance2similarity`, so every metric has to clamp
-  its result to that range.
-- Mask semantics: `mask` non-zero marks the holes (by default all pure white pixels,
-  computed in Python by `_default_mask`); `_initialize_pyramid` makes them black on
-  level 0 as on the coarser levels, so their colors do not matter
-  (`test_colors_under_the_holes_do_not_matter`); `global_mask` marks pixels that are
-  neither filled nor used as a patch source, and whose colors must not influence the
-  fill: the downsampling kernel skips them, and gradients next to them are neutral
-  (`test_colors_under_global_mask_do_not_matter`). At the end of `run()` every pixel
-  that is not a hole, including the globally masked ones, is copied back from the input,
-  so only the holes change. The tests assert this invariant (`assert_filled`,
-  `assert_plausible_fill`).
-
-### OpenCV usage and library size
-
-The release wheels link a static, core-only OpenCV (`scripts/build_opencv.py`:
-`BUILD_LIST=core`, every optional backend off). For changes to the C++ code:
-
-- The library links only `opencv_core`; `imgcodecs` is only used by the example.
-- Use plain pixel loops instead of `cv::Mat` matrix expressions such as `a == b` or
-  `m1 | m2`: they pull OpenCV's expression module, and with it `FileStorage`, PCA and
-  `SparseMat` code, into the static library, which grew by about 40 % before commit
-  e50c613 replaced them.
-- On Windows the static OpenCV uses the static MSVC runtime (`BUILD_WITH_STATIC_CRT`),
-  so the library does too (`MSVC_RUNTIME_LIBRARY` in `CMakeLists.txt`). Its stderr is
-  then not captured by pytest's `capfd`, so tests of native output run in a subprocess
-  (`test_set_verbose_prints_progress`).
-- With a static OpenCV, CMake installs its licenses, which the build script collects in
-  `<prefix>/licenses`, into `.dist-info/licenses/opencv` of the wheel, and the CycloneDX
-  SBOM it writes to `<prefix>/sboms/opencv.cdx.json` into `.dist-info/sboms` (PEP 770).
-  The static library hides OpenCV from scanners; grype matches the SBOM through its CPE.
-- The SBOM leaves out OpenCV's bundled zlib: only `FileStorage` uses it, and none of it
-  is linked into the library. The wheel job checks that every wheel has the SBOM and,
-  except on Windows, that `nm` finds no zlib symbol in the library. `write_sbom` fails
-  if the build bundles another 3rdparty library; add a new one to the SBOM.
-- To update OpenCV, change the default of `OPENCV_VERSION` and add its hash to
-  `OPENCV_SHA256S`. `PATCHMATCH_OPENCV_VERSION` selects another pinned version: the
-  CI job `opencv5` builds against OpenCV 5 (Homebrew's `opencv` since 2026), because
-  builds from the sdist link whatever OpenCV the system has. The CI cache of the
-  OpenCV build is keyed on the hash of the script.
-
-### Packaging and versioning
-
-- Build backend: scikit-build-core with setuptools-scm. The version comes from the git
-  tags; `patchmatch/_version.py` is generated and git-ignored. Without git metadata the
-  version falls back to `0.0.0`, so CI checks out with `fetch-depth: 0`.
-- The release wheels are built from the sdist, not from the checkout, and cibuildwheel
-  runs `pytest {project}/tests --no-cov` against the sdist contents. Everything the tests
-  need has to be in the sdist: `sdist.include` adds `examples/images/forest_pruned.bmp`,
-  the rest of `examples/` is excluded. New test data has to be added there as well.
-- Fallback: if a build from the sdist fails (e.g. no compiler, CMake or OpenCV on a
-  platform without a wheel), the `tool.scikit-build.overrides` entry builds a pure wheel
-  without the library, so the installation succeeds with `patchmatch_available` False and
-  the error message of `find_library` explains how to reinstall. Builds from the source
-  tree still fail. The CI job `sdist-fallback` and `test_import_without_native_library`
-  keep this path working.
-- Wheels: manylinux x86_64 and aarch64, macOS arm64 and x86_64 (deployment target 11.0),
-  Windows x64. musllinux is skipped.
-
-## CI
-
-- `ci.yml`: `lint` runs `pre-commit run --all-files`; `test` runs `uv run pytest` on
-  Ubuntu, macOS and Windows with Python 3.11, 3.14 and 3.15, after building (or
-  restoring) the OpenCV of the build script. It syncs only the `test` group: the `dev`
-  group pulls in pyyaml through pre-commit, which had no wheel for 3.15 yet, and
-  `--no-build` refuses to build it.
-- pre-commit runs, besides the file checks, ruff and uv-lock: clang-format
-  (`.clang-format`), shellcheck, markdownlint-cli2 (`.markdownlint.yaml`, 88 columns),
-  typos (fixes in place), actionlint (checks `run:` scripts with shellcheck only if it
-  is on `PATH`) and zizmor (offline, default persona), and mypy as a local hook
-  (`uv run --locked --no-build --only-group dev mypy`, like the `lint` job, so the
-  library is not built; numpy and pillow are in the `dev` group for their types).
-  MegaLinter was considered and rejected: it duplicates pre-commit in a multi-GB Docker
-  image and bundles the linter versions instead of pinning each hook for Dependabot.
-- Dependabot waits 7 days after a release (`cooldown`, required by zizmor).
-- `test` sets `SKBUILD_CMAKE_DEFINE=CMAKE_COMPILE_WARNING_AS_ERROR=ON`, so the warning
-  flags of `CMakeLists.txt` (`-Wall -Wextra -Wpedantic -Wshadow`, `/W4` on MSVC) fail the
-  build. Only there: builds from the sdist and the wheels must not break when a newer
-  compiler adds a warning. The OpenCV headers are system includes and do not count.
-- `sanitizers` builds with `PATCHMATCH_SANITIZE=ON` on Ubuntu and runs the tests with
-  the preloaded ASan runtime (see Commands). It reuses the checkout and OpenCV steps of
-  `test` through YAML anchors, so change them there.
-  Scheduled (nightly) and manual runs of `ci.yml` pass `--hypothesis-profile=deep`
-  (`tests/conftest.py`: 5000 examples per property test, about 90 s locally without
-  sanitizers) and allow the job 90 minutes; a failure prints a `@reproduce_failure`
-  blob. The property tests found real bugs, so they get the most search time.
-- `coverage` builds with `PATCHMATCH_COVERAGE=ON` on Ubuntu, runs the tests and fails
-  below 95 % of the C++ lines or 90 % of the branches (gcovr, see Commands).
-  It reuses the same anchors. It also writes `coverage.xml` (Python) and
-  `coverage-cpp.xml` (`gcovr --sonarqube`) and exports `build/compile_commands.json`,
-  and then runs the SonarCloud scan (`sonar-project.properties`, `SONAR_TOKEN`, skipped
-  without the secret, e.g. for Dependabot and forks). Automatic analysis in SonarCloud
-  is disabled; it cannot import coverage and would conflict with the CI scan. `scripts/`
-  has no tests and is excluded from the coverage on new code (80 % in "Sonar way").
-  `sonar.qualitygate.wait=true` makes the scan fail on a red quality gate, so the gate
-  is part of `ci-ok` and auto-merge waits for it; the skipped scan of Dependabot and
-  fork PRs blocks nothing, unlike a required "SonarCloud Code Analysis" check, which
-  would never appear there.
-- The `uv run` steps pass `--locked` and `--no-build` (SonarCloud S8544, S8541).
-  `--no-build` only forbids building dependencies from source; uv still builds the
-  project itself. The OpenCV step runs with `--only-group test`: the project cannot be
-  built before OpenCV is installed, `--no-project` would lock nothing, and the `dev`
-  group may lack wheels for the newest Python of the matrix.
-- Every setup-uv step sets `version: latest-known`: the newest uv whose checksum is
-  bundled with the pinned setup-uv. Without it, CI installs each uv release minutes
-  after publication; this way uv only moves when Dependabot updates the action, with
-  its cooldown. That uv can be a few releases older than the one of the `uv-lock` hook.
-  `prune-cache: true` keeps only wheels built from source in the uv cache; downloaded
-  wheels restore no faster than they download.
-- `system-opencv` installs `libopencv-dev` on `ubuntu-24.04` (OpenCV 4.6) instead of
-  running the build script and runs the tests, because builds from the sdist link
-  whatever OpenCV the system has. The runner is pinned so that the OpenCV version only
-  changes on purpose. The Ubuntu mirror is sometimes very slow (180 MB at under
-  300 kB/s), so the job caches the downloaded `.deb` files, keyed on the hash of
-  `apt-get install --print-uris`, with `restore-keys` for the files that did not change.
-  apt checks them against the signed index and dpkg installs them as usual. The job
-  downloads first (`--download-only`) and caches only the files of the current list.
-- `wheels.yml`: sdist, then cibuildwheel on five runners, then `sdist-fallback`;
-  `publish` attests the build provenance of all files (`actions/attest`) and uploads
-  them to PyPI with trusted publishing (environment `pypi`, deployable only from tags
-  `v*`) only for a published GitHub release of `mauwii/PyPatchMatch`. It downloads the
-  artifacts named `dist-*`, so other artifacts of the run never reach PyPI. The wheel
-  jobs cache the OpenCV prefix, keyed on `build_opencv.py` and `pyproject.toml` from the
-  sdist (there is no checkout); on Linux a volume makes `/tmp/opencv` of the container
-  visible to the cache step. Runs on a tag, and therefore releases, skip the cache and
-  build OpenCV from scratch.
-  The build and test dependencies of the distributions are not locked, so the workflow
-  sets `UV_EXCLUDE_NEWER: 7 days` (the cooldown of `dependabot.yml`): `uv build` and
-  cibuildwheel's `build-frontend = "build[uv]"` resolve only releases older than a
-  week. On Linux `environment-pass` hands the variable into the container; on macOS
-  and Windows cibuildwheel uses the uv of a setup-uv step.
-- `fill-quality.yml` runs for pull requests that change `CMakeLists.txt`,
-  `patchmatch/csrc` or the evaluation script: it builds the library of the base commit,
-  runs `scripts/evaluate_inpainting.py --baseline` against it (patch size 3, 3 seeds),
-  writes the table to the job summary (`--markdown`) and uploads `evaluation.html` as the
-  artifact `fill-quality`. It is a report, not a gate: the measures vary over the seeds,
-  so it is not in the `needs` of `ci-ok`. It repeats the OpenCV steps of `ci.yml` with
-  the same cache key, because anchors do not reach across files.
-- `codeql.yml` analyzes actions, C/C++ and Python.
-- `cache-cleanup.yml` deletes the caches of a pull request when it is closed: only that
-  pull request can read them, and at the 10 GB limit GitHub evicts the least recently
-  used caches, often those of `main`. For pull requests from forks the token is
-  read-only; their caches expire after 7 days without access.
-- `ci-ok` and `wheels-ok` (re-actors/alls-green) are the required status checks; add new
-  jobs to their `needs`. The ruleset of `main` also has a `code_scanning` rule: CodeQL
-  alerts of severity error or security severity high and above block the merge (CodeQL
-  uploads its results for Dependabot PRs too, so they are not stuck).
-- Actions are pinned to full commit SHAs with a `# vX.Y.Z` comment, and checkouts use
-  `persist-credentials: false`. The pre-commit hooks are pinned the same way
-  (`rev: <sha>  # frozen: vX.Y.Z`; `pre-commit autoupdate --freeze` by hand), because a
-  moved tag would otherwise reach CI and fresh clones without review. Dependabot
-  updates actions, uv and pre-commit weekly in groups, SHA and comment together. The
-  repository is a GitHub fork, on which Dependabot version updates are off by default;
-  they are enabled in Insights → Dependency graph → Dependabot.
-
-## Conventions
-
-- Python >= 3.11: keep `from __future__ import annotations`. Ruff targets py311 with the
-  rules B, C4, E, F, I, RUF, SIM, UP and W, and formats at 88 columns. `patchmatch/csrc`
-  is excluded from ruff. C++ is formatted by clang-format (Microsoft style, 120 columns,
-  includes grouped as own header, `<...>`, `"..."`); naming is not checked: `m_`
-  members, `k` constants. Commit a reformat separately and add its hash to
-  `.git-blame-ignore-revs`.
-- The package ships `py.typed`; public functions are fully annotated. mypy checks
-  `patchmatch` and `tests` in strict mode (`[tool.mypy]`); the tests have to use the
-  API correctly but need no annotations of their own. A deliberately wrong argument
-  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.
-- 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.
-- Tests check invariants instead of golden images: holes filled, all other pixels
-  unchanged, determinism with `set_random_seed`, fills that blend in with their
-  surroundings. `test_patch_match.py` and `test_e2e.py` seed through an autouse fixture.
-  Unit tests use a small synthetic image; the `e2e` tests use
-  `examples/images/forest_pruned.bmp` and mirror the workflows of the README and the
-  examples. `test_properties.py` checks the invariants on random inputs with Hypothesis
-  (in the `test` group, so the wheel tests run it too); it seeds inside the tests,
-  because Hypothesis rejects function-scoped fixtures, and has no deadline, because
-  the sanitizer and coverage builds are much slower.
-- The README documents the behavior (mask semantics, `patch_size` as a radius, the
-  fallback installation); update it together with API or installation changes.
-- Commit messages: imperative subject in sentence case without a prefix (e.g. "Reject
-  invalid patch sizes and empty regularity maps"), and a body that explains the reason,
-  with measurements where relevant. Changes go through PRs from branches such as
-  `fix/<topic>`.
-
-## Git and GitHub
-
-- `origin` is `mauwii/PyPatchMatch`, where PRs and releases go; `upstream` is
-  `invoke-ai/PyPatchMatch`. `gh` resolves the default repository to upstream, so pass
-  `-R mauwii/PyPatchMatch`.
-- Releases: creating a GitHub release with a tag like `v2.0.0` (or `v2.0.0rc2` for
-  pre-releases) builds the wheels and publishes them to PyPI.