Skip to content

🐍 Geometric Computer Vision Library for Spatial AI

63.3 KB
Raw Blame
# LICENSE HEADER MANAGED BY add-license-header
#
# Copyright 2018 Kornia Team
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
#     http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
#

import io
import re
import struct
import warnings
import zlib
from pathlib import Path

import kornia_rs
import numpy as np
import pytest
import torch

from kornia.color import rgb_to_grayscale
from kornia.core.exceptions import ShapeError, TypeCheckError, ValueCheckError
from kornia.io import ImageLoadType, load_image, write_image
from kornia.io.io import _read_jpeg_components, _read_png_chunks


def create_random_img8(height: int, width: int, channels: int) -> np.ndarray:
    return (np.random.rand(height, width, channels) * 255).astype(np.uint8)  # noqa: NPY002


def create_random_img8_torch(height: int, width: int, channels: int, device=None) -> torch.Tensor:
    return (torch.rand(channels, height, width, device=device) * 255).to(torch.uint8)


def write_random_png_u16(path: Path, mode: str) -> None:
    """Write a random 16-bit PNG, ``"mono"`` (grayscale) or ``"rgba"``, with kornia-rs directly."""
    channels = {"mono": 1, "rgba": 4}[mode]
    img_np = np.random.randint(0, 65535, (4, 5, channels)).astype(np.uint16)  # noqa: NPY002
    kornia_rs.io.write_image_png_u16(str(path), img_np, mode=mode)


def _png_chunk(kind: bytes, data: bytes) -> bytes:
    return struct.pack(">I", len(data)) + kind + data + struct.pack(">I", zlib.crc32(kind + data) & 0xFFFFFFFF)


def write_indexed_png(path: Path, indices: np.ndarray, palette: list, alpha: bytes | None = None) -> None:
    """Write an 8-bit palette PNG (colour type 3) byte by byte, so the test needs no image library."""
    height, width = indices.shape
    raw = b"".join(b"\x00" + indices[row].astype(np.uint8).tobytes() for row in range(height))
    chunks = [
        _png_chunk(b"IHDR", struct.pack(">IIBBBBB", width, height, 8, 3, 0, 0, 0)),
        _png_chunk(b"PLTE", bytes(channel for colour in palette for channel in colour)),
    ]
    if alpha is not None:
        chunks.append(_png_chunk(b"tRNS", alpha))
    chunks += [_png_chunk(b"IDAT", zlib.compress(raw)), _png_chunk(b"IEND", b"")]
    path.write_bytes(b"\x89PNG\r\n\x1a\n" + b"".join(chunks))


def write_png_with_trns(path: Path, pixels: np.ndarray, colour_type: int, trns: bytes | None = None) -> None:
    """Write an 8-bit gray (colour type 0) or RGB (2) PNG with an optional tRNS colour key, byte by byte."""
    height, width = pixels.shape[:2]
    raw = b"".join(b"\x00" + pixels[row].astype(np.uint8).tobytes() for row in range(height))
    chunks = [_png_chunk(b"IHDR", struct.pack(">IIBBBBB", width, height, 8, colour_type, 0, 0, 0))]
    if trns is not None:
        chunks.append(_png_chunk(b"tRNS", trns))
    chunks += [_png_chunk(b"IDAT", zlib.compress(raw)), _png_chunk(b"IEND", b"")]
    path.write_bytes(b"\x89PNG\r\n\x1a\n" + b"".join(chunks))


def corrupt_chunk_crc(path: Path, kind: bytes) -> None:
    """Add 1 to the stored CRC of the first ``kind`` chunk, leaving its length and body intact."""
    data = bytearray(path.read_bytes())
    start = data.index(kind) - 4  # the 4-byte length precedes the chunk type
    crc_at = start + 8 + int.from_bytes(data[start : start + 4], "big")
    data[crc_at : crc_at + 4] = ((int.from_bytes(data[crc_at : crc_at + 4], "big") + 1) & 0xFFFFFFFF).to_bytes(4, "big")
    path.write_bytes(bytes(data))


PALETTE = [(255, 255, 0), (0, 255, 0), (255, 0, 0), (0, 0, 255)]
PALETTE_INDICES = np.array([[2, 1, 0], [3, 0, 1]], dtype=np.uint8)  # H = 2, W = 3


@pytest.fixture(scope="session")
def png_image(tmp_path_factory):
    """RGB PNG written locally so load tests do not depend on the network."""
    filename = tmp_path_factory.mktemp("data") / "image.png"
    img_rgb = np.random.randint(0, 255, (32, 32, 3), dtype=np.uint8)  # noqa: NPY002
    kornia_rs.io.write_image_png_u8(str(filename), img_rgb, mode="rgb")
    return filename


@pytest.fixture(scope="session")
def rgba_png_image(tmp_path_factory):
    """Create an RGBA PNG image for testing."""
    filename = tmp_path_factory.mktemp("data") / "rgba_image.png"
    img_rgba = np.random.randint(0, 255, (32, 32, 4), dtype=np.uint8)  # noqa: NPY002
    kornia_rs.io.write_image_png_u8(str(filename), img_rgba, mode="rgba")
    return filename


@pytest.fixture(scope="session")
def jpg_image(tmp_path_factory):
    """RGB JPEG written locally so load tests do not depend on the network."""
    filename = tmp_path_factory.mktemp("data") / "image.jpg"
    write_image(str(filename), create_random_img8_torch(32, 32, 3))
    return filename


@pytest.fixture(scope="session")
def images_fn(png_image, jpg_image):
    return {"png": png_image, "jpg": jpg_image}


class TestIoImage:
    @pytest.mark.parametrize(
        ("suffix", "channels", "dtype"),
        [
            (".png", 1, torch.uint8),  # read_image_png_u8
            (".png", 1, torch.uint16),  # read_image_png_u16
            (".png", 3, torch.uint8),  # read_image (RGB PNG)
            (".jpg", 3, torch.uint8),  # read_image_jpegturbo
            (".tiff", 3, torch.uint8),  # read_image (any other extension)
        ],
        ids=["png-gray8", "png-gray16", "png-rgb8", "jpg-rgb8", "tiff-rgb8"],
    )
    def test_truncated_image_decode_error_includes_path(self, suffix, channels, dtype, tmp_path: Path) -> None:
        pixels = (torch.arange(channels * 64 * 64, dtype=torch.int32) * 37 % 251).reshape(channels, 64, 64).to(dtype)
        path = tmp_path / f"truncated_{channels}c_{str(dtype).removeprefix('torch.')}{suffix}"
        write_image(path, pixels)
        data = path.read_bytes()
        path.write_bytes(data[: len(data) // 2])

        with pytest.raises(ValueError, match=re.escape(path.name)) as exc_info:
            load_image(path, ImageLoadType.UNCHANGED)

        assert exc_info.value.__cause__ is not None
        assert str(exc_info.value.__cause__) in str(exc_info.value)

    @pytest.mark.parametrize(
        ("suffix", "error"), [(".png", FileNotFoundError), (".jpg", FileNotFoundError), (".tiff", FileNotFoundError)]
    )
    def test_missing_file_keeps_its_os_error(self, suffix, error, tmp_path: Path) -> None:
        # a missing file is not a decode failure: callers catching FileNotFoundError or OSError keep working
        with pytest.raises(error, match=re.escape(f"missing{suffix}")):
            load_image(tmp_path / f"missing{suffix}")

    @pytest.mark.parametrize("suffix", [".jpg", ".tiff", ".xyz"])
    def test_directory_path_raises_os_error_naming_the_path(self, suffix, tmp_path: Path) -> None:
        # every format path goes through open(), so a directory names itself instead of a bare OSError (.jpg, .tiff)
        # or a ValueError for an unrecognised format (.xyz); Windows raises PermissionError for open() on a directory,
        # POSIX raises IsADirectoryError
        (tmp_path / f"dir{suffix}").mkdir()
        with pytest.raises((IsADirectoryError, PermissionError), match=re.escape(f"dir{suffix}")):
            load_image(tmp_path / f"dir{suffix}")

    def test_smoke(self, tmp_path: Path) -> None:
        height, width = 4, 5
        img_th: torch.Tensor = create_random_img8_torch(height, width, 3)

        file_path = tmp_path / "image.jpg"
        write_image(str(file_path), img_th)

        assert file_path.is_file()

        img_load: torch.Tensor = load_image(str(file_path), ImageLoadType.UNCHANGED)

        assert img_th.shape == img_load.shape
        assert img_th.shape[1:] == (height, width)
        assert str(img_th.device) == "cpu"

    def test_device(self, device, png_image: Path) -> None:
        file_path = Path(png_image)

        assert file_path.is_file()

        img_th: torch.Tensor = load_image(file_path, ImageLoadType.UNCHANGED, str(device))
        assert str(img_th.device) == str(device)

    @pytest.mark.parametrize("ext", ["png", "jpg"])
    @pytest.mark.parametrize(
        "channels,load_type,expected_type,expected_channels",
        [
            # NOTE: these tests which should write and load images with channel size != 3, didn't do it
            # (1, ImageLoadType.GRAY8, torch.uint8, 1),
            (3, ImageLoadType.GRAY8, torch.uint8, 1),
            # (4, ImageLoadType.GRAY8, torch.uint8, 1),
            # (1, ImageLoadType.GRAY32, torch.float32, 1),
            (3, ImageLoadType.GRAY32, torch.float32, 1),
            # (4, ImageLoadType.GRAY32, torch.float32, 1),
            (3, ImageLoadType.RGB8, torch.uint8, 3),
            # (1, ImageLoadType.RGB8, torch.uint8, 3),
            (3, ImageLoadType.RGBA8, torch.uint8, 4),
            # (1, ImageLoadType.RGB32, torch.float32, 3),
            (3, ImageLoadType.RGB32, torch.float32, 3),
        ],
    )
    def test_load_image(self, images_fn, ext, channels, load_type, expected_type, expected_channels):
        file_path = images_fn[ext]

        assert file_path.is_file()

        img = load_image(file_path, load_type)
        assert img.shape[0] == expected_channels
        assert img.dtype == expected_type

    @pytest.mark.parametrize(
        "load_type,expected_type,expected_channels",
        [
            (ImageLoadType.UNCHANGED, torch.uint8, 4),
            (ImageLoadType.GRAY8, torch.uint8, 1),
            (ImageLoadType.GRAY32, torch.float32, 1),
            (ImageLoadType.RGB8, torch.uint8, 3),
            (ImageLoadType.RGBA8, torch.uint8, 4),
            (ImageLoadType.RGB32, torch.float32, 3),
        ],
    )
    def test_load_rgba_png(self, rgba_png_image, load_type, expected_type, expected_channels):
        img = load_image(rgba_png_image, load_type)
        assert img.shape[0] == expected_channels
        assert img.dtype == expected_type

    @pytest.mark.parametrize("channels,mode", [(1, "mono"), (3, "rgb")])
    def test_load_opaque_image_as_rgba(self, tmp_path: Path, channels: int, mode: str) -> None:
        pixels = np.full((2, 2, channels), 64, dtype=np.uint8)
        path = tmp_path / "image.png"
        kornia_rs.io.write_image_png_u8(str(path), pixels, mode=mode)

        rgba = load_image(path, ImageLoadType.RGBA8)

        assert rgba.shape == (4, 2, 2)
        assert torch.equal(rgba[:3], torch.full((3, 2, 2), 64, dtype=torch.uint8))
        assert torch.equal(rgba[3], torch.full((2, 2), 255, dtype=torch.uint8))

    def test_unchanged_loads_an_8_bit_grayscale_png_as_one_uint8_channel(self, tmp_path: Path) -> None:
        img = create_random_img8_torch(4, 5, 1)
        path = tmp_path / "image.png"
        write_image(path, img)
        loaded = load_image(path, ImageLoadType.UNCHANGED)
        assert loaded.dtype == torch.uint8
        assert loaded.shape == (1, 4, 5)
        assert torch.equal(loaded, img)

    @pytest.mark.parametrize("ext", ["jpg"])
    @pytest.mark.parametrize("channels", [3])
    def test_write_image(self, device, tmp_path, ext, channels):
        height, width = 4, 5
        img_th: torch.Tensor = create_random_img8_torch(height, width, channels, device)

        file_path = tmp_path / f"image.{ext}"
        write_image(file_path, img_th)

        assert file_path.is_file()

    @pytest.mark.parametrize("shape", [(1, 1, 5), (1, 5, 1)])
    def test_write_image_one_row_or_one_column_grayscale(self, tmp_path: Path, shape) -> None:
        # (1, 1, W) and (1, H, 1) must keep their unit height or width on the way to the encoder.
        img = torch.arange(5, dtype=torch.uint8).reshape(shape) * 50
        path = tmp_path / "line.png"

        write_image(path, img)

        loaded = load_image(path, ImageLoadType.UNCHANGED)
        assert loaded.shape == shape
        assert torch.equal(loaded, img)


class TestIndexedPng:
    def test_unchanged_keeps_the_palette_indices(self, tmp_path: Path) -> None:
        path = tmp_path / "indexed.png"
        write_indexed_png(path, PALETTE_INDICES, PALETTE)
        out = load_image(path, ImageLoadType.UNCHANGED)
        assert out.dtype == torch.uint8
        assert out.tolist() == [PALETTE_INDICES.tolist()]

    @pytest.mark.parametrize("load_type", [ImageLoadType.RGB8, ImageLoadType.RGB32])
    def test_rgb_types_expand_the_palette(self, tmp_path: Path, device, load_type) -> None:
        path = tmp_path / "indexed.png"
        write_indexed_png(path, PALETTE_INDICES, PALETTE)
        expected = torch.tensor([PALETTE[i] for i in PALETTE_INDICES.flatten()], dtype=torch.uint8, device=device)
        expected = expected.T.reshape(3, 2, 3)
        if load_type == ImageLoadType.RGB32:
            expected = expected.float() / 255.0
        out = load_image(path, load_type, device=str(device))
        assert out.device.type == torch.device(device).type
        torch.testing.assert_close(out, expected)

    def test_gray8_is_the_gray_of_the_palette_colours(self, tmp_path: Path) -> None:
        path = tmp_path / "indexed.png"
        write_indexed_png(path, PALETTE_INDICES, PALETTE)
        # cv2.cvtColor(rgb, cv2.COLOR_RGB2GRAY): red 76, green 150, yellow 226, blue 29
        expected = torch.tensor([[[76, 150, 226], [29, 226, 150]]], dtype=torch.uint8)
        torch.testing.assert_close(load_image(path, ImageLoadType.GRAY8), expected)

    def test_rgba8_takes_alpha_from_the_trns_chunk(self, tmp_path: Path, device) -> None:
        path = tmp_path / "indexed_trns.png"
        write_indexed_png(path, PALETTE_INDICES, PALETTE, alpha=bytes([0, 128]))  # entries 2 and 3 stay opaque
        out = load_image(path, ImageLoadType.RGBA8, device=str(device))
        assert out.device.type == torch.device(device).type
        assert out.shape == (4, 2, 3)
        assert out[3].tolist() == [[255, 128, 0], [255, 0, 128]]

    @pytest.mark.parametrize(
        "load_type",
        [ImageLoadType.GRAY8, ImageLoadType.RGB8, ImageLoadType.RGBA8, ImageLoadType.GRAY32, ImageLoadType.RGB32],
    )
    def test_empty_trns_chunk_keeps_palette_entries_opaque(self, tmp_path: Path, load_type) -> None:
        path = tmp_path / "empty_trns.png"
        write_indexed_png(path, PALETTE_INDICES, PALETTE, alpha=b"")

        out = load_image(path, load_type)

        expected_rgb = torch.tensor([PALETTE[i] for i in PALETTE_INDICES.flatten()], dtype=torch.uint8).T.reshape(
            3, 2, 3
        )
        if load_type == ImageLoadType.RGBA8:
            assert out.shape == (4, 2, 3)
            assert out[3].tolist() == [[255, 255, 255], [255, 255, 255]]
            torch.testing.assert_close(out[:3], expected_rgb)
        elif load_type == ImageLoadType.RGB8:
            assert out.shape == (3, 2, 3)
            torch.testing.assert_close(out, expected_rgb)
        elif load_type == ImageLoadType.RGB32:
            assert out.shape == (3, 2, 3)
            expected = expected_rgb.float() / 255.0
            torch.testing.assert_close(out, expected)
        elif load_type == ImageLoadType.GRAY8:
            assert out.shape == (1, 2, 3)
            torch.testing.assert_close(out, torch.tensor([[[76, 150, 226], [29, 226, 150]]], dtype=torch.uint8))
        else:
            assert out.shape == (1, 2, 3)
            expected = rgb_to_grayscale(expected_rgb.float() / 255.0)
            torch.testing.assert_close(out, expected)

    def test_rgb8_composites_transparent_palette_entries_over_white(self, tmp_path: Path) -> None:
        path = tmp_path / "indexed_trns.png"
        write_indexed_png(path, PALETTE_INDICES, PALETTE, alpha=bytes([0, 128]))
        out = load_image(path, ImageLoadType.RGB8)
        # round(c * a / 255 + 255 * (1 - a / 255)): yellow at alpha 0 -> white, green at alpha 128 -> (127, 255, 127)
        assert out[:, 0, 2].tolist() == [255, 255, 255]
        assert out[:, 0, 1].tolist() == [127, 255, 127]
        assert out[:, 0, 0].tolist() == [255, 0, 0]

    def test_index_beyond_the_palette_raises_naming_the_file(self, tmp_path: Path) -> None:
        path = tmp_path / "short_palette.png"
        write_indexed_png(path, PALETTE_INDICES, PALETTE[:2])  # indices 2 and 3 have no colour
        with pytest.raises(ValueError, match=re.escape(path.name)):
            load_image(path, ImageLoadType.RGB8)

    def test_index_equal_to_the_palette_length_raises_naming_the_file(self, tmp_path: Path, device) -> None:
        path = tmp_path / "three_entries.png"
        write_indexed_png(path, PALETTE_INDICES, PALETTE[:3])  # entries 0..2; the pixel with index 3 has no colour
        with pytest.raises(ValueError, match=re.escape(path.name)):
            load_image(path, ImageLoadType.RGB8, device=str(device))

    def test_a_palette_that_is_not_whole_rgb_entries_raises_naming_the_file(self, tmp_path: Path) -> None:
        path = tmp_path / "bad_plte.png"
        write_indexed_png(path, PALETTE_INDICES, [*PALETTE, (7,)])  # a 13-byte PLTE chunk
        with pytest.raises(ValueError, match=re.escape(path.name)):
            load_image(path, ImageLoadType.RGB8)


class TestCorruptPngChunks:
    # load_image reads PLTE and tRNS itself, so it checks their CRC and length like a PNG decoder; kornia-rs 0.2.0
    # accepts a tRNS chunk with a bad CRC, which Pillow 12.3 rejects ("cannot identify image file")
    @pytest.mark.parametrize("load_type", [ImageLoadType.RGBA8, ImageLoadType.RGB8])
    def test_palette_trns_with_a_bad_crc_raises_naming_the_file(self, tmp_path: Path, load_type) -> None:
        path = tmp_path / "bad_trns.png"
        write_indexed_png(path, PALETTE_INDICES, PALETTE, alpha=bytes([0, 128]))
        corrupt_chunk_crc(path, b"tRNS")
        with pytest.raises(ValueError, match=re.escape(path.name) + ".*tRNS"):
            load_image(path, load_type)

    @pytest.mark.parametrize("load_type", [ImageLoadType.RGBA8, ImageLoadType.GRAY8])
    def test_colour_key_with_a_bad_crc_raises_naming_the_file(self, tmp_path: Path, load_type) -> None:
        path = tmp_path / "bad_key.png"
        write_png_with_trns(
            path, np.array([[10, 20, 10], [20, 10, 20]], dtype=np.uint8), colour_type=0, trns=struct.pack(">H", 10)
        )
        corrupt_chunk_crc(path, b"tRNS")
        with pytest.raises(ValueError, match=re.escape(path.name) + ".*tRNS"):
            load_image(path, load_type)

    def test_unchanged_does_not_read_the_trns_chunk(self, tmp_path: Path) -> None:
        # UNCHANGED returns what kornia-rs decodes, the indices, and never looks at tRNS, so its CRC is not checked
        path = tmp_path / "bad_trns.png"
        write_indexed_png(path, PALETTE_INDICES, PALETTE, alpha=bytes([0, 128]))
        corrupt_chunk_crc(path, b"tRNS")
        assert load_image(path, ImageLoadType.UNCHANGED).tolist() == [PALETTE_INDICES.tolist()]

    def test_plte_with_a_bad_crc_raises_naming_the_file(self, tmp_path: Path) -> None:
        path = tmp_path / "bad_plte.png"
        write_indexed_png(path, PALETTE_INDICES, PALETTE)
        corrupt_chunk_crc(path, b"PLTE")
        with pytest.raises(ValueError, match=re.escape(path.name) + ".*PLTE"):
            _read_png_chunks(path)
        with pytest.raises(ValueError, match=re.escape(path.name)):  # kornia-rs rejects a bad PLTE CRC itself
            load_image(path, ImageLoadType.RGB8)

    def test_truncated_plte_body_raises_naming_the_file(self, tmp_path: Path) -> None:
        path = tmp_path / "truncated.png"
        write_indexed_png(path, PALETTE_INDICES, PALETTE)
        data = path.read_bytes()
        path.write_bytes(data[: data.index(b"PLTE") + 4 + 6])  # 6 of the 12 palette bytes, then end of file
        with pytest.raises(ValueError, match=re.escape(path.name) + ".*PLTE.*truncated"):
            _read_png_chunks(path)
        with pytest.raises(ValueError, match=re.escape(path.name)) as error:
            load_image(path, ImageLoadType.RGB8)
        assert "palette entry" not in str(error.value)


class TestGrayJpeg:
    @staticmethod
    def _gray() -> torch.Tensor:
        return (torch.arange(12 * 20) % 251).to(torch.uint8).view(1, 12, 20)  # H = 12, W = 20

    def test_unchanged_keeps_one_channel(self, tmp_path: Path) -> None:
        path = tmp_path / "gray.jpg"
        write_image(path, self._gray(), quality=95)
        out = load_image(path, ImageLoadType.UNCHANGED)
        assert out.shape == (1, 12, 20)
        torch.testing.assert_close(out, load_image(path, ImageLoadType.GRAY8))

    @pytest.mark.parametrize("load_type", [ImageLoadType.UNCHANGED, ImageLoadType.GRAY8])
    def test_one_channel_owns_a_contiguous_buffer(self, tmp_path: Path, load_type) -> None:
        path = tmp_path / "gray.jpg"
        write_image(path, self._gray(), quality=95)
        out = load_image(path, load_type)
        assert out.is_contiguous()
        assert out.untyped_storage().nbytes() == 12 * 20  # not the three-channel decode buffer

    def test_rgb8_repeats_the_gray_channel(self, tmp_path: Path) -> None:
        path = tmp_path / "gray.jpg"
        write_image(path, self._gray(), quality=95)
        gray = load_image(path, ImageLoadType.UNCHANGED)
        torch.testing.assert_close(load_image(path, ImageLoadType.RGB8), gray.expand(3, -1, -1))

    def test_large_app_segment_before_the_frame_header(self, tmp_path: Path) -> None:
        plain = tmp_path / "gray.jpg"
        write_image(plain, self._gray(), quality=95)
        data = plain.read_bytes()
        payload = b"Exif\x00\x00" + b"x" * 60000  # a camera-sized APP1 block between SOI and the frame header
        tagged = tmp_path / "gray_exif.jpg"
        tagged.write_bytes(data[:2] + b"\xff\xe1" + struct.pack(">H", len(payload) + 2) + payload + data[2:])
        out = load_image(tagged, ImageLoadType.UNCHANGED)
        assert out.shape == (1, 12, 20)
        torch.testing.assert_close(out, load_image(plain, ImageLoadType.UNCHANGED))

    @pytest.mark.parametrize(
        ("marker", "fill", "components"),
        [(0xC0, b"", 1), (0xC2, b"", 1), (0xC2, b"\xff\xff", 1), (0xC2, b"", 3), (0xC9, b"", 1)],
        ids=["baseline", "progressive", "progressive-after-fill-bytes", "progressive-3-components", "arithmetic"],
    )
    def test_frame_header_component_count(self, tmp_path: Path, marker, fill, components) -> None:
        # SOI, an APP0 segment, optional fill bytes, then a baseline (C0), progressive (C2) or arithmetic (C9) frame
        # header: precision 8, height 12, width 20, the component count and 3 bytes per component
        app0 = b"\xff\xe0" + struct.pack(">H", 16) + b"JFIF\x00" + bytes(9)
        sof = struct.pack(">BHHB", 8, 12, 20, components) + bytes(3 * components)
        header = b"\xff\xd8" + app0 + fill + bytes([0xFF, marker]) + struct.pack(">H", len(sof) + 2) + sof
        path = tmp_path / "header.jpg"
        path.write_bytes(header)
        assert _read_jpeg_components(path) == components

    def test_color_jpeg_unchanged_keeps_three_channels(self, tmp_path: Path) -> None:
        path = tmp_path / "color.jpg"
        write_image(path, create_random_img8_torch(12, 20, 3))
        assert load_image(path, ImageLoadType.UNCHANGED).shape == (3, 12, 20)


class TestAlphaRounding:
    def test_semi_transparent_rgba_rounds_after_compositing(self, tmp_path: Path) -> None:
        path = tmp_path / "rgba.png"
        pixels = np.zeros((2, 3, 4), dtype=np.uint8)
        pixels[...] = (200, 100, 50, 64)
        kornia_rs.io.write_image_png_u8(str(path), pixels, mode="rgba")
        # round(c * 64 / 255 + 255 * (1 - 64 / 255)) for c = 200, 100, 50 -> 241.2, 216.1, 203.5
        assert load_image(path, ImageLoadType.RGB8)[:, 0, 0].tolist() == [241, 216, 204]


class TestWriteImageValidation:
    def test_rgba_png_round_trips(self, tmp_path: Path) -> None:
        rgba = create_random_img8_torch(4, 5, 4)
        path = tmp_path / "rgba.png"
        write_image(path, rgba)
        assert torch.equal(load_image(path, ImageLoadType.UNCHANGED), rgba)

    def test_rgba_16_bit_png_round_trips(self, tmp_path: Path) -> None:
        rgba = torch.randint(0, 65535, (4, 4, 5), dtype=torch.int32).to(torch.uint16)
        path = tmp_path / "rgba16.png"
        write_image(path, rgba)
        assert torch.equal(load_image(path, ImageLoadType.UNCHANGED), rgba)

    @pytest.mark.parametrize("ext", [".jpg", ".tiff"])
    def test_rgba_to_a_format_without_alpha_raises_and_writes_nothing(self, tmp_path: Path, ext) -> None:
        path = tmp_path / f"rgba{ext}"
        with pytest.raises(ShapeError, match="4-channel"):
            write_image(path, create_random_img8_torch(4, 5, 4))
        assert not path.exists()

    @pytest.mark.parametrize("ext", [".png", ".jpg", ".tiff"])
    def test_two_channels_raise_and_write_nothing(self, tmp_path: Path, ext) -> None:
        path = tmp_path / f"two{ext}"
        with pytest.raises(ShapeError, match="2-channel"):
            write_image(path, create_random_img8_torch(4, 5, 2))
        assert not path.exists()

    def test_an_unsupported_channel_count_is_still_a_value_error(self, tmp_path: Path) -> None:
        # kornia-rs raised ValueError for these before write_image checked them; ShapeError keeps that catchable
        with pytest.raises(ValueError, match="5-channel"):
            write_image(tmp_path / "five.png", create_random_img8_torch(4, 5, 5))

    @pytest.mark.parametrize("dtype", [torch.uint8, torch.uint16, torch.float32])
    def test_tif_round_trips_every_tiff_dtype(self, tmp_path: Path, dtype) -> None:
        image = torch.arange(3 * 4 * 5).view(3, 4, 5)
        image = image.to(dtype) / 60 if dtype == torch.float32 else image.to(dtype)
        path = tmp_path / "short.tif"
        write_image(path, image)
        assert torch.equal(load_image(path, ImageLoadType.UNCHANGED), image)

    @pytest.mark.parametrize("name", ["upper.JPG", "upper.PNG", "short.tif", "mixed.TiFf"])
    def test_extension_case_and_tif(self, tmp_path: Path, name) -> None:
        rgb = create_random_img8_torch(4, 5, 3)
        path = tmp_path / name
        write_image(path, rgb)
        loaded = load_image(path, ImageLoadType.UNCHANGED)
        assert loaded.shape == (3, 4, 5)
        if not name.lower().endswith(".jpg"):
            assert torch.equal(loaded, rgb)  # lossless formats round-trip exactly

    def test_batched_tensor_raises_and_writes_nothing(self, tmp_path: Path) -> None:
        path = tmp_path / "batched.png"
        with pytest.raises(ShapeError, match=re.escape("(C, H, W)")):
            write_image(path, create_random_img8_torch(4, 5, 3)[None])
        assert not path.exists()


class TestColourKeyPng:
    # colour type 0 (gray) and 2 (RGB) PNGs carry a tRNS colour key: pixels equal to it are transparent
    def test_gray_key_becomes_transparent_in_rgba8(self, tmp_path: Path) -> None:
        path = tmp_path / "gray_key.png"
        write_png_with_trns(
            path, np.array([[10, 20, 10], [20, 10, 20]], dtype=np.uint8), colour_type=0, trns=struct.pack(">H", 10)
        )
        # Pillow 12.3 Image.open(path).convert("RGBA") alpha: [[0, 255, 0], [255, 0, 255]]
        assert load_image(path, ImageLoadType.RGBA8)[3].tolist() == [[0, 255, 0], [255, 0, 255]]

    def test_gray_key_composites_over_white_in_gray8(self, tmp_path: Path) -> None:
        path = tmp_path / "gray_key.png"
        write_png_with_trns(
            path, np.array([[10, 20, 10], [20, 10, 20]], dtype=np.uint8), colour_type=0, trns=struct.pack(">H", 10)
        )
        # the keyed 10s composite over white to 255; the opaque 20s keep their value. Pillow 12.3:
        # Image.alpha_composite(Image.new("RGBA", (3, 2), "white"), Image.open(path).convert("RGBA")).convert("L")
        assert load_image(path, ImageLoadType.GRAY8)[0].tolist() == [[255, 20, 255], [20, 255, 20]]

    def test_rgb_key_composites_over_white_in_rgb8(self, tmp_path: Path) -> None:
        pixels = np.zeros((2, 3, 3), dtype=np.uint8)
        pixels[0, 0] = (1, 2, 3)
        path = tmp_path / "rgb_key.png"
        write_png_with_trns(path, pixels, colour_type=2, trns=struct.pack(">HHH", 1, 2, 3))
        out = load_image(path, ImageLoadType.RGB8)
        assert out[:, 0, 0].tolist() == [255, 255, 255]
        assert out[:, 1, 2].tolist() == [0, 0, 0]

    def test_rgb_key_needs_every_sample_to_match(self, tmp_path: Path) -> None:
        pixels = np.zeros((2, 3, 3), dtype=np.uint8)
        pixels[0] = [(1, 2, 3), (1, 2, 0), (1, 0, 0)]  # the key, then two pixels sharing some of its samples
        path = tmp_path / "rgb_key_partial.png"
        write_png_with_trns(path, pixels, colour_type=2, trns=struct.pack(">HHH", 1, 2, 3))
        # Pillow 12.3 Image.open(path).convert("RGBA") alpha: [[0, 255, 255], [255, 255, 255]]
        assert load_image(path, ImageLoadType.RGBA8)[3].tolist() == [[0, 255, 255], [255, 255, 255]]

    def test_unchanged_ignores_the_key(self, tmp_path: Path) -> None:
        path = tmp_path / "gray_key.png"
        write_png_with_trns(
            path, np.array([[10, 20, 10], [20, 10, 20]], dtype=np.uint8), colour_type=0, trns=struct.pack(">H", 10)
        )
        assert load_image(path, ImageLoadType.UNCHANGED).shape == (1, 2, 3)

    def test_png_without_a_key_stays_opaque(self, tmp_path: Path) -> None:
        path = tmp_path / "gray_nokey.png"
        write_png_with_trns(path, np.array([[10, 20, 10], [20, 10, 20]], dtype=np.uint8), colour_type=0)
        assert load_image(path, ImageLoadType.RGBA8)[3].tolist() == [[255] * 3] * 2


class TestIoArgumentChecks:
    def test_write_into_a_missing_directory_raises_file_not_found(self, tmp_path: Path) -> None:
        path = tmp_path / "missing" / "x.png"
        with pytest.raises(FileNotFoundError, match="missing"):
            write_image(path, create_random_img8_torch(4, 5, 3))

    def test_write_into_a_file_as_directory_raises_not_a_directory(self, tmp_path: Path) -> None:
        parent = tmp_path / "plain_file"
        parent.write_bytes(b"")
        with pytest.raises(NotADirectoryError, match="plain_file"):
            write_image(parent / "x.png", create_random_img8_torch(4, 5, 3))

    def test_write_into_the_current_directory_with_a_bare_filename(self, tmp_path: Path, monkeypatch) -> None:
        monkeypatch.chdir(tmp_path)
        write_image("bare.png", create_random_img8_torch(4, 5, 3))
        assert (tmp_path / "bare.png").exists()

    @pytest.mark.parametrize("desired_type", ["RGB8", 2])
    def test_load_image_rejects_a_load_type_that_is_not_an_image_load_type(self, png_image, desired_type) -> None:
        with pytest.raises(TypeCheckError, match="ImageLoadType"):
            load_image(png_image, desired_type)

    @pytest.mark.parametrize("quality", [-1, 101, np.int64(101)])
    def test_write_image_rejects_quality_outside_0_100(self, tmp_path: Path, quality) -> None:
        with pytest.raises(ValueCheckError, match="quality"):
            write_image(tmp_path / "q.jpg", create_random_img8_torch(4, 5, 3), quality=quality)

    @pytest.mark.parametrize("quality", [80.5, True, "80"])
    def test_write_image_rejects_a_quality_that_is_not_an_integer(self, tmp_path: Path, quality) -> None:
        with pytest.raises(TypeCheckError, match="quality"):
            write_image(tmp_path / "q.jpg", create_random_img8_torch(4, 5, 3), quality=quality)

    def test_quality_is_validated_for_png_too(self, tmp_path: Path) -> None:
        with pytest.raises(ValueCheckError, match="quality"):
            write_image(tmp_path / "q.png", create_random_img8_torch(4, 5, 3), quality=101)

    @pytest.mark.parametrize("quality", [0, 100, np.int64(90)])
    def test_write_image_accepts_any_integer_quality_in_0_100(self, tmp_path: Path, quality) -> None:
        path = tmp_path / "q.jpg"
        write_image(path, create_random_img8_torch(4, 5, 3), quality=quality)
        assert load_image(path, ImageLoadType.RGB8).shape == (3, 4, 5)

    def test_write_image_rejects_a_non_tensor(self, tmp_path: Path) -> None:
        with pytest.raises(TypeCheckError):
            write_image(tmp_path / "n.png", np.zeros((3, 4, 5), dtype=np.uint8))


class TestSampleImages:
    def test_local_paths_create_no_cache_directory(self, tmp_path: Path) -> None:
        from kornia.io import get_sample_images

        path = tmp_path / "local.png"
        write_image(path, create_random_img8_torch(4, 5, 3))
        get_sample_images(paths=[str(path)], cache_dir=str(tmp_path / "cache"))
        assert not (tmp_path / "cache").exists()

    def test_a_relative_path_starting_with_http_is_a_local_file(self, tmp_path: Path, monkeypatch) -> None:
        from kornia.io import get_sample_images

        monkeypatch.chdir(tmp_path)
        write_image(tmp_path / "http_local.png", create_random_img8_torch(4, 5, 3))
        out = get_sample_images(paths=["http_local.png"], cache_dir=str(tmp_path / "cache"))
        assert out[0].shape == (3, 4, 5)

    def test_default_cache_dir_follows_the_hub_config(self, tmp_path: Path, monkeypatch) -> None:
        from unittest import mock

        from kornia.config import kornia_config
        from kornia.io import get_sample_images

        monkeypatch.setattr(kornia_config, "hub_cache_dir", str(tmp_path / "hub"))
        payload = tmp_path / "src.png"
        write_image(payload, create_random_img8_torch(4, 5, 3))
        with mock.patch("kornia.io.sample.urlopen") as mock_urlopen:
            mock_urlopen.return_value.__enter__.return_value.read.return_value = payload.read_bytes()
            get_sample_images(paths=["https://example.invalid/sample.png"])
        assert (tmp_path / "hub" / "images" / "sample.png").exists()

    @pytest.mark.parametrize("suffix", ["?token=abc", "#section"])
    def test_a_url_query_or_fragment_is_not_part_of_the_cache_name(self, tmp_path: Path, suffix) -> None:
        from unittest import mock

        from kornia.io import get_sample_images

        source = tmp_path / "source.png"
        write_indexed_png(source, PALETTE_INDICES, PALETTE)
        cache = tmp_path / "cache"
        with mock.patch("kornia.io.sample.urlopen") as mock_urlopen:
            mock_urlopen.return_value.__enter__.return_value.read.return_value = source.read_bytes()
            out = get_sample_images(paths=[f"https://example.invalid/x/palette.png{suffix}"], cache_dir=str(cache))
        assert sorted(p.name for p in cache.iterdir()) == ["palette.png"]
        assert (out[0][:, 0, 0] * 255).round().tolist() == [255.0, 0.0, 0.0]  # index 2 is red: the palette applies

    @pytest.mark.parametrize("entry_point", ["get_sample_images", "download_image"])
    @pytest.mark.parametrize(("variable", "timeout"), [(None, 30.0), ("5", 5.0), (" 0.5 ", 0.5)])
    def test_downloads_take_their_timeout_from_kornia_download_timeout(
        self, tmp_path: Path, monkeypatch, entry_point, variable, timeout
    ) -> None:
        # #5904: the fetch always used timeout=30, whatever KORNIA_DOWNLOAD_TIMEOUT said
        from unittest import mock

        from kornia.io.sample import download_image, get_sample_images

        if variable is None:
            monkeypatch.delenv("KORNIA_DOWNLOAD_TIMEOUT", raising=False)
        else:
            monkeypatch.setenv("KORNIA_DOWNLOAD_TIMEOUT", variable)
        source = tmp_path / "source.png"
        write_image(source, create_random_img8_torch(4, 5, 3))
        url = "https://example.invalid/sample.png"
        with mock.patch("kornia.io.sample.urlopen") as mock_urlopen:
            mock_urlopen.return_value.__enter__.return_value.read.return_value = source.read_bytes()
            if entry_point == "get_sample_images":
                get_sample_images(paths=[url], cache_dir=str(tmp_path / "cache"))
            else:
                download_image(url, str(tmp_path / "saved.png"))
        assert mock_urlopen.call_args.kwargs["timeout"] == timeout

    @pytest.mark.parametrize("variable", ["abc", "0", "-1"])
    def test_an_unusable_kornia_download_timeout_raises_before_downloading(
        self, tmp_path: Path, monkeypatch, variable
    ) -> None:
        from unittest import mock

        from kornia.io import get_sample_images

        monkeypatch.setenv("KORNIA_DOWNLOAD_TIMEOUT", variable)
        source = tmp_path / "source.png"
        write_image(source, create_random_img8_torch(4, 5, 3))
        cache = tmp_path / "cache"
        with mock.patch("kornia.io.sample.urlopen") as mock_urlopen:
            mock_urlopen.return_value.__enter__.return_value.read.return_value = source.read_bytes()
            with pytest.raises(ValueError, match="KORNIA_DOWNLOAD_TIMEOUT"):
                get_sample_images(paths=["https://example.invalid/sample.png"], cache_dir=str(cache))
            mock_urlopen.assert_not_called()
        assert not cache.exists() or list(cache.iterdir()) == []

    @pytest.mark.parametrize(
        "url", ["https://example.invalid", "https://example.invalid/", "https://example.invalid/dir/"]
    )
    def test_a_url_without_a_file_name_raises_before_downloading(self, tmp_path: Path, url) -> None:
        from unittest import mock

        from kornia.io import get_sample_images

        cache = tmp_path / "cache"
        with mock.patch("kornia.io.sample.urlopen") as mock_urlopen:
            with pytest.raises(ValueError, match=re.escape(url)):
                get_sample_images(paths=[url], cache_dir=str(cache))
            mock_urlopen.assert_not_called()
        assert not cache.exists()

    @pytest.mark.parametrize(
        "windows",
        [None, "refuses_replacing_an_open_file", "refuses_reading_a_file_being_replaced"],
        ids=["posix_replace", "windows_replace", "windows_read_during_replace"],
    )
    def test_concurrent_downloads_of_the_same_image_both_succeed(self, tmp_path: Path, windows) -> None:
        import os
        import threading
        from concurrent.futures import ThreadPoolExecutor
        from unittest import mock

        from kornia.io import get_sample_images

        image = create_random_img8_torch(4, 5, 3)
        source = tmp_path / "source.png"
        write_image(source, image)
        payload = source.read_bytes()
        cache = tmp_path / "cache"
        both_written = threading.Barrier(2, timeout=10)
        one_replace_at_a_time = threading.Lock()
        replacing = set()  # the threads whose os.replace has been called and has not returned yet
        a_call_moved_on = threading.Event()  # a call has returned or raised, or a read of the cache file was refused
        real_replace = os.replace
        real_open = open

        def replace_after_both_writes(src, dst):
            replacing.add(threading.get_ident())
            try:
                both_written.wait()  # both calls have missed the cache and finished writing before either replaces
                with one_replace_at_a_time:
                    if windows == "refuses_replacing_an_open_file" and os.path.exists(dst):
                        # Windows refuses to replace a file that another call has open
                        raise PermissionError(13, "Access is denied", dst)
                    if windows == "refuses_reading_a_file_being_replaced" and os.path.exists(dst):
                        a_call_moved_on.wait(timeout=10)  # this replace is still in flight while the other call goes on
                    return real_replace(src, dst)
            finally:
                replacing.discard(threading.get_ident())

        def open_refused_while_another_call_replaces(path, mode="r", *args, **kwargs):
            if (
                windows == "refuses_reading_a_file_being_replaced"
                and Path(path) == cache / "same.png"
                and replacing - {threading.get_ident()}
            ):
                a_call_moved_on.set()
                # Windows: opening a file that another call is replacing fails with access denied
                raise PermissionError(13, "Permission denied", str(path))
            return real_open(path, mode, *args, **kwargs)

        def fetch():
            try:
                return get_sample_images(paths=["https://example.invalid/x/same.png"], cache_dir=str(cache))[0]
            finally:
                a_call_moved_on.set()

        with (
            mock.patch("kornia.io.sample.urlopen") as mock_urlopen,
            mock.patch("kornia.io.sample.os.replace", replace_after_both_writes),
            mock.patch("kornia.io.io.open", open_refused_while_another_call_replaces, create=True),
            ThreadPoolExecutor(max_workers=2) as pool,
        ):
            mock_urlopen.return_value.__enter__.return_value.read.return_value = payload
            results = [future.result() for future in [pool.submit(fetch), pool.submit(fetch)]]
        expected = image.float() / 255.0
        for out in results:
            torch.testing.assert_close(out, expected)
        assert sorted(p.name for p in cache.iterdir()) == ["same.png"]  # no temporary file is left behind
        assert (cache / "same.png").read_bytes() == payload

    def test_a_download_that_is_not_an_image_is_not_cached(self, tmp_path: Path) -> None:
        from unittest import mock

        from kornia.io import get_sample_images

        cache = tmp_path / "cache"
        with mock.patch("kornia.io.sample.urlopen") as mock_urlopen:
            mock_urlopen.return_value.__enter__.return_value.read.return_value = b"<html>not found</html>"
            with pytest.raises(ValueError, match=re.escape("sample.png")):
                get_sample_images(paths=["https://example.invalid/sample.png"], cache_dir=str(cache))
        assert list(cache.iterdir()) == []  # neither the cache file nor the temporary file

    def test_a_download_that_is_not_an_image_leaves_another_calls_copy_in_place(self, tmp_path: Path) -> None:
        from unittest import mock

        from kornia.io import get_sample_images

        image = create_random_img8_torch(4, 5, 3)
        source = tmp_path / "source.png"
        write_image(source, image)
        cache = tmp_path / "cache"

        def body_read_while_another_call_publishes():
            (cache / "same.png").write_bytes(source.read_bytes())  # a call that also missed the cache publishes first
            return b"<html>not found</html>"

        with mock.patch("kornia.io.sample.urlopen") as mock_urlopen:
            mock_urlopen.return_value.__enter__.return_value.read.side_effect = body_read_while_another_call_publishes
            with pytest.raises(ValueError, match=re.escape("same.png")):
                get_sample_images(paths=["https://example.invalid/x/same.png"], cache_dir=str(cache))
        assert sorted(p.name for p in cache.iterdir()) == ["same.png"]  # no temporary file is left behind
        assert (cache / "same.png").read_bytes() == source.read_bytes()


class TestDownloadImage:
    """Offline pins for ``kornia.io.sample.download_image``; ``urlopen`` is mocked, no network is touched."""

    URL = "https://raw.githubusercontent.com/kornia/data/main/panda.jpg"

    def test_saves_the_fetched_bytes(self, tmp_path):
        from unittest import mock

        from PIL import Image as PILImage

        from kornia.io.sample import download_image

        payload = io.BytesIO()
        PILImage.new("RGB", (4, 3), (10, 20, 30)).save(payload, format="PNG")
        with mock.patch("kornia.io.sample.urlopen") as mock_urlopen:
            mock_urlopen.return_value.__enter__.return_value.read.return_value = payload.getvalue()
            dst = tmp_path / "panda.png"
            download_image(self.URL, str(dst))

        mock_urlopen.assert_called_once_with(self.URL, timeout=30)
        with PILImage.open(dst) as saved:
            assert saved.size == (4, 3)
            assert saved.getpixel((0, 0)) == (10, 20, 30)

    def test_writes_the_downloaded_bytes_without_decoding(self, tmp_path):
        from unittest import mock

        from kornia.io.sample import download_image

        payload = b"\xff\xd8 bytes that no image decoder accepts"
        with mock.patch("kornia.io.sample.urlopen") as mock_urlopen:
            mock_urlopen.return_value.__enter__.return_value.read.return_value = payload
            dst = tmp_path / "panda.jpg"
            download_image(self.URL, str(dst))
        assert dst.read_bytes() == payload
        assert sorted(p.name for p in tmp_path.iterdir()) == ["panda.jpg"]  # no temporary file is left behind

    def test_a_refused_replace_without_a_copy_raises_and_leaves_no_file(self, tmp_path):
        from unittest import mock

        from kornia.io.sample import download_image

        with (
            mock.patch("kornia.io.sample.urlopen") as mock_urlopen,
            mock.patch("kornia.io.sample.os.replace", side_effect=PermissionError(13, "Access is denied")),
        ):
            mock_urlopen.return_value.__enter__.return_value.read.return_value = b"payload"
            with pytest.raises(PermissionError):
                download_image(self.URL, str(tmp_path / "panda.jpg"))
        assert list(tmp_path.iterdir()) == []  # neither the destination nor the temporary file

    @pytest.mark.parametrize("existing", [b"payload", b"different", b"payload-extra", b"pay"])
    def test_a_refused_replace_only_accepts_matching_bytes(self, tmp_path, existing):
        from unittest import mock

        from kornia.io.sample import download_image

        dst = tmp_path / "panda.jpg"
        dst.write_bytes(existing)
        error = PermissionError(13, "Access is denied")
        with (
            mock.patch("kornia.io.sample.urlopen") as mock_urlopen,
            mock.patch("kornia.io.sample.os.replace", side_effect=error),
        ):
            mock_urlopen.return_value.__enter__.return_value.read.return_value = b"payload"
            if existing == b"payload":
                download_image(self.URL, str(dst))
            else:
                with pytest.raises(PermissionError) as exc:
                    download_image(self.URL, str(dst))
                assert exc.value is error
        assert dst.read_bytes() == existing
        assert list(tmp_path.iterdir()) == [dst]

    def test_a_refused_replace_with_an_unreadable_copy_preserves_the_replace_error(self, tmp_path):
        from unittest import mock

        from kornia.io.sample import download_image

        dst = tmp_path / "panda.jpg"
        dst.write_bytes(b"payload")
        error = PermissionError(13, "Replace refused")

        def refusing_read(path, mode="r", *args, **kwargs):
            if mode == "rb":
                raise PermissionError(13, "Read refused")
            return open(path, mode, *args, **kwargs)

        with (
            mock.patch("kornia.io.sample.urlopen") as mock_urlopen,
            mock.patch("kornia.io.sample.os.replace", side_effect=error),
            mock.patch("kornia.io.sample.open", refusing_read, create=True),
        ):
            mock_urlopen.return_value.__enter__.return_value.read.return_value = b"payload"
            with pytest.raises(PermissionError) as exc:
                download_image(self.URL, str(dst))
            assert exc.value is error
        assert dst.read_bytes() == b"payload"
        assert list(tmp_path.iterdir()) == [dst]

    def test_the_destination_appears_only_once_the_write_is_complete(self, tmp_path):
        from unittest import mock

        from kornia.io.sample import download_image

        dst = tmp_path / "panda.jpg"
        writes = []

        def watching_open(path, mode="r", *args, **kwargs):
            handle = open(path, mode, *args, **kwargs)  # noqa: SIM115 - returned to the code under test
            real_write = handle.write

            def write(data):
                writes.append((str(path), dst.exists()))  # a process killed here must not leave a partial dst
                return real_write(data)

            handle.write = write
            return handle

        payload = b"\xff\xd8" + bytes(100)
        with (
            mock.patch("kornia.io.sample.urlopen") as mock_urlopen,
            mock.patch("kornia.io.sample.open", watching_open, create=True),
        ):
            mock_urlopen.return_value.__enter__.return_value.read.return_value = payload
            download_image(self.URL, str(dst))
        assert len(writes) == 1
        written, dst_existed = writes[0]
        assert not dst_existed
        assert Path(written).parent == tmp_path  # a temporary file next to dst, so the final rename is atomic
        assert Path(written).name.startswith("panda.jpg.")
        assert written.endswith(".part")
        assert dst.read_bytes() == payload

    def test_an_interrupted_write_leaves_no_file(self, tmp_path):
        from unittest import mock

        from kornia.io.sample import download_image

        def failing_open(path, mode="r", *args, **kwargs):
            handle = open(path, mode, *args, **kwargs)  # noqa: SIM115 - returned to the code under test
            real_write = handle.write

            def write(data):
                real_write(data[:5])  # part of the body reaches the disk, then the device fills up
                raise OSError(28, "No space left on device")

            handle.write = write
            return handle

        dst = tmp_path / "panda.jpg"
        with (
            mock.patch("kornia.io.sample.urlopen") as mock_urlopen,
            mock.patch("kornia.io.sample.open", failing_open, create=True),
        ):
            mock_urlopen.return_value.__enter__.return_value.read.return_value = b"\xff\xd8" + bytes(100)
            with pytest.raises(OSError, match="No space left"):
                download_image(self.URL, str(dst))
        assert list(tmp_path.iterdir()) == []  # neither dst nor the temporary file

    def test_http_error_propagates(self, tmp_path):
        import urllib.error
        from unittest import mock

        from kornia.io.sample import download_image

        dst = tmp_path / "panda.png"
        with (
            mock.patch(
                "kornia.io.sample.urlopen",
                side_effect=urllib.error.HTTPError(self.URL, 404, "Not Found", {}, None),
            ),
            pytest.raises(urllib.error.HTTPError, match="404"),
        ):
            download_image(self.URL, str(dst))
        assert not dst.exists()


class TestKorniaRsImageIo:
    """``kornia.io`` calls ``kornia_rs.io``, where kornia_rs keeps its image readers and writers since 0.1.11.

    kornia_rs 0.1.11 moved every ``read_image_*``/``write_image_*`` out of the package root; kornia kept
    calling the root, so ``pip install kornia`` (which resolves the newest kornia_rs) lost JPEG loading and
    most writes until the floor moved to 0.1.14 and the calls to ``kornia_rs.io`` (kornia#4325).
    """

    @staticmethod
    def _used_function_names() -> set[str]:
        """Every ``_rs_io.<name>`` attribute in ``kornia/io/io.py``."""
        import ast
        import inspect

        import kornia.io.io as io_module

        return {
            node.attr
            for node in ast.walk(ast.parse(inspect.getsource(io_module)))
            if isinstance(node, ast.Attribute) and isinstance(node.value, ast.Name) and node.value.id == "_rs_io"
        }

    def test_used_function_names_are_extracted_from_the_source(self):
        assert {"read_image_jpegturbo", "read_image", "write_image_tiff_f32"} <= self._used_function_names()

    def test_installed_kornia_rs_provides_every_used_function(self):
        missing = sorted(n for n in self._used_function_names() if not callable(getattr(kornia_rs.io, n, None)))
        assert missing == [], f"kornia_rs {kornia_rs.__version__}: {missing}"

    @pytest.mark.parametrize("ext", ["jpg", "png", "tiff"])
    def test_uint8_round_trip_every_extension(self, tmp_path, ext):
        img = create_random_img8_torch(5, 6, 3)
        path = tmp_path / f"image.{ext}"
        write_image(path, img)
        loaded = load_image(path, ImageLoadType.UNCHANGED)
        assert loaded.shape == img.shape
        if ext != "jpg":  # lossless containers come back bit-exact
            assert torch.equal(loaded, img)

    def test_lookup_happens_at_call_time(self, tmp_path, monkeypatch):
        """Patching the kornia_rs function is seen by the next call."""
        calls = []
        real = kornia_rs.io.write_image_png_u8

        def spy(*args, **kwargs):
            calls.append(args[0])
            return real(*args, **kwargs)

        monkeypatch.setattr(kornia_rs.io, "write_image_png_u8", spy)
        write_image(tmp_path / "image.png", create_random_img8_torch(2, 3, 3))
        assert calls == [str(tmp_path / "image.png")]


class TestWiderThanUint8Decodes:
    """kornia_rs decodes 16-bit PNG/TIFF and float TIFF; the 8-bit load types are not defined for them."""

    @pytest.mark.parametrize(
        "ext,dtype",
        [("png", torch.uint16), ("tiff", torch.uint16), ("tiff", torch.float32)],
    )
    def test_unchanged_returns_the_decoded_dtype(self, tmp_path, ext, dtype):
        if dtype == torch.uint16:
            img = torch.randint(0, 65535, (3, 4, 5), dtype=torch.int32).to(torch.uint16)
        else:
            img = torch.rand(3, 4, 5)
        path = tmp_path / f"image.{ext}"
        write_image(path, img)
        loaded = load_image(path, ImageLoadType.UNCHANGED)
        assert loaded.dtype == dtype
        assert torch.equal(loaded, img)

    def test_unchanged_loads_a_16_bit_grayscale_png(self, tmp_path):
        img = torch.randint(0, 65535, (1, 4, 5), dtype=torch.int32).to(torch.uint16)
        path = tmp_path / "image.png"
        write_image(path, img)
        loaded = load_image(path, ImageLoadType.UNCHANGED)
        assert loaded.dtype == torch.uint16
        assert torch.equal(loaded, img)

    def test_unchanged_loads_a_16_bit_rgba_png(self, tmp_path):
        img_np = np.random.randint(0, 65535, (4, 5, 4)).astype(np.uint16)  # noqa: NPY002
        path = tmp_path / "image.png"
        kornia_rs.io.write_image_png_u16(str(path), img_np, mode="rgba")
        loaded = load_image(path, ImageLoadType.UNCHANGED)
        assert loaded.dtype == torch.uint16
        assert torch.equal(loaded, torch.from_numpy(img_np).permute(2, 0, 1))

    @pytest.mark.parametrize("mode", ["mono", "rgba"])
    def test_16_bit_png_goes_to_the_16_bit_reader(self, tmp_path, monkeypatch, mode):
        """kornia_rs's ``read_image`` also decodes these files, so the dtype alone cannot show which reader ran."""
        path = tmp_path / "image.png"
        write_random_png_u16(path, mode)
        calls = []
        real = kornia_rs.io.read_image_png_u16

        def spy(*args, **kwargs):
            calls.append(args[1])
            return real(*args, **kwargs)

        monkeypatch.setattr(kornia_rs.io, "read_image_png_u16", spy)
        assert load_image(path, ImageLoadType.UNCHANGED).dtype == torch.uint16
        assert calls == [mode]

    @pytest.mark.parametrize("mode", ["mono", "rgba"])
    @pytest.mark.parametrize("load_type", [t for t in ImageLoadType if t != ImageLoadType.UNCHANGED])
    def test_eight_bit_load_types_reject_a_16_bit_png(self, tmp_path, mode, load_type):
        path = tmp_path / "image.png"
        write_random_png_u16(path, mode)
        expected = rf"decoded to torch\.uint16, and ImageLoadType\.{load_type.name} .*ImageLoadType\.UNCHANGED"
        with pytest.raises(NotImplementedError, match=expected):
            load_image(path, load_type)

    @pytest.mark.parametrize("mode", ["mono", "rgba"])
    def test_default_load_type_rejects_a_16_bit_png(self, tmp_path, mode):
        path = tmp_path / "image.png"
        write_random_png_u16(path, mode)
        with pytest.raises(NotImplementedError, match=r"decoded to torch\.uint16, and ImageLoadType\.RGB32"):
            load_image(path)

    @pytest.mark.parametrize("load_type", [ImageLoadType.RGB8, ImageLoadType.GRAY8, ImageLoadType.RGB32])
    def test_eight_bit_load_types_reject_a_float_decode(self, tmp_path, load_type):
        path = tmp_path / "image.tiff"
        write_image(path, torch.rand(3, 4, 5))
        expected = rf"decoded to torch\.float32, and ImageLoadType\.{load_type.name}"
        with pytest.raises(NotImplementedError, match=expected):
            load_image(path, load_type)


class TestConventionsIo:
    """Pins for the channel, dtype, alpha, orientation and format policies of ``load_image`` and ``write_image``."""

    @staticmethod
    def _rgb() -> torch.Tensor:
        return (torch.arange(3 * 4 * 5) * 11 % 256).to(torch.uint8).view(3, 4, 5)  # H = 4, W = 5, asymmetric

    @pytest.mark.parametrize(
        ("load_type", "channels"),
        [
            (ImageLoadType.GRAY8, 1),
            (ImageLoadType.GRAY32, 1),
            (ImageLoadType.RGB8, 3),
            (ImageLoadType.RGB32, 3),
            (ImageLoadType.RGBA8, 4),
        ],
    )
    @pytest.mark.parametrize("file_channels", [1, 3])
    def test_convention_load_image_channels_follow_the_load_type(self, tmp_path, load_type, channels, file_channels):
        # The load type fixes the channel count whatever the file holds; only UNCHANGED keeps the file's own count.
        path = tmp_path / "image.png"
        write_image(path, self._rgb()[:file_channels])
        assert load_image(path, load_type).shape == (channels, 4, 5)

    @pytest.mark.parametrize("file_channels", [1, 3])
    def test_convention_load_image_unchanged_keeps_the_file_channels(self, tmp_path, file_channels):
        path = tmp_path / "image.png"
        write_image(path, self._rgb()[:file_channels])
        assert load_image(path, ImageLoadType.UNCHANGED).shape == (file_channels, 4, 5)

    def test_convention_load_image_default_is_rgb32_float_in_unit_range_on_cpu(self, tmp_path):
        pixels = self._rgb().clone()
        pixels[0, 0, 0], pixels[0, 0, 1] = 0, 255
        path = tmp_path / "image.png"
        write_image(path, pixels)
        out = load_image(path)
        assert out.dtype == torch.float32
        assert out.device.type == "cpu"
        assert out.shape == (3, 4, 5)
        assert out.min().item() == 0.0
        assert out.max().item() == 1.0
        torch.testing.assert_close(out, load_image(path, ImageLoadType.RGB32))
        torch.testing.assert_close(out, pixels.float() / 255.0)

    def test_convention_load_image_composites_alpha_over_white(self, tmp_path):
        # A transparent pixel loads as white, an opaque one keeps its colour, and a semi-transparent one is
        # composited over white and rounded; OpenCV and Pillow drop the alpha channel instead.
        # Snippet: [round(c * 64 / 255 + 255 * (1 - 64 / 255)) for c in (200, 100, 50)] -> [241, 216, 204]
        pixels = torch.zeros(4, 3, 5, dtype=torch.uint8)  # (C, H, W), H = 3, W = 5
        pixels[:] = torch.tensor([10, 20, 30, 255], dtype=torch.uint8)[:, None, None]
        pixels[:, 0, 0] = torch.tensor([200, 100, 50, 64], dtype=torch.uint8)
        pixels[:, 2, 4] = torch.tensor([7, 8, 9, 0], dtype=torch.uint8)
        path = tmp_path / "rgba.png"
        write_image(path, pixels)
        out = load_image(path, ImageLoadType.RGB8)
        assert out.shape == (3, 3, 5)
        assert out[:, 0, 0].tolist() == [241, 216, 204]
        assert out[:, 2, 4].tolist() == [255, 255, 255]
        assert out[:, 1, 2].tolist() == [10, 20, 30]

    def test_convention_load_image_ignores_exif_orientation(self, tmp_path):
        # The decoded array is the stored one, (C, H, W) = (3, 4, 8); cv2.imread honours orientation 6 and would give
        # (8, 4, 3) for this file. The APP1 block below is a TIFF header with one IFD entry: Orientation (0x0112) = 6.
        plain = tmp_path / "plain.jpg"
        write_image(plain, (torch.arange(3 * 4 * 8) * 5 % 256).to(torch.uint8).view(3, 4, 8))
        exif = (
            b"Exif\x00\x00MM\x00*\x00\x00\x00\x08"  # Exif marker, big-endian TIFF header, IFD at offset 8
            b"\x00\x01\x01\x12\x00\x03\x00\x00\x00\x01\x00\x06\x00\x00"  # 1 entry: tag 0x0112, SHORT, 1, value 6
            b"\x00\x00\x00\x00"  # no next IFD
        )
        data = plain.read_bytes()
        tagged = tmp_path / "tagged.jpg"
        tagged.write_bytes(data[:2] + b"\xff\xe1" + struct.pack(">H", len(exif) + 2) + exif + data[2:])
        out = load_image(tagged, ImageLoadType.RGB8)
        assert out.shape == (3, 4, 8)
        torch.testing.assert_close(out, load_image(plain, ImageLoadType.RGB8))

    def test_convention_write_image_formats_per_dtype(self, tmp_path):
        # uint8 -> jpg, png, tif; uint16 -> png, tif; float32 -> tif; everything else raises NotImplementedError.
        image = self._rgb()
        for ext in ("jpg", "png", "tif"):
            write_image(tmp_path / f"u8.{ext}", image)
            assert load_image(tmp_path / f"u8.{ext}", ImageLoadType.UNCHANGED).shape == (3, 4, 5)
        for ext in ("png", "tif"):
            write_image(tmp_path / f"u16.{ext}", image.to(torch.uint16) * 200)
            out = load_image(tmp_path / f"u16.{ext}", ImageLoadType.UNCHANGED)
            assert out.dtype == torch.uint16
            assert out.shape == (3, 4, 5)
        # a float32 TIFF is written without clamping: values in [-0.5, 1.5] come back unchanged
        wide = image.float() / 255 * 2 - 0.5
        assert wide.min() < 0
        assert wide.max() > 1
        write_image(tmp_path / "f32.tif", wide)
        out = load_image(tmp_path / "f32.tif", ImageLoadType.UNCHANGED)
        assert out.dtype == torch.float32
        assert out.shape == (3, 4, 5)
        torch.testing.assert_close(out, wide, rtol=0.0, atol=0.0)

        rejected = [(torch.uint16, "jpg"), (torch.float32, "png"), (torch.float32, "jpg")]
        rejected += [(torch.float64, ext) for ext in ("jpg", "png", "tif")]
        for dtype, ext in rejected:
            with pytest.raises(NotImplementedError, match=r"Unsupported (file extension|image dtype)"):
                write_image(tmp_path / f"bad.{ext}", image.to(dtype))

    def test_convention_write_image_jpeg_quality_default_is_80(self, tmp_path):
        image = (torch.arange(3 * 16 * 24) * 37 % 256).to(torch.uint8).view(3, 16, 24)  # H = 16, W = 24
        written = {}
        for name, kwargs in (("default", {}), ("q80", {"quality": 80}), ("q95", {"quality": 95})):
            write_image(tmp_path / f"{name}.jpg", image, **kwargs)
            written[name] = (tmp_path / f"{name}.jpg").read_bytes()
        assert written["default"] == written["q80"]
        assert written["default"] != written["q95"]

    @pytest.mark.parametrize(
        "shape",
        [
            (3, 0, 4),
            (3, 4, 0),
            (1, 0, 0),
            (0, 4),
            (4, 0),
        ],
    )
    def test_convention_write_image_zero_size_raises_5770(self, tmp_path, shape):
        # #5770: a zero height or width used to reach kornia-rs, which raised a bare Exception and left the
        # truncated file behind. It is now rejected before anything is created.
        for ext in ("png", "jpg", "tif"):
            path = tmp_path / f"zero.{ext}"
            with pytest.raises(ShapeError, match=re.escape(str(tuple(shape)))):
                write_image(path, torch.zeros(*shape, dtype=torch.uint8))
            assert not path.exists()

    @pytest.mark.parametrize("shape", [(3, 1, 4), (3, 4, 1), (1, 4)])
    def test_write_image_accepts_a_single_row_or_column_5770(self, tmp_path, shape):
        # Only a zero extent is rejected: a 1-pixel height or width still writes.
        path = tmp_path / "thin.png"
        write_image(path, torch.zeros(*shape, dtype=torch.uint8))
        assert path.stat().st_size > 0


@pytest.mark.parametrize("side, expected", [("long", (1, 3, 24, 40)), ("short", (1, 3, 40, 56))])
def test_sample_images_resize_side_with_divisible_factor(tmp_path, side, expected):
    from kornia.io import get_sample_images

    path = tmp_path / "non_square.png"
    write_image(path, torch.zeros(3, 22, 32, dtype=torch.uint8))
    with warnings.catch_warnings():
        warnings.filterwarnings("error", message=r".*side", category=DeprecationWarning)
        out = get_sample_images(40, paths=[str(path)], divisible_factor=8, as_list=False, side=side)
    assert out.shape == expected


@pytest.mark.parametrize("side", ["short", "long"])
def test_sample_images_divisible_only_warns_for_side(tmp_path, side):
    from kornia.io import get_sample_images

    path = tmp_path / "non_square.png"
    write_image(path, torch.zeros(3, 22, 32, dtype=torch.uint8))
    expected = get_sample_images(paths=[str(path)], divisible_factor=8)
    with pytest.warns(DeprecationWarning, match="side"):
        out = get_sample_images(paths=[str(path)], divisible_factor=8, side=side)
    assert len(out) == len(expected) == 1
    assert out[0].shape == expected[0].shape
    torch.testing.assert_close(out[0], expected[0], rtol=0, atol=0)