improcv 0.1.0a1__py3-none-any.whl

improcv/__init__.py

@@ -0,0 +1,264 @@
+"""improcv: modern image-processing and computer-vision utilities for NumPy and OpenCV."""
+
+from importlib.metadata import PackageNotFoundError
+from importlib.metadata import version as _version
+
+try:
+    __version__ = _version("improcv")
+except PackageNotFoundError:
+    # Only happens when running from a source checkout that was never
+    # installed (editable or otherwise) -- package metadata doesn't exist
+    # yet to read a version from.
+    __version__ = "0.0.0.dev0"
+
+try:
+    import cv2 as _cv2  # noqa: F401
+except ModuleNotFoundError as _exc:
+    # Only a genuinely absent cv2 gets the friendly "install one of these
+    # extras" message. A present-but-broken installation (ABI mismatch, a
+    # missing shared library, a corrupted build) raises a plain
+    # ImportError instead of ModuleNotFoundError, or a ModuleNotFoundError
+    # for some *other* module cv2 itself failed to import — in either
+    # case, masking that with "you need to install OpenCV" would hide the
+    # real problem, so it's left to propagate unmodified.
+    if _exc.name != "cv2":
+        raise
+    raise ImportError(
+        "improcv requires an OpenCV installation, which is not installed automatically "
+        "(to avoid conflicting with an OpenCV variant you may already have). Install "
+        'exactly one of: `pip install "improcv[cv]"` (opencv-python), '
+        '`pip install "improcv[cv-headless]"` (opencv-python-headless), '
+        '`pip install "improcv[cv-contrib]"` (opencv-contrib-python), or '
+        '`pip install "improcv[cv-contrib-headless]"` (opencv-contrib-python-headless) — '
+        "or install one of the four `opencv-*` packages yourself."
+    ) from _exc
+
+from improcv.analysis import (
+    MeanStdDevResult,
+    MinMaxResult,
+    Moments,
+    TemplateMatchMethod,
+    histogram,
+    match_template,
+    mean_stddev,
+    min_max_loc,
+    moments,
+)
+from improcv.barcode import Barcode, decode_barcodes
+from improcv.color import bgr_to_rgb, ensure_gray, rgb_to_bgr, to_hsv, to_lab, to_ycrcb
+from improcv.contours import (
+    ApproxMethod,
+    BoundingBox,
+    Contour,
+    Hierarchy,
+    RetrievalMode,
+    RotatedRect,
+    SortOrder,
+    approx_poly_dp,
+    bounding_boxes,
+    convex_hull,
+    find_contours,
+    min_area_rect,
+    sort_contours,
+)
+from improcv.detectors import (
+    FastType,
+    MSERRegion,
+    detect_blob_keypoints,
+    detect_fast_keypoints,
+    detect_mser_regions,
+)
+from improcv.drawing import draw_bounding_boxes, draw_contours, montage
+from improcv.edges import auto_canny, harris_corner, laplacian_edge, sobel_edge
+from improcv.features import (
+    DescriptorNorm,
+    FeatureMethod,
+    Features,
+    HomographyResult,
+    detect_and_compute,
+    find_homography,
+    match_features,
+    match_features_ratio,
+)
+from improcv.filters import (
+    bilateral_filter,
+    clahe,
+    gamma_correction,
+    gaussian_blur,
+    histogram_equalization,
+    median_blur,
+)
+from improcv.hough import (
+    Circle,
+    HoughCircleMethod,
+    Line,
+    LineSegment,
+    hough_circles,
+    hough_line_segments,
+    hough_lines,
+)
+from improcv.morphology import (
+    blackhat,
+    dilate,
+    erode,
+    morph_close,
+    morph_gradient,
+    morph_open,
+    threshold,
+    tophat,
+)
+from improcv.pixels import (
+    adjust_brightness,
+    adjust_contrast,
+    alpha_blend,
+    apply_lut,
+    bitwise_and,
+    bitwise_or,
+    in_range,
+    invert,
+)
+from improcv.qrcode import QRCode, decode_qr_code, decode_qr_codes
+from improcv.regions import (
+    Centroids,
+    ComponentStats,
+    Connectivity,
+    DistanceMaskSize,
+    DistanceType,
+    FloodFillResult,
+    Labels,
+    connected_components,
+    connected_components_with_stats,
+    distance_transform,
+    flood_fill,
+)
+from improcv.restoration import InpaintMethod, inpaint
+from improcv.segmentation import grabcut_rect, watershed
+from improcv.transforms import (
+    center_crop,
+    crop,
+    flip,
+    pad,
+    resize,
+    rotate,
+    rotate_bound,
+    translate,
+    warp_affine,
+    warp_perspective,
+)
+from improcv.types import Image, ImageFloat32, ImageU8, Mask, TransformMatrix
+
+__all__ = [
+    "ApproxMethod",
+    "Barcode",
+    "BoundingBox",
+    "Centroids",
+    "Circle",
+    "ComponentStats",
+    "Connectivity",
+    "Contour",
+    "DescriptorNorm",
+    "DistanceMaskSize",
+    "DistanceType",
+    "FastType",
+    "FeatureMethod",
+    "Features",
+    "FloodFillResult",
+    "Hierarchy",
+    "HomographyResult",
+    "HoughCircleMethod",
+    "Image",
+    "ImageFloat32",
+    "ImageU8",
+    "InpaintMethod",
+    "Labels",
+    "Line",
+    "LineSegment",
+    "Mask",
+    "MSERRegion",
+    "MeanStdDevResult",
+    "MinMaxResult",
+    "Moments",
+    "QRCode",
+    "RetrievalMode",
+    "RotatedRect",
+    "SortOrder",
+    "TemplateMatchMethod",
+    "TransformMatrix",
+    "__version__",
+    "adjust_brightness",
+    "adjust_contrast",
+    "alpha_blend",
+    "apply_lut",
+    "approx_poly_dp",
+    "auto_canny",
+    "bgr_to_rgb",
+    "bilateral_filter",
+    "bitwise_and",
+    "bitwise_or",
+    "blackhat",
+    "bounding_boxes",
+    "center_crop",
+    "clahe",
+    "connected_components",
+    "connected_components_with_stats",
+    "convex_hull",
+    "crop",
+    "decode_barcodes",
+    "decode_qr_code",
+    "decode_qr_codes",
+    "detect_and_compute",
+    "detect_blob_keypoints",
+    "detect_fast_keypoints",
+    "detect_mser_regions",
+    "dilate",
+    "distance_transform",
+    "draw_bounding_boxes",
+    "draw_contours",
+    "ensure_gray",
+    "erode",
+    "find_contours",
+    "find_homography",
+    "flip",
+    "flood_fill",
+    "gamma_correction",
+    "gaussian_blur",
+    "grabcut_rect",
+    "harris_corner",
+    "histogram",
+    "histogram_equalization",
+    "hough_circles",
+    "hough_line_segments",
+    "hough_lines",
+    "in_range",
+    "inpaint",
+    "invert",
+    "laplacian_edge",
+    "match_features",
+    "match_features_ratio",
+    "match_template",
+    "mean_stddev",
+    "median_blur",
+    "min_area_rect",
+    "min_max_loc",
+    "moments",
+    "montage",
+    "morph_close",
+    "morph_gradient",
+    "morph_open",
+    "pad",
+    "resize",
+    "rgb_to_bgr",
+    "rotate",
+    "rotate_bound",
+    "sobel_edge",
+    "sort_contours",
+    "threshold",
+    "to_hsv",
+    "to_lab",
+    "to_ycrcb",
+    "tophat",
+    "translate",
+    "warp_affine",
+    "warp_perspective",
+    "watershed",
+]

improcv/_compat/opencv.py

@@ -0,0 +1,58 @@
+"""Isolates OpenCV 4.x/5.x behavioral differences behind narrow, capability-detected helpers.
+
+Nothing here branches on the OpenCV version number: each helper detects the
+actual difference it's normalizing (a shape, a presence of an attribute) and
+handles it directly.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+
+__all__: list[str] = []
+
+
+def _normalize_calc_hist_output(raw: np.ndarray, bins: int) -> np.ndarray:
+    """Normalize cv2.calcHist's output to a flat ``(bins,)`` array.
+
+    ``cv2.calcHist`` returns shape ``(bins, 1)`` on some OpenCV builds and
+    ``(bins,)`` on others for identical 1D-histogram input (verified
+    directly: ``(bins, 1)`` on OpenCV 4.13.0, ``(bins,)`` on OpenCV 5.0.0).
+    Detected by the array's actual size, not by checking the OpenCV version.
+    """
+    if raw.size != bins:
+        raise RuntimeError(
+            f"cv2.calcHist returned an array of size {raw.size}, expected {bins} "
+            "-- unexpected OpenCV output shape"
+        )
+    return raw.reshape(bins)
+
+
+def _normalize_hough_lines_p_output(raw: np.ndarray) -> np.ndarray:
+    """Normalize cv2.HoughLinesP's output to a flat ``(N, 4)`` int32 array.
+
+    ``cv2.HoughLinesP`` returns shape ``(N, 4)`` on some OpenCV builds and
+    ``(N, 1, 4)`` on others for identical input (verified directly:
+    ``(N, 1, 4)`` on OpenCV 4.13.0, ``(N, 4)`` on OpenCV 5.0.0). Detected by
+    the array's actual shape, not by checking the OpenCV version. Accepts
+    only exactly 4 fields per row (``x1, y1, x2, y2``) and ``int32`` --
+    anything else is an internally inconsistent OpenCV result, not a shape
+    this function knows how to normalize.
+    """
+    if not isinstance(raw, np.ndarray):
+        raise RuntimeError(
+            f"cv2.HoughLinesP returned a {type(raw).__name__}, expected an np.ndarray -- "
+            "unexpected OpenCV output"
+        )
+    if raw.dtype != np.int32:
+        raise RuntimeError(
+            f"cv2.HoughLinesP returned dtype {raw.dtype}, expected int32 -- "
+            "unexpected OpenCV output"
+        )
+    if raw.ndim == 2 and raw.shape[1] == 4:
+        return raw
+    if raw.ndim == 3 and raw.shape[1:] == (1, 4):
+        return raw[:, 0, :]
+    raise RuntimeError(
+        f"cv2.HoughLinesP returned an array of shape {raw.shape} -- unexpected OpenCV output shape"
+    )

improcv/_validation.py

@@ -0,0 +1,363 @@
+"""Shared argument validation helpers for improcv's public functions."""
+
+from __future__ import annotations
+
+import math
+import numbers
+from collections.abc import Collection
+from typing import cast
+
+import numpy as np
+
+__all__: list[str] = []
+
+
+def require_image_ndim(image: np.ndarray, ndims: tuple[int, ...] = (2, 3)) -> None:
+    """Raise ValueError unless `image.ndim` is one of `ndims` and `image` is non-empty.
+
+    Every public function calls this (directly or via a narrower `ndims`),
+    so the empty-image check here is the single, global place that rejects
+    an empty image for the whole library. Checks `image.size == 0` rather
+    than just height/width: a zero-channel `(H, W, 0)` array has nonzero
+    height and width but is still empty, and verified directly to produce
+    uninitialized-memory garbage from at least one OpenCV call rather than
+    a clear error.
+    """
+    if image.ndim not in ndims:
+        allowed = " or ".join(str(n) for n in ndims)
+        raise ValueError(f"image must have {allowed} dimensions, got {image.ndim}")
+    if image.size == 0:
+        raise ValueError(f"image must not be empty, got shape {image.shape}")
+
+
+def require_real_number(value: object, name: str) -> None:
+    """Raise TypeError unless `value` is a real number.
+
+    Accepts plain Python `int`/`float` as well as NumPy scalar types
+    (`np.float32`, `np.float64`, `np.int32`, ...) — anything registered as
+    `numbers.Real` — but rejects `bool` (a `bool` is technically an `int`
+    subclass, but accepting `True`/`False` here would silently
+    misinterpret a boolean argument as ``1``/``0``) and non-numeric types
+    such as `str`.
+    """
+    if isinstance(value, bool) or not isinstance(value, numbers.Real):
+        raise TypeError(f"{name} must be a real number, got {type(value).__name__}")
+
+
+def _safe_float(value: numbers.Real) -> float:
+    """Convert `value` to float, treating an unconvertible magnitude as infinity.
+
+    `float(value)` raises a raw `OverflowError` for a Python `int` too huge
+    to represent as a float (e.g. ``10**400``) — verified directly. Such a
+    value is not representable as a finite float either way, so this
+    treats it the same as an already-infinite value rather than letting
+    the raw `OverflowError` propagate past validation.
+    """
+    try:
+        return float(value)
+    except OverflowError:
+        # Only a Python int (arbitrary precision) can overflow float() in
+        # practice; the cast is purely to satisfy Pyright (numbers.Real
+        # doesn't support comparison operators reliably per typeshed) and
+        # has no runtime effect.
+        return math.inf if cast(int, value) > 0 else -math.inf
+
+
+def _is_nan_or_inf(value: numbers.Real) -> bool:
+    # _safe_float normalizes any numbers.Real (including NumPy scalar types
+    # like np.float32, which math.isnan/math.isinf don't accept directly on
+    # some platforms) before checking finiteness.
+    return not math.isfinite(_safe_float(value))
+
+
+def require_positive(value: object, name: str) -> None:
+    """Raise TypeError unless `value` is a real number, then ValueError unless
+    it's finite and positive."""
+    require_real_number(value, name)
+    assert isinstance(value, numbers.Real)  # narrows for the type checker
+    if _is_nan_or_inf(value):
+        raise ValueError(f"{name} must be finite, got {value}")
+    if value <= 0:
+        raise ValueError(f"{name} must be positive, got {value}")
+
+
+def require_non_negative(value: object, name: str) -> None:
+    """Raise TypeError unless `value` is a real number, then ValueError unless
+    it's finite and non-negative."""
+    require_real_number(value, name)
+    assert isinstance(value, numbers.Real)  # narrows for the type checker
+    if _is_nan_or_inf(value):
+        raise ValueError(f"{name} must be finite, got {value}")
+    if value < 0:
+        raise ValueError(f"{name} must be non-negative, got {value}")
+
+
+def require_finite(value: object, name: str) -> None:
+    """Raise TypeError unless `value` is a real number, then ValueError unless
+    it's finite (not NaN or infinite).
+
+    Unlike `require_positive`/`require_non_negative`, this carries no sign
+    constraint — for parameters where negative values are meaningful (e.g.
+    a brightness delta) but NaN/infinity are not.
+    """
+    require_real_number(value, name)
+    assert isinstance(value, numbers.Real)  # narrows for the type checker
+    if _is_nan_or_inf(value):
+        raise ValueError(f"{name} must be finite, got {value}")
+
+
+def require_int(value: object, name: str) -> None:
+    """Raise TypeError unless `value` is an int.
+
+    Rejects `bool` (a `bool` is technically an `int` subclass in Python,
+    but accepting `True`/`False` here would silently misinterpret a
+    boolean argument as ``1``/``0``) and any non-int type, including
+    floats — so this also rejects NaN and infinity, which are float-only
+    concepts.
+    """
+    if isinstance(value, bool) or not isinstance(value, int):
+        raise TypeError(f"{name} must be an int, got {type(value).__name__}")
+
+
+def require_integral(value: object, name: str) -> None:
+    """Raise TypeError unless `value` is an integral number.
+
+    Accepts plain Python `int` as well as NumPy integer scalar types
+    (`np.int32`, `np.int64`, ...) — anything registered as `numbers.Integral`
+    — but rejects `bool` (a `bool` is technically an `int` subclass, and
+    therefore also registers as `numbers.Integral`, but accepting
+    `True`/`False` here would silently misinterpret a boolean argument as
+    `1`/`0`) and non-integral types such as `float`.
+
+    Unlike `require_int`, which only accepts plain `int`, this accepts any
+    `numbers.Integral` — for parameters where a coordinate might legitimately
+    come straight out of a NumPy array (e.g. a centroid or contour point).
+    """
+    if isinstance(value, bool) or not isinstance(value, numbers.Integral):
+        raise TypeError(f"{name} must be an integer, got {type(value).__name__}")
+
+
+def require_bool(value: object, name: str) -> None:
+    """Raise TypeError unless `value` is an actual `bool`.
+
+    OpenCV's Python bindings loosely coerce several types (including `int`
+    and even `None`) into a boolean parameter — this rejects that before it
+    reaches OpenCV, so a caller's mistake surfaces as a clear error instead
+    of silently-wrong behavior.
+    """
+    if not isinstance(value, bool):
+        raise TypeError(f"{name} must be a bool, got {type(value).__name__}")
+
+
+def require_positive_int(value: object, name: str) -> None:
+    """Raise TypeError unless `value` is an int, then ValueError unless it's positive."""
+    require_int(value, name)
+    assert isinstance(value, int)  # narrows for the type checker; require_int already enforced this
+    if value <= 0:
+        raise ValueError(f"{name} must be positive, got {value}")
+
+
+def require_non_negative_int(value: object, name: str) -> None:
+    """Raise TypeError unless `value` is an int, then ValueError unless it's non-negative."""
+    require_int(value, name)
+    assert isinstance(value, int)  # narrows for the type checker; require_int already enforced this
+    if value < 0:
+        raise ValueError(f"{name} must be non-negative, got {value}")
+
+
+def require_size_2d(value: object, name: str) -> None:
+    """Raise ValueError/TypeError unless `value` is a 2-tuple of positive ints.
+
+    For ``(width, height)``-style parameters (e.g. `output_size`), where
+    a wrong-length tuple would otherwise reach an `IndexError` or a raw
+    `cv2.error` deep inside OpenCV instead of a clear library error.
+    """
+    if not isinstance(value, tuple) or len(value) != 2:
+        raise ValueError(f"{name} must be a 2-tuple, got {value!r}")
+    width, height = value
+    require_positive_int(width, f"{name}[0]")
+    require_positive_int(height, f"{name}[1]")
+
+
+def require_point_2d(value: object, name: str) -> None:
+    """Raise ValueError/TypeError unless `value` is a 2-tuple of finite real numbers.
+
+    For ``(x, y)``-style parameters (e.g. `rotate`'s `center`), where a
+    wrong-length tuple would otherwise reach an `IndexError` (too short)
+    or a raw `cv2.error`/`TypeError` deep inside OpenCV (too long).
+    """
+    if not isinstance(value, tuple) or len(value) != 2:
+        raise ValueError(f"{name} must be a 2-tuple, got {value!r}")
+    x, y = value
+    require_finite(x, f"{name}[0]")
+    require_finite(y, f"{name}[1]")
+
+
+def require_one_of(value: object, allowed: Collection[object], name: str) -> None:
+    """Raise ValueError unless `value` is one of `allowed`.
+
+    Intended for runtime-checking string-literal (`Literal[...]`) parameters:
+    type checkers only catch invalid values at static-analysis time, so
+    every such parameter needs this check to reject bad values passed in
+    at runtime (e.g. from user input or untyped call sites).
+    """
+    if value not in allowed:
+        raise ValueError(f"{name} must be one of {tuple(allowed)}, got {value!r}")
+
+
+def require_dtype(image: np.ndarray, dtypes: tuple[type, ...], name: str = "image") -> None:
+    """Raise TypeError unless `image.dtype` is one of `dtypes`.
+
+    For functions backed by an OpenCV call that only supports specific
+    dtypes (e.g. ``cv2.equalizeHist`` requires 8-bit input) and would
+    otherwise raise a raw, unfriendly ``cv2.error``.
+    """
+    if not any(image.dtype == dtype for dtype in dtypes):
+        allowed = ", ".join(np.dtype(dtype).name for dtype in dtypes)
+        raise TypeError(f"{name} must have dtype in ({allowed}), got {image.dtype}")
+
+
+def require_transform_matrix(
+    matrix: np.ndarray, shape: tuple[int, int], name: str = "matrix"
+) -> None:
+    """Raise ValueError/TypeError unless `matrix` is a finite float array of `shape`.
+
+    Checks shape, then dtype (``float32``/``float64`` — an ``int32``
+    matrix reaches a raw ``cv2.error``), then finiteness (a ``NaN`` in the
+    matrix does not error at all; it silently produces a black image).
+    Deliberately does not cast a wrong-dtype matrix for the caller — a
+    silent cast could paper over the caller's own mistake (e.g. building
+    the matrix from integer inputs by accident).
+    """
+    if matrix.shape != shape:
+        raise ValueError(f"{name} must have shape {shape}, got {matrix.shape}")
+    require_dtype(matrix, (np.float32, np.float64), name)
+    if not np.all(np.isfinite(matrix)):
+        raise ValueError(f"{name} must contain only finite values")
+
+
+def require_channels(image: np.ndarray, channels: int) -> None:
+    """Raise ValueError unless `image` has exactly `channels` channels and is non-empty.
+
+    The emptiness check matters on its own: a 3-channel *empty* image
+    (e.g. shape ``(0, 10, 3)``) previously passed this check and reached
+    a raw ``cv2.error`` at the actual OpenCV call site.
+    """
+    if image.ndim != 3 or image.shape[2] != channels:
+        raise ValueError(
+            f"image must have {channels} channels with shape (H, W, {channels}), "
+            f"got shape {image.shape}"
+        )
+    if image.shape[0] == 0 or image.shape[1] == 0:
+        raise ValueError(f"image must not be empty, got shape {image.shape}")
+
+
+def require_channel_count(
+    image: np.ndarray, min_channels: int, max_channels: int, name: str = "image"
+) -> int:
+    """Raise ValueError unless `image`'s channel count is within [min_channels, max_channels].
+
+    Returns the channel count (1 for a 2D image) for convenience. Several
+    ``cv2.*`` calls that accept an arbitrary channel count in principle
+    silently misinterpret the array once the channel count exceeds an
+    OpenCV-build-specific limit (e.g. ``cv2.meanStdDev`` verified to
+    silently collapse to a single aggregate channel above 128 channels on
+    OpenCV 5.x but not until above 512 on OpenCV 4.x) -- this makes that
+    limit an explicit, checked contract instead of silent, version-dependent
+    data corruption.
+    """
+    channels = 1 if image.ndim == 2 else image.shape[2]
+    if not min_channels <= channels <= max_channels:
+        raise ValueError(
+            f"{name} must have between {min_channels} and {max_channels} channels, got {channels}"
+        )
+    return channels
+
+
+def require_odd(value: int, name: str) -> None:
+    """Raise ValueError unless `value` is odd."""
+    if value % 2 == 0:
+        raise ValueError(f"{name} must be odd, got {value}")
+
+
+def require_spatial_mask(mask: np.ndarray, image: np.ndarray, name: str = "mask") -> None:
+    """Raise ValueError/TypeError unless `mask` is a valid spatial mask for `image`.
+
+    `mask` must be uint8, 2D, and match `image`'s spatial size (H, W) --
+    regardless of `image`'s channel count or dtype, since a mask selects
+    pixel positions, not per-channel values. Unlike
+    `require_same_shape_and_dtype`, which wrongly demands full shape+dtype
+    equality between two same-kind images.
+    """
+    require_dtype(mask, (np.uint8,), name)
+    require_image_ndim(mask, ndims=(2,))
+    spatial_shape = image.shape[:2]
+    if mask.shape != spatial_shape:
+        raise ValueError(
+            f"{name} must have shape {spatial_shape} (matching image's spatial size), "
+            f"got {mask.shape}"
+        )
+
+
+def require_positive_integral(value: object, name: str) -> None:
+    """Raise TypeError unless `value` is an integral number, then ValueError unless it's positive.
+
+    Unlike `require_positive_int`, which only accepts a plain Python `int`,
+    this accepts any `numbers.Integral` (including NumPy integer scalars) --
+    for parameters like a histogram bin count that may legitimately arrive
+    as `np.int32`.
+    """
+    require_integral(value, name)
+    assert isinstance(value, numbers.Integral)  # narrows for the type checker
+    if value <= 0:
+        raise ValueError(f"{name} must be positive, got {value}")
+
+
+def require_range(value: object, low: float, high: float, name: str) -> None:
+    """Raise TypeError unless `value` is a real number, then ValueError unless
+    `low <= value <= high`."""
+    require_real_number(value, name)
+    assert isinstance(value, numbers.Real)  # narrows for the type checker
+    if not low <= _safe_float(value) <= high:
+        raise ValueError(f"{name} must be between {low} and {high}, got {value}")
+
+
+def require_fits_dtype(value: object, dtype: np.dtype | type, name: str) -> None:
+    """Raise ValueError unless `value` fits within `dtype`'s representable range.
+
+    For parameters like `threshold`'s `max_value` that OpenCV silently
+    saturates rather than rejects when out of range for the image's
+    integer dtype (e.g. ``300`` silently becomes ``255`` for a ``uint8``
+    image) — verified directly against ``cv2.threshold``. Floating-point
+    dtypes have no meaningful bound here and are skipped.
+    """
+    require_real_number(value, name)
+    assert isinstance(value, numbers.Real)  # narrows for the type checker
+    if np.issubdtype(dtype, np.integer):
+        info = np.iinfo(dtype)
+        if not info.min <= _safe_float(value) <= info.max:
+            raise ValueError(
+                f"{name} must fit within the range of {np.dtype(dtype).name} "
+                f"([{info.min}, {info.max}]), got {value}"
+            )
+
+
+def require_same_shape_and_dtype(
+    image_a: np.ndarray, image_b: np.ndarray, name_a: str = "image_a", name_b: str = "image_b"
+) -> None:
+    """Raise ValueError/TypeError unless `image_a` and `image_b` share shape and dtype.
+
+    Mismatched dtype passed uncaught into OpenCV's element-wise ops (e.g.
+    ``cv2.bitwise_and``, ``cv2.addWeighted``) surfaces as a raw, unfriendly
+    ``cv2.error`` rather than a clear library error.
+    """
+    if image_a.shape != image_b.shape:
+        raise ValueError(
+            f"{name_a} and {name_b} must have the same shape, got "
+            f"{image_a.shape} and {image_b.shape}"
+        )
+    if image_a.dtype != image_b.dtype:
+        raise TypeError(
+            f"{name_a} and {name_b} must have the same dtype, got "
+            f"{image_a.dtype} and {image_b.dtype}"
+        )