patchcraft 0.2.0__py3-none-any.whl

patchcraft/metrics.py

@@ -0,0 +1,151 @@
+"""Pixel-level metrics between patches (or between any same-shape tensors).
+
+Three pure functions, no state, no allocation beyond the diff itself. Lives
+in PatchCraft because every consumer that uses ``extract`` + ``reconstruct``
+or ``pair`` ends up reinventing the same MSE/PSNR per patch — bundling them
+here saves consumers from inventing slightly-different reductions and gives
+the test suite a stable comparison surface.
+
+Out of scope: SSIM, MS-SSIM, LPIPS, perceptual losses. Those depend on
+windowing schemes or pre-trained networks; pytorch-msssim and lpips are
+mature standalone packages.
+
+Contract: docs/THEORY.md §1.6 and §9.7.
+"""
+from __future__ import annotations
+
+import math
+
+import torch
+
+__all__ = ["patch_metrics", "per_patch_mse", "per_patch_psnr"]
+
+
+def _check_pair(a: torch.Tensor, b: torch.Tensor) -> None:
+    if not isinstance(a, torch.Tensor):
+        raise TypeError(f"a must be torch.Tensor, got {type(a).__name__}")
+    if not isinstance(b, torch.Tensor):
+        raise TypeError(f"b must be torch.Tensor, got {type(b).__name__}")
+    if a.shape != b.shape:
+        raise ValueError(
+            f"shape mismatch: a.shape={tuple(a.shape)}, b.shape={tuple(b.shape)}"
+        )
+    if a.dtype != b.dtype:
+        raise ValueError(
+            f"dtype mismatch: a.dtype={a.dtype}, b.dtype={b.dtype}"
+        )
+    if a.device != b.device:
+        raise ValueError(
+            f"device mismatch: a.device={a.device}, b.device={b.device}"
+        )
+
+
+def _check_max_value(max_value: float) -> float:
+    if not isinstance(max_value, (int, float)) or isinstance(max_value, bool):
+        raise ValueError(
+            f"max_value must be a positive number, got {max_value!r}"
+        )
+    if not math.isfinite(max_value) or max_value <= 0:
+        raise ValueError(
+            f"max_value must be finite and positive, got {max_value!r}"
+        )
+    return float(max_value)
+
+
+def patch_metrics(
+    a: torch.Tensor,
+    b: torch.Tensor,
+    *,
+    max_value: float = 1.0,
+) -> dict[str, float]:
+    """Pixel-level metrics between two same-shape tensors.
+
+    Computes over the full tensor (reduces every axis). Works on single
+    patches ``(C, h, w)``, patch stacks ``(L, C, h, w)``, paired patches
+    of either shape — anything as long as ``a.shape == b.shape``.
+
+    Internal accumulation promotes to ``float64`` for stability, regardless
+    of input dtype. Returns plain Python floats so the dict can be
+    JSON-serialized.
+
+    Parameters
+    ----------
+    a, b
+        Same shape, same dtype, same device.
+    max_value
+        Dynamic range of the signal (``1.0`` for normalized
+        ``float`` in ``[0, 1]``, ``255`` for byte-scaled). Used only for PSNR.
+
+    Returns
+    -------
+    dict
+        ``{"mae", "mse", "max_abs", "psnr_db"}``. ``psnr_db`` is
+        ``+inf`` when ``a == b`` exactly.
+
+    Raises
+    ------
+    TypeError, ValueError
+        On non-tensor input, shape/dtype/device mismatch, or non-positive
+        ``max_value``.
+    """
+    _check_pair(a, b)
+    mv = _check_max_value(max_value)
+
+    a64 = a.to(torch.float64) if a.dtype != torch.float64 else a
+    b64 = b.to(torch.float64) if b.dtype != torch.float64 else b
+    diff = a64 - b64
+    abs_diff = diff.abs()
+    mse = (diff * diff).mean().item()
+    psnr_db = float("inf") if mse == 0.0 else 10.0 * math.log10(mv * mv / mse)
+    return {
+        "mae": abs_diff.mean().item(),
+        "mse": mse,
+        "max_abs": abs_diff.max().item(),
+        "psnr_db": psnr_db,
+    }
+
+
+def per_patch_mse(a: torch.Tensor, b: torch.Tensor) -> torch.Tensor:
+    """Return a ``(L,)`` tensor of MSE values, one per patch in ``(L, C, h, w)``.
+
+    Useful for ranking patches by reconstruction error after a model pass
+    or after a lossy round-trip. Reduction is over ``C, h, w``; the leading
+    axis is preserved.
+
+    Raises ``ValueError`` if either input is not 4-D or shapes differ.
+    """
+    _check_pair(a, b)
+    if a.ndim != 4:
+        raise ValueError(
+            f"per_patch_mse expects 4-D tensors (L, C, h, w), got ndim={a.ndim}"
+        )
+    diff = a - b
+    return (diff * diff).mean(dim=(1, 2, 3))
+
+
+def per_patch_psnr(
+    a: torch.Tensor,
+    b: torch.Tensor,
+    *,
+    max_value: float = 1.0,
+) -> torch.Tensor:
+    """Return a ``(L,)`` tensor of PSNR values (dB), one per patch.
+
+    Identical patches yield ``+inf`` (no clamp tricks — the result is
+    mathematically infinite and the caller should treat it as such).
+
+    Parameters
+    ----------
+    a, b
+        ``(L, C, h, w)`` tensors with identical shape, dtype, device.
+    max_value
+        Signal dynamic range; see :func:`patch_metrics`.
+    """
+    mv = _check_max_value(max_value)
+    mse = per_patch_mse(a, b)
+    finfo = torch.finfo(mse.dtype) if mse.is_floating_point() else None
+    tiny = finfo.tiny if finfo is not None else 1e-12
+    mse_safe = mse.clamp_min(tiny)
+    psnr = 10.0 * torch.log10((mv * mv) / mse_safe)
+    inf = torch.full_like(mse, float("inf"))
+    return torch.where(mse == 0, inf, psnr)

patchcraft/pair.py

@@ -0,0 +1,161 @@
+"""LR ↔ HR patch pairing.
+
+Given a low-resolution image, a high-resolution image, and an integer scale
+factor, produce patches on both sides that correspond pixel-region for
+pixel-region (patch ``k`` on each side covers the same image area, at
+different resolutions).
+
+Contract: docs/THEORY.md §3 and §9.3.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+import torch
+
+from patchcraft.extract import _as_pair, extract
+
+__all__ = ["PatchMeta", "PatchPair", "pair"]
+
+
+@dataclass(frozen=True, slots=True)
+class PatchMeta:
+    """Metadata for a single LR/HR patch correspondence.
+
+    Lives on CPU (never moves to GPU regardless of where the patches live).
+    Identifies *which* patch in the grid — coordinates are in LR pixel space;
+    multiply ``row`` and ``col`` by ``scale_factor`` to get HR coordinates.
+    """
+
+    patch_index: int
+    row: int
+    col: int
+    lr_patch_size: tuple[int, int]
+    hr_patch_size: tuple[int, int]
+    image_id: str | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class PatchPair:
+    """Result of ``pair()``: LR and HR patch tensors plus per-patch metadata."""
+
+    lr_patches: torch.Tensor  # (L, C, ph_lr, pw_lr)
+    hr_patches: torch.Tensor  # (L, C, ph_hr, pw_hr)
+    metas: tuple[PatchMeta, ...]
+
+    def __len__(self) -> int:
+        return int(self.lr_patches.shape[0])
+
+
+def pair(
+    lr_image: torch.Tensor,
+    hr_image: torch.Tensor,
+    lr_patch_size: int | tuple[int, int],
+    scale_factor: int,
+    stride: int | tuple[int, int],
+    *,
+    image_id: str | None = None,
+) -> PatchPair:
+    """Extract aligned LR/HR patch pairs.
+
+    Both images are ``(C, H, W)``. ``hr_image.shape`` must equal
+    ``(C, scale_factor * H_lr, scale_factor * W_lr)``. HR patch size and HR
+    stride are derived as ``scale_factor * lr_*``; dilation is fixed at 1.
+
+    Patch ``k`` on the LR side has its top-left at LR pixel
+    ``(row * sh_lr, col * sw_lr)``; the corresponding HR patch covers the
+    same image region at ``scale_factor`` times the resolution.
+
+    Returns a ``PatchPair`` with:
+    - ``lr_patches``: ``Tensor[L, C, ph_lr, pw_lr]`` (from `extract`).
+    - ``hr_patches``: ``Tensor[L, C, ph_hr, pw_hr]``.
+    - ``metas``: tuple of ``L`` :class:`PatchMeta` (CPU only).
+
+    Raises ``ValueError`` on any of the conditions listed in §9.3: non-int
+    or non-positive ``scale_factor``; HR shape that does not match
+    ``scale_factor * LR shape``; channel mismatch between LR and HR; LR or
+    HR not 3D; non-positive ``lr_patch_size`` or ``stride``.
+
+    LR and HR are expected to share the same dtype and device; mismatch is
+    rejected (caller normalizes upstream).
+    """
+    if not isinstance(lr_image, torch.Tensor):
+        raise TypeError(
+            f"lr_image must be torch.Tensor, got {type(lr_image).__name__}"
+        )
+    if not isinstance(hr_image, torch.Tensor):
+        raise TypeError(
+            f"hr_image must be torch.Tensor, got {type(hr_image).__name__}"
+        )
+    if lr_image.ndim != 3:
+        raise ValueError(f"lr_image must have ndim==3, got ndim={lr_image.ndim}")
+    if hr_image.ndim != 3:
+        raise ValueError(f"hr_image must have ndim==3, got ndim={hr_image.ndim}")
+
+    if (
+        not isinstance(scale_factor, int)
+        or isinstance(scale_factor, bool)
+        or scale_factor <= 0
+    ):
+        raise ValueError(
+            f"scale_factor must be a positive int, got {scale_factor!r}"
+        )
+
+    c_lr, h_lr, w_lr = lr_image.shape
+    c_hr, h_hr, w_hr = hr_image.shape
+
+    if c_lr != c_hr:
+        raise ValueError(
+            f"channel mismatch: lr_image has C={c_lr}, hr_image has C={c_hr}"
+        )
+    if lr_image.dtype != hr_image.dtype:
+        raise ValueError(
+            f"dtype mismatch: lr_image is {lr_image.dtype}, hr_image is {hr_image.dtype}"
+        )
+    if lr_image.device != hr_image.device:
+        raise ValueError(
+            f"device mismatch: lr_image on {lr_image.device}, hr_image on {hr_image.device}"
+        )
+
+    if h_hr != scale_factor * h_lr or w_hr != scale_factor * w_lr:
+        raise ValueError(
+            f"hr_image shape {hr_image.shape} does not match "
+            f"scale_factor={scale_factor} times lr_image shape {lr_image.shape}; "
+            f"expected hr shape ({c_lr}, {scale_factor * h_lr}, {scale_factor * w_lr})"
+        )
+
+    ph_lr, pw_lr = _as_pair(lr_patch_size, "lr_patch_size")
+    sh_lr, sw_lr = _as_pair(stride, "stride")
+
+    ph_hr, pw_hr = ph_lr * scale_factor, pw_lr * scale_factor
+    sh_hr, sw_hr = sh_lr * scale_factor, sw_lr * scale_factor
+
+    lr_patches = extract(
+        lr_image, patch_size=(ph_lr, pw_lr), stride=(sh_lr, sw_lr)
+    )
+    hr_patches = extract(
+        hr_image, patch_size=(ph_hr, pw_hr), stride=(sh_hr, sw_hr)
+    )
+
+    # Geometry is identical by construction (integer scale), so counts match.
+    n_patches = int(lr_patches.shape[0])
+    if hr_patches.shape[0] != n_patches:  # defensive — shouldn't happen
+        raise RuntimeError(
+            f"internal: lr and hr patch counts diverged "
+            f"({n_patches} vs {hr_patches.shape[0]}); please file a bug"
+        )
+
+    num_w_lr = (w_lr - pw_lr) // sw_lr + 1 if n_patches > 0 else 0
+    metas = tuple(
+        PatchMeta(
+            patch_index=k,
+            row=(k // num_w_lr) * sh_lr if num_w_lr else 0,
+            col=(k % num_w_lr) * sw_lr if num_w_lr else 0,
+            lr_patch_size=(ph_lr, pw_lr),
+            hr_patch_size=(ph_hr, pw_hr),
+            image_id=image_id,
+        )
+        for k in range(n_patches)
+    )
+
+    return PatchPair(lr_patches=lr_patches, hr_patches=hr_patches, metas=metas)

patchcraft/reconstruct.py

@@ -0,0 +1,118 @@
+"""Reconstruction of an image from its patches via torch.nn.functional.fold.
+
+Contract: docs/THEORY.md §2 and §9.2.
+"""
+from __future__ import annotations
+
+import torch
+import torch.nn.functional as F  # noqa: N812 (torch convention)
+
+from patchcraft.extract import _as_pair
+
+__all__ = ["reconstruct"]
+
+
+def reconstruct(
+    patches: torch.Tensor,
+    image_shape: tuple[int, int, int],
+    stride: int | tuple[int, int],
+    dilation: int | tuple[int, int] = 1,
+) -> torch.Tensor:
+    """Inverse of `extract`: rebuild a ``(C, H, W)`` image from ``(L, C, ph, pw)``.
+
+    Uses ``F.fold`` plus an overlap count map. Bit-exact round-trip when
+    ``stride == patch_size`` (each pixel covered exactly once). For overlap
+    (``stride < patch_size``), each pixel's reconstructed value is the average
+    of all patches covering it — same as the original when patches came from
+    ``extract`` unmodified.
+
+    Rejects (per §9.2): ``dilation != 1``; ``stride > patch_size`` in any axis
+    (partial coverage would synthesize pixel values, which PatchCraft refuses);
+    ``image_shape`` inconsistent with the patch grid (channels mismatch or
+    ``L`` does not match the geometry); ``patches.ndim != 4``.
+
+    Dtype and device of ``patches`` are preserved. For ``float16``, precision
+    is degraded by the divide-by-count-map step; promote to ``float32`` before
+    calling if exactness matters.
+    """
+    if not isinstance(patches, torch.Tensor):
+        raise TypeError(
+            f"patches must be torch.Tensor, got {type(patches).__name__}"
+        )
+    if patches.ndim != 4:
+        raise ValueError(
+            f"patches must have ndim==4 (L, C, ph, pw), got ndim={patches.ndim}"
+        )
+
+    n_patches, c, ph, pw = patches.shape
+
+    if not (isinstance(image_shape, tuple) and len(image_shape) == 3):
+        raise ValueError(
+            f"image_shape must be a 3-tuple (C, H, W), got {image_shape!r}"
+        )
+    for axis_name, val in zip(("C", "H", "W"), image_shape, 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}"
+            )
+    target_c, h, w = image_shape
+    if target_c != c:
+        raise ValueError(
+            f"image_shape channels={target_c} does not match patches channel count {c}"
+        )
+
+    sh, sw = _as_pair(stride, "stride")
+    dh, dw = _as_pair(dilation, "dilation")
+
+    if dh != 1 or dw != 1:
+        raise ValueError(
+            f"reconstruct requires dilation==1, got dilation=({dh}, {dw}). "
+            "Patches extracted with dilation > 1 cannot round-trip — consume them as features."
+        )
+    if sh > ph or sw > pw:
+        raise ValueError(
+            f"reconstruct forbids stride > patch_size (partial coverage forbidden), "
+            f"got stride=({sh}, {sw}) and patch_size=({ph}, {pw})."
+        )
+
+    num_h = (h - ph) // sh + 1
+    num_w = (w - pw) // sw + 1
+    if num_h <= 0 or num_w <= 0:
+        raise ValueError(
+            f"image_shape={image_shape} too small for patch_size=({ph}, {pw}) "
+            f"and stride=({sh}, {sw})"
+        )
+    expected_n_patches = num_h * num_w
+    if n_patches != expected_n_patches:
+        raise ValueError(
+            f"patches.shape[0]={n_patches} inconsistent with grid implied by "
+            f"image_shape={image_shape}, patch_size=({ph}, {pw}), "
+            f"stride=({sh}, {sw}): expected L={expected_n_patches} "
+            f"(num_h={num_h}, num_w={num_w})."
+        )
+
+    # (L, C, ph, pw) -> (1, C*ph*pw, L), the layout F.fold expects.
+    patches_flat = (
+        patches.permute(1, 2, 3, 0).reshape(c * ph * pw, n_patches).unsqueeze(0)
+    )
+    folded = F.fold(
+        patches_flat,
+        output_size=(h, w),
+        kernel_size=(ph, pw),
+        stride=(sh, sw),
+    )
+
+    # Count map: same fold geometry but 1 "channel" — broadcasts across C in division.
+    ones = torch.ones(
+        1, ph * pw, n_patches, dtype=patches.dtype, device=patches.device
+    )
+    count = F.fold(
+        ones,
+        output_size=(h, w),
+        kernel_size=(ph, pw),
+        stride=(sh, sw),
+    )
+
+    # clamp(min=1e-6) absorbs float noise on covered pixels; geometry validation
+    # above guarantees there are no uncovered pixels (count > 0 everywhere).
+    return (folded / count.clamp(min=1e-6))[0]

patchcraft/resize.py

@@ -0,0 +1,189 @@
+"""Image resizing with PIL or torch backends.
+
+Output type matches input: PIL → PIL, Tensor → Tensor. Cross-backend
+conversions go through a normalized float32 [0, 1] intermediate (with a
+uint8 hop into PIL because PIL's standard modes are byte-typed).
+
+Contract: docs/THEORY.md §5 and §9.4.
+"""
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any, Literal
+
+import numpy as np
+import torch
+import torch.nn.functional as F  # noqa: N812 (torch convention)
+
+if TYPE_CHECKING:
+    from PIL.Image import Image as PILImage
+
+__all__ = ["resize"]
+
+
+_PIL_RESAMPLE_NAMES = {
+    "nearest", "bilinear", "bicubic", "lanczos", "box", "hamming",
+}
+_TORCH_RESAMPLE_NAMES = {
+    "nearest", "bilinear", "bicubic", "area", "nearest-exact",
+}
+
+
+def _validate_target_size(target_size: object) -> tuple[int, int]:
+    if not (isinstance(target_size, tuple) and len(target_size) == 2):
+        raise ValueError(
+            f"target_size must be a 2-tuple (H, W), got {target_size!r}"
+        )
+    for axis_name, val in zip(("H", "W"), target_size, strict=True):
+        if not isinstance(val, int) or isinstance(val, bool) or val <= 0:
+            raise ValueError(
+                f"target_size[{axis_name}] must be a positive int, got {val!r}"
+            )
+    return (target_size[0], target_size[1])
+
+
+def _pil_to_tensor_f32(pil_image: PILImage) -> torch.Tensor:
+    """PIL → ``Tensor[C, H, W]`` float32 in [0, 1]. Copy is forced (PIL buffers
+    are not safely sharable with torch)."""
+    arr = np.asarray(pil_image, dtype=np.float32) / 255.0
+    arr = arr[np.newaxis, ...] if arr.ndim == 2 else arr.transpose(2, 0, 1)
+    return torch.from_numpy(np.ascontiguousarray(arr))
+
+
+def _tensor_to_pil_u8(tensor: torch.Tensor) -> PILImage:
+    """``Tensor[C, H, W]`` → PIL.Image (uint8 modes: L, RGB, RGBA only)."""
+    from PIL import Image
+    if tensor.is_floating_point():
+        arr = (tensor.clamp(0, 1).cpu().numpy() * 255).round().astype(np.uint8)
+    else:
+        arr = tensor.cpu().numpy().astype(np.uint8)
+    c = arr.shape[0]
+    if c == 1:
+        return Image.fromarray(arr[0], mode="L")
+    if c == 3:
+        return Image.fromarray(arr.transpose(1, 2, 0), mode="RGB")
+    if c == 4:
+        return Image.fromarray(arr.transpose(1, 2, 0), mode="RGBA")
+    raise ValueError(
+        f"cannot convert tensor with {c} channels to PIL "
+        f"(supported: C=1 → L, C=3 → RGB, C=4 → RGBA)"
+    )
+
+
+def _resize_pil(
+    pil_image: PILImage,
+    target_size: tuple[int, int],
+    resample: str | None,
+) -> PILImage:
+    from PIL import Image
+    h, w = target_size
+    if resample is None:
+        pil_resample = Image.Resampling.LANCZOS
+    else:
+        if not isinstance(resample, str):
+            raise ValueError(
+                f"resample must be str or None, got {type(resample).__name__}"
+            )
+        key = resample.lower()
+        if key not in _PIL_RESAMPLE_NAMES:
+            raise ValueError(
+                f"resample {resample!r} not supported by PIL backend; "
+                f"valid: {sorted(_PIL_RESAMPLE_NAMES)}"
+            )
+        pil_resample = Image.Resampling[key.upper()]
+    return pil_image.resize((w, h), pil_resample)
+
+
+def _resize_torch(
+    tensor: torch.Tensor,
+    target_size: tuple[int, int],
+    resample: str | None,
+) -> torch.Tensor:
+    if resample is None:
+        mode = "bilinear"
+    else:
+        if not isinstance(resample, str):
+            raise ValueError(
+                f"resample must be str or None, got {type(resample).__name__}"
+            )
+        key = resample.lower()
+        if key not in _TORCH_RESAMPLE_NAMES:
+            raise ValueError(
+                f"resample {resample!r} not supported by torch backend; "
+                f"valid: {sorted(_TORCH_RESAMPLE_NAMES)}"
+            )
+        mode = key
+
+    original_dtype = tensor.dtype
+    x = tensor.unsqueeze(0)
+    if mode in {"bilinear", "bicubic"} and not x.is_floating_point():
+        x = x.to(torch.float32)
+
+    kwargs: dict[str, Any] = {"size": target_size, "mode": mode}
+    if mode in {"bilinear", "bicubic"}:
+        kwargs["align_corners"] = False
+    out = F.interpolate(x, **kwargs)
+    return out[0].to(original_dtype)
+
+
+def resize(
+    image: torch.Tensor | PILImage,
+    target_size: tuple[int, int],
+    backend: Literal["pil", "torch"] = "pil",
+    resample: str | None = None,
+) -> torch.Tensor | PILImage:
+    """Resize a single image, preserving input type.
+
+    ``image`` is a ``PIL.Image`` or ``Tensor[C, H, W]``. ``target_size`` is
+    ``(H, W)``. ``backend`` selects the resize algorithm family
+    (``"pil"`` → ``PIL.Image.resize``; ``"torch"`` → ``F.interpolate``).
+    Cross-backend conversions go through a normalized float32 [0, 1]
+    intermediate. CUDA tensors are only accepted with ``backend="torch"``.
+
+    ``resample=None`` picks each backend's default: LANCZOS for ``"pil"``,
+    bilinear for ``"torch"``. The accepted resample strings differ between
+    backends; an unsupported choice raises ``ValueError``.
+
+    Rejects (per §9.4): non-2-tuple or non-positive ``target_size``;
+    ``backend`` not in ``{"pil", "torch"}``; CUDA tensor with
+    ``backend="pil"``; unsupported ``resample`` for the chosen backend;
+    PIL tensor conversion of an unsupported channel count.
+    """
+    target_size = _validate_target_size(target_size)
+    if backend not in {"pil", "torch"}:
+        raise ValueError(f"backend must be 'pil' or 'torch', got {backend!r}")
+
+    if isinstance(image, torch.Tensor):
+        if image.ndim != 3:
+            raise ValueError(
+                f"tensor image must have ndim==3 (C, H, W), got ndim={image.ndim}"
+            )
+        if backend == "pil":
+            if image.device.type != "cpu":
+                raise ValueError(
+                    f"backend='pil' cannot accept tensors on {image.device}; "
+                    "move to CPU explicitly with .cpu() first"
+                )
+            original_dtype = image.dtype
+            pil_in = _tensor_to_pil_u8(image)
+            pil_out = _resize_pil(pil_in, target_size, resample)
+            tensor_out = _pil_to_tensor_f32(pil_out)
+            if not torch.empty(0, dtype=original_dtype).is_floating_point():
+                tensor_out = (tensor_out * 255).round()
+            return tensor_out.to(original_dtype)
+        return _resize_torch(image, target_size, resample)
+
+    # PIL branch.
+    try:
+        from PIL.Image import Image as PILImageCls
+    except ImportError as exc:  # pragma: no cover — pillow is a runtime dep
+        raise ImportError("Pillow is required for resize") from exc
+    if not isinstance(image, PILImageCls):
+        raise TypeError(
+            f"image must be torch.Tensor or PIL.Image, got {type(image).__name__}"
+        )
+    if backend == "pil":
+        return _resize_pil(image, target_size, resample)
+    # PIL + backend == "torch"
+    tensor = _pil_to_tensor_f32(image)
+    resized = _resize_torch(tensor, target_size, resample)
+    return _tensor_to_pil_u8(resized)