patchcraft 0.2.0__py3-none-any.whl

patchcraft/__init__.py

@@ -0,0 +1,39 @@
+"""PatchCraft — image patch extraction, pairing and reconstruction utilities."""
+
+from patchcraft.cache import Cache
+from patchcraft.extract import Patchify, extract
+from patchcraft.geometry import (
+    PairedTilingSpec,
+    TilingSpec,
+    num_patches,
+    paired_tilings,
+    scale_factor,
+    tilings,
+)
+from patchcraft.metrics import patch_metrics, per_patch_mse, per_patch_psnr
+from patchcraft.pair import PatchMeta, PatchPair, pair
+from patchcraft.reconstruct import reconstruct
+from patchcraft.resize import resize
+from patchcraft.stitch import stitch
+
+__version__ = "0.2.0"
+__all__ = [
+    "Cache",
+    "PairedTilingSpec",
+    "PatchMeta",
+    "PatchPair",
+    "Patchify",
+    "TilingSpec",
+    "extract",
+    "num_patches",
+    "pair",
+    "paired_tilings",
+    "patch_metrics",
+    "per_patch_mse",
+    "per_patch_psnr",
+    "reconstruct",
+    "resize",
+    "scale_factor",
+    "stitch",
+    "tilings",
+]

patchcraft/cache.py

@@ -0,0 +1,247 @@
+"""Content-addressed disk cache.
+
+Bytes in, bytes out. Optional ``zstandard`` compression (transparent fallback
+when not installed). Retry on transient ``PermissionError`` from OneDrive,
+antivirus, or the Windows Search indexer. Atomic write via ``*.tmp`` plus
+``os.replace``. Sidecar JSON carries the full key, version, content checksum.
+
+Contract: docs/THEORY.md §4 and §9.5.
+"""
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import time
+from collections.abc import Callable
+from pathlib import Path
+from typing import Any
+
+__all__ = ["Cache"]
+
+_WRITE_BACKOFF: tuple[float, ...] = (0.25, 0.5, 1.0, 2.0, 4.0)
+_READ_BACKOFF: tuple[float, ...] = (0.25,)
+
+
+def _retry[T](
+    op: Callable[[], T],
+    backoff: tuple[float, ...],
+) -> T:
+    """Retry ``op`` on ``PermissionError`` with the given backoff schedule.
+
+    First attempt is immediate; subsequent attempts sleep for
+    ``backoff[i-1]`` seconds. After exhausting the schedule the last
+    ``PermissionError`` is re-raised. All other exceptions propagate
+    immediately.
+    """
+    last: PermissionError | None = None
+    for attempt in range(len(backoff) + 1):
+        try:
+            return op()
+        except PermissionError as exc:
+            last = exc
+            if attempt < len(backoff):
+                time.sleep(backoff[attempt])
+    assert last is not None  # invariant from loop above
+    raise last
+
+
+def _try_zstandard() -> Any | None:
+    try:
+        import zstandard
+    except ImportError:
+        return None
+    return zstandard
+
+
+def _normalize_part(part: Any) -> Any:
+    """Coerce a key-part into something JSON-stable.
+
+    Lists and tuples both serialize as JSON arrays — order matters. Dicts
+    are sorted by key. Bytes are hashed (avoids embedding binary blobs in
+    the key). Anything else falls back to ``repr`` — explicit but uglier."""
+    if isinstance(part, (str, int, float, bool)) or part is None:
+        return part
+    if isinstance(part, (list, tuple)):
+        return [_normalize_part(p) for p in part]
+    if isinstance(part, dict):
+        return {str(k): _normalize_part(v) for k, v in sorted(part.items())}
+    if isinstance(part, bytes):
+        return {"__bytes_sha256__": hashlib.sha256(part).hexdigest()}
+    return {"__repr__": repr(part)}
+
+
+class Cache:
+    """Single-namespace content-addressed cache on disk.
+
+    ``root`` is created on construction if missing. ``namespace`` is used
+    as a subdirectory and as part of the key (so two namespaces never
+    collide even if a caller produces identical key parts). ``version``
+    is the invalidation lever: bump it, and old entries become
+    unreadable by construction without any delete.
+    """
+
+    def __init__(
+        self,
+        root: str | os.PathLike[str],
+        namespace: str,
+        version: int = 1,
+    ) -> None:
+        if not isinstance(namespace, str) or not namespace:
+            raise ValueError(
+                f"namespace must be a non-empty str, got {namespace!r}"
+            )
+        if not isinstance(version, int) or isinstance(version, bool) or version <= 0:
+            raise ValueError(f"version must be a positive int, got {version!r}")
+
+        self._namespace = namespace
+        self._version = version
+        self._root = Path(root) / namespace
+        self._root.mkdir(parents=True, exist_ok=True)
+        self._zstd = _try_zstandard()
+
+    @property
+    def root(self) -> Path:
+        return self._root
+
+    @property
+    def namespace(self) -> str:
+        return self._namespace
+
+    @property
+    def version(self) -> int:
+        return self._version
+
+    def key_for(self, *parts: Any) -> str:
+        """SHA-256 over a canonical JSON of ``parts``, namespace, version."""
+        canonical = {
+            "namespace": self._namespace,
+            "version": self._version,
+            "parts": [_normalize_part(p) for p in parts],
+        }
+        blob = json.dumps(canonical, sort_keys=True, separators=(",", ":")).encode()
+        return hashlib.sha256(blob).hexdigest()
+
+    def _paths(self, key: str) -> tuple[Path, Path]:
+        short = key[:16]
+        return self._root / f"{short}.bin", self._root / f"{short}.json"
+
+    def put(self, key: str, data: bytes) -> None:
+        """Store ``data`` under ``key``. Atomic; retries on transient races."""
+        if not isinstance(key, str):
+            raise TypeError(f"key must be str, got {type(key).__name__}")
+        if not isinstance(data, (bytes, bytearray, memoryview)):
+            raise TypeError(f"data must be bytes-like, got {type(data).__name__}")
+        data_bytes = bytes(data)
+
+        bin_path, sidecar_path = self._paths(key)
+
+        if self._zstd is not None:
+            cctx = self._zstd.ZstdCompressor(level=3)
+            payload = cctx.compress(data_bytes)
+            compressed = True
+        else:
+            payload = data_bytes
+            compressed = False
+
+        checksum = hashlib.sha256(data_bytes).hexdigest()
+        sidecar: dict[str, Any] = {
+            "key": key,
+            "namespace": self._namespace,
+            "version": self._version,
+            "checksum": checksum,
+            "compressed": compressed,
+            "size": len(data_bytes),
+        }
+
+        tmp_bin = bin_path.with_suffix(bin_path.suffix + ".tmp")
+        tmp_side = sidecar_path.with_suffix(sidecar_path.suffix + ".tmp")
+
+        def _write_payload() -> None:
+            with open(tmp_bin, "wb") as f:
+                f.write(payload)
+            os.replace(tmp_bin, bin_path)
+
+        def _write_sidecar() -> None:
+            with open(tmp_side, "w", encoding="utf-8") as f:
+                json.dump(sidecar, f)
+            os.replace(tmp_side, sidecar_path)
+
+        _retry(_write_payload, _WRITE_BACKOFF)
+        _retry(_write_sidecar, _WRITE_BACKOFF)
+
+    def get(self, key: str) -> bytes | None:
+        """Return cached bytes, or ``None`` if absent / version-mismatched.
+
+        Raises ``IOError`` on sidecar/payload mismatch (corrupt entry).
+        """
+        if not isinstance(key, str):
+            raise TypeError(f"key must be str, got {type(key).__name__}")
+
+        bin_path, sidecar_path = self._paths(key)
+        if not (bin_path.exists() and sidecar_path.exists()):
+            return None
+
+        def _read_sidecar() -> dict[str, Any]:
+            with open(sidecar_path, "rb") as f:
+                parsed = json.loads(f.read())
+            if not isinstance(parsed, dict):
+                raise OSError(
+                    f"sidecar at {sidecar_path} is not a JSON object"
+                )
+            return parsed
+
+        try:
+            sidecar = _retry(_read_sidecar, _READ_BACKOFF)
+        except FileNotFoundError:
+            return None
+
+        # Different key collided into the same 16-hex prefix? Treat as miss.
+        if sidecar.get("key") != key:
+            return None
+        # Stale version (cache invalidation lever). Transparent miss.
+        if sidecar.get("version") != self._version:
+            return None
+        if sidecar.get("namespace") != self._namespace:
+            return None
+
+        def _read_payload() -> bytes:
+            with open(bin_path, "rb") as f:
+                return f.read()
+
+        try:
+            payload = _retry(_read_payload, _READ_BACKOFF)
+        except FileNotFoundError:
+            return None
+
+        if sidecar.get("compressed"):
+            if self._zstd is None:
+                raise OSError(
+                    f"cache entry {key[:16]!r} is zstd-compressed but "
+                    "zstandard is not installed in this environment"
+                )
+            dctx = self._zstd.ZstdDecompressor()
+            try:
+                data: bytes = dctx.decompress(payload)
+            except self._zstd.ZstdError as exc:
+                # Compressed-payload corruption manifests here before checksum.
+                raise OSError(
+                    f"cache entry {key[:16]!r} payload corrupt (zstd decode "
+                    f"failed); remove it from {self._root} to invalidate"
+                ) from exc
+        else:
+            data = payload
+
+        if hashlib.sha256(data).hexdigest() != sidecar.get("checksum"):
+            raise OSError(
+                f"cache entry {key[:16]!r} checksum mismatch — corrupt; "
+                f"remove {bin_path.name} and {sidecar_path.name} from "
+                f"{self._root} to invalidate"
+            )
+        return data
+
+    def __repr__(self) -> str:
+        return (
+            f"Cache(root={str(self._root)!r}, namespace={self._namespace!r}, "
+            f"version={self._version})"
+        )

patchcraft/extract.py

@@ -0,0 +1,116 @@
+"""Patch extraction via torch.nn.functional.unfold.
+
+Contract: docs/THEORY.md §1 and §9.1, docs/ADR/0001-patch-extraction-api.md,
+docs/ADR/0002-patchify-transform.md.
+"""
+from __future__ import annotations
+
+import torch
+import torch.nn.functional as F  # noqa: N812 (torch convention)
+
+__all__ = ["Patchify", "extract"]
+
+
+def _as_pair(value: int | tuple[int, int], name: str) -> tuple[int, int]:
+    if isinstance(value, int) and not isinstance(value, bool):
+        if value <= 0:
+            raise ValueError(f"{name} must be positive, got {value}")
+        return (value, value)
+    if isinstance(value, tuple) and len(value) == 2:
+        h, w = value
+        h_ok = isinstance(h, int) and not isinstance(h, bool)
+        w_ok = isinstance(w, int) and not isinstance(w, bool)
+        if not (h_ok and w_ok):
+            raise ValueError(f"{name} must contain ints, got {value!r}")
+        if h <= 0 or w <= 0:
+            raise ValueError(f"{name} must be positive, got {value!r}")
+        return (h, w)
+    raise ValueError(f"{name} must be int or (int, int), got {value!r}")
+
+
+def extract(
+    image: torch.Tensor,
+    patch_size: int | tuple[int, int],
+    stride: int | tuple[int, int],
+    dilation: int | tuple[int, int] = 1,
+) -> torch.Tensor:
+    """Extract rectangular patches from a `(C, H, W)` image.
+
+    Returns `Tensor[L, C, ph, pw]` in row-major order. Patch `k` has its
+    top-left at `(k // num_w * sh, k % num_w * sw)`. Truncation is the only
+    boundary policy: if the geometry fits no patch, returns `Tensor[0, C, ph, pw]`.
+    Dtype and device of `image` are preserved.
+    """
+    if not isinstance(image, torch.Tensor):
+        raise TypeError(f"image must be torch.Tensor, got {type(image).__name__}")
+    if image.ndim != 3:
+        raise ValueError(f"image must have ndim==3 (C, H, W), got ndim={image.ndim}")
+
+    ph, pw = _as_pair(patch_size, "patch_size")
+    sh, sw = _as_pair(stride, "stride")
+    dh, dw = _as_pair(dilation, "dilation")
+
+    c, h, w = image.shape
+    eff_h = dh * (ph - 1) + 1
+    eff_w = dw * (pw - 1) + 1
+
+    if h < eff_h or w < eff_w:
+        return torch.empty(0, c, ph, pw, dtype=image.dtype, device=image.device)
+
+    unfolded = F.unfold(
+        image.unsqueeze(0),
+        kernel_size=(ph, pw),
+        dilation=(dh, dw),
+        stride=(sh, sw),
+    )
+    return unfolded[0].view(c, ph, pw, -1).permute(3, 0, 1, 2).contiguous()
+
+
+class Patchify:
+    """Callable that extracts patches with a frozen geometry.
+
+    Drop-in for `torchvision.transforms.Compose([...])`:
+
+        transform = Compose([
+            ToTensor(),
+            GaussianBlur(kernel_size=3),
+            Patchify(patch_size=4, stride=2),
+        ])
+        patches = transform(pil_image)  # Tensor[L, C, 4, 4]
+
+    Equivalent to `lambda img: extract(img, patch_size, stride, dilation)`,
+    but composable, repr-friendly, and validates the geometry at construction
+    instead of at first call. Holds no state beyond the geometry — no cache,
+    no fixed image size, no device. See ADR 0002.
+
+    Output shape is `(L, C, ph, pw)`, the same as `extract`. Subsequent
+    transforms in the Compose chain receive the patch stack, not a single
+    patch; they must accept `(N, C, H, W)` or be wrapped.
+    """
+
+    __slots__ = ("_dh", "_dw", "_ph", "_pw", "_sh", "_sw")
+
+    def __init__(
+        self,
+        patch_size: int | tuple[int, int],
+        stride: int | tuple[int, int],
+        dilation: int | tuple[int, int] = 1,
+    ) -> None:
+        self._ph, self._pw = _as_pair(patch_size, "patch_size")
+        self._sh, self._sw = _as_pair(stride, "stride")
+        self._dh, self._dw = _as_pair(dilation, "dilation")
+
+    def __call__(self, image: torch.Tensor) -> torch.Tensor:
+        return extract(
+            image,
+            patch_size=(self._ph, self._pw),
+            stride=(self._sh, self._sw),
+            dilation=(self._dh, self._dw),
+        )
+
+    def __repr__(self) -> str:
+        return (
+            f"Patchify(patch_size=({self._ph}, {self._pw}), "
+            f"stride=({self._sh}, {self._sw}), "
+            f"dilation=({self._dh}, {self._dw}))"
+        )

patchcraft/geometry.py

@@ -0,0 +1,290 @@
+"""Pre-flight geometry helpers: enumerate valid patch tilings, count patches.
+
+Pure number-only API — does not touch tensors or images. Useful for:
+- asking the lib "what patch sizes fit my image cleanly?" before extracting;
+- precomputing patch counts for memory planning;
+- driving parametrized tests over the full space of valid geometries.
+
+Contract: docs/THEORY.md §1.5 and §9.6.
+"""
+from __future__ import annotations
+
+from typing import NamedTuple
+
+from patchcraft.extract import _as_pair
+
+__all__ = [
+    "PairedTilingSpec",
+    "TilingSpec",
+    "num_patches",
+    "paired_tilings",
+    "scale_factor",
+    "tilings",
+]
+
+
+class TilingSpec(NamedTuple):
+    """One valid patch geometry for an image.
+
+    ``overlap=False`` means an *exact tile*: ``patch_size == stride`` and the
+    image is divided into a clean grid with no overlap and no waste.
+    ``overlap=True`` means ``stride < patch_size`` and full coverage is still
+    achieved — adjacent patches share pixels.
+    """
+
+    patch_size: tuple[int, int]
+    stride: tuple[int, int]
+    dilation: tuple[int, int]
+    num_patches: tuple[int, int]
+    total_patches: int
+    overlap: bool
+
+
+class PairedTilingSpec(NamedTuple):
+    """A pair of tilings that align across two resolutions of the same image.
+
+    ``hr.patch_size == scale_factor * lr.patch_size`` and same for stride;
+    ``lr.total_patches == hr.total_patches`` by construction. Patch ``k`` on
+    the LR side and patch ``k`` on the HR side cover the same image region
+    at different resolutions.
+    """
+
+    lr: TilingSpec
+    hr: TilingSpec
+    scale_factor: int
+
+
+def num_patches(
+    image_shape: tuple[int, ...],
+    patch_size: int | tuple[int, int],
+    stride: int | tuple[int, int],
+    dilation: int | tuple[int, int] = 1,
+) -> tuple[int, int]:
+    """Return ``(num_h, num_w)`` — how many patches `extract` would produce.
+
+    Accepts ``(H, W)`` or ``(C, H, W)`` for ``image_shape``. Returns ``(0, 0)``
+    in either axis when the effective patch does not fit (mirroring `extract`'s
+    empty-tensor behavior). Does not allocate or touch any tensor.
+    """
+    if not (isinstance(image_shape, tuple) and len(image_shape) in (2, 3)):
+        raise ValueError(
+            f"image_shape must be (H, W) or (C, H, W), got {image_shape!r}"
+        )
+    h, w = (image_shape[-2], image_shape[-1])
+    for axis_name, val in zip(("H", "W"), (h, w), strict=True):
+        if not isinstance(val, int) or isinstance(val, bool) or val <= 0:
+            raise ValueError(
+                f"image_shape[{axis_name}] must be a positive int, got {val!r}"
+            )
+
+    ph, pw = _as_pair(patch_size, "patch_size")
+    sh, sw = _as_pair(stride, "stride")
+    dh, dw = _as_pair(dilation, "dilation")
+
+    eff_h = dh * (ph - 1) + 1
+    eff_w = dw * (pw - 1) + 1
+    nh = (h - eff_h) // sh + 1 if h >= eff_h else 0
+    nw = (w - eff_w) // sw + 1 if w >= eff_w else 0
+    return (nh, nw)
+
+
+def tilings(
+    image_shape: tuple[int, int] | tuple[int, int, int],
+    *,
+    allow_overlap: bool = False,
+    min_patch_size: int = 2,
+    max_patch_size: int | None = None,
+) -> list[TilingSpec]:
+    """Enumerate square geometries that fully cover an image (``dilation==1``).
+
+    Always emits geometries with **full coverage** (no truncated rows/cols).
+    Patches are square: ``ph == pw``, ``sh == sw``.
+
+    Parameters
+    ----------
+    image_shape
+        ``(H, W)`` or ``(C, H, W)``. Only H, W matter.
+    allow_overlap
+        If False (default), emit only exact tilings (``stride == patch_size``
+        and ``H % p == 0`` and ``W % p == 0``). If True, also emit
+        ``stride < patch_size`` geometries with ``(H - p) % s == 0`` and
+        ``(W - p) % s == 0`` — overlap-with-clean-edges.
+    min_patch_size
+        Smallest patch to consider. Defaults to 2 (skips the trivial pixel-wise
+        tiling at ``p == 1``).
+    max_patch_size
+        Largest patch to consider. Defaults to ``min(H, W)``.
+
+    Returns
+    -------
+    list[TilingSpec]
+        Sorted by ``(patch_size[0], stride[0])`` ascending. Always at least
+        one entry: ``(p=min(H, W), s=p)`` when image is square.
+
+    Raises
+    ------
+    ValueError
+        On malformed ``image_shape``, non-positive bounds, or
+        ``min_patch_size > max_patch_size``.
+    """
+    if not (isinstance(image_shape, tuple) and len(image_shape) in (2, 3)):
+        raise ValueError(
+            f"image_shape must be (H, W) or (C, H, W), got {image_shape!r}"
+        )
+    h, w = (image_shape[-2], image_shape[-1])
+    for axis_name, val in zip(("H", "W"), (h, w), strict=True):
+        if not isinstance(val, int) or isinstance(val, bool) or val <= 0:
+            raise ValueError(
+                f"image_shape[{axis_name}] must be a positive int, got {val!r}"
+            )
+
+    if (
+        not isinstance(min_patch_size, int)
+        or isinstance(min_patch_size, bool)
+        or min_patch_size <= 0
+    ):
+        raise ValueError(
+            f"min_patch_size must be a positive int, got {min_patch_size!r}"
+        )
+    if max_patch_size is None:
+        max_patch_size = min(h, w)
+    if (
+        not isinstance(max_patch_size, int)
+        or isinstance(max_patch_size, bool)
+        or max_patch_size <= 0
+    ):
+        raise ValueError(
+            f"max_patch_size must be a positive int or None, got {max_patch_size!r}"
+        )
+    if min_patch_size > max_patch_size:
+        raise ValueError(
+            f"min_patch_size ({min_patch_size}) > max_patch_size ({max_patch_size})"
+        )
+
+    upper = min(max_patch_size, h, w)
+    results: list[TilingSpec] = []
+    for p in range(min_patch_size, upper + 1):
+        # Exact tile: stride == patch_size; requires divisibility on both axes.
+        if h % p == 0 and w % p == 0:
+            nh, nw = h // p, w // p
+            results.append(TilingSpec(
+                patch_size=(p, p),
+                stride=(p, p),
+                dilation=(1, 1),
+                num_patches=(nh, nw),
+                total_patches=nh * nw,
+                overlap=False,
+            ))
+        if allow_overlap:
+            for s in range(1, p):
+                if (h - p) % s == 0 and (w - p) % s == 0:
+                    nh = (h - p) // s + 1
+                    nw = (w - p) // s + 1
+                    results.append(TilingSpec(
+                        patch_size=(p, p),
+                        stride=(s, s),
+                        dilation=(1, 1),
+                        num_patches=(nh, nw),
+                        total_patches=nh * nw,
+                        overlap=True,
+                    ))
+    return results
+
+
+def scale_factor(
+    lr_shape: tuple[int, int] | tuple[int, int, int],
+    hr_shape: tuple[int, int] | tuple[int, int, int],
+) -> int | None:
+    """Return the integer scale factor between two image shapes, or ``None``.
+
+    Accepts ``(H, W)`` or ``(C, H, W)`` for either argument (channels are
+    ignored). Returns ``k`` such that
+    ``hr_shape[-2:] == (k * lr_shape[-2], k * lr_shape[-1])``, or ``None``
+    when no such integer ``k >= 1`` exists (non-divisible, anisotropic, or
+    LR larger than HR).
+
+    Pure shape math; no tensor, no allocation. Use it before calling
+    :func:`patchcraft.pair` to discover the scale factor from data instead
+    of hard-coding it.
+    """
+    for name, shape in (("lr_shape", lr_shape), ("hr_shape", hr_shape)):
+        if not (isinstance(shape, tuple) and len(shape) in (2, 3)):
+            raise ValueError(
+                f"{name} must be (H, W) or (C, H, W), got {shape!r}"
+            )
+        h, w = shape[-2], shape[-1]
+        for axis, val in (("H", h), ("W", w)):
+            if not isinstance(val, int) or isinstance(val, bool) or val <= 0:
+                raise ValueError(
+                    f"{name}[{axis}] must be a positive int, got {val!r}"
+                )
+
+    h_lr, w_lr = lr_shape[-2], lr_shape[-1]
+    h_hr, w_hr = hr_shape[-2], hr_shape[-1]
+    if h_hr % h_lr != 0 or w_hr % w_lr != 0:
+        return None
+    sf_h = h_hr // h_lr
+    sf_w = w_hr // w_lr
+    if sf_h != sf_w or sf_h < 1:
+        return None
+    return sf_h
+
+
+def paired_tilings(
+    lr_shape: tuple[int, int] | tuple[int, int, int],
+    hr_shape: tuple[int, int] | tuple[int, int, int],
+    *,
+    allow_overlap: bool = False,
+    min_patch_size: int = 2,
+    max_patch_size: int | None = None,
+) -> list[PairedTilingSpec]:
+    """Enumerate aligned tiling pairs between two resolutions of the same image.
+
+    Requires ``hr_shape`` to be an integer multiple of ``lr_shape`` (see
+    :func:`scale_factor`). For each LR tiling emitted by :func:`tilings`,
+    derives the matching HR tiling by multiplying patch size and stride by
+    the scale factor. Both sides have identical ``total_patches`` and patch
+    ``k`` covers the same image region on both sides.
+
+    Use the result to drive :func:`patchcraft.pair` with confidence that the
+    parameters produce sound, aligned LR/HR patch sets.
+
+    Raises
+    ------
+    ValueError
+        If ``lr_shape`` and ``hr_shape`` are not related by an integer
+        scale factor, or on the same input validation cases as
+        :func:`tilings`.
+    """
+    sf = scale_factor(lr_shape, hr_shape)
+    if sf is None:
+        raise ValueError(
+            f"lr_shape={lr_shape} and hr_shape={hr_shape} are not related "
+            "by a positive integer scale factor on both spatial axes"
+        )
+    h_hr, w_hr = hr_shape[-2], hr_shape[-1]
+    lr_specs = tilings(
+        lr_shape,
+        allow_overlap=allow_overlap,
+        min_patch_size=min_patch_size,
+        max_patch_size=max_patch_size,
+    )
+
+    pairs: list[PairedTilingSpec] = []
+    for lr in lr_specs:
+        ph_hr = lr.patch_size[0] * sf
+        pw_hr = lr.patch_size[1] * sf
+        sh_hr = lr.stride[0] * sf
+        sw_hr = lr.stride[1] * sf
+        nh_hr = (h_hr - ph_hr) // sh_hr + 1
+        nw_hr = (w_hr - pw_hr) // sw_hr + 1
+        hr = TilingSpec(
+            patch_size=(ph_hr, pw_hr),
+            stride=(sh_hr, sw_hr),
+            dilation=(1, 1),
+            num_patches=(nh_hr, nw_hr),
+            total_patches=nh_hr * nw_hr,
+            overlap=lr.overlap,
+        )
+        pairs.append(PairedTilingSpec(lr=lr, hr=hr, scale_factor=sf))
+    return pairs