π Geometric Computer Vision Library for Spatial AI
Python artificial-intelligencecomputer-visiondeep-learninghacktoberfestimage-processingmachine-learningneural-networkpythonpytorchroboticsspatial-ai
# 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)