Kornia IO 图像张量加载与保存实战:基于 kornia-rs 与 DLPack 的零拷贝图像读写指南
Kornia IO 图像张量加载与保存实战:基于 kornia-rs 与 DLPack 的零拷贝图像读写指南
导读
本指南围绕 Kornia 的 kornia.io 包展开,讲解如何将图像文件直接加载为 PyTorch 张量、按 ImageLoadType 灵活控制通道数与数据类型、并通过 write_image 写回磁盘。kornia.io 底层由 Rust 编写的 kornia-rs 库提供解码能力,借助 DLPack 协议以极低的内存开销把解码结果交付给 PyTorch,在 Linux、macOS 与 Windows 上均可使用。读完本文,你将掌握 Kornia 中图像输入输出的完整调用链、每种加载类型的语义与适用场景,以及批量加载示例图集的实用技巧。
kornia.io:直接以张量形态读写图像
Kornia 的 IO 子模块将「读取图像文件」与「PyTorch 张量」直接打通,核心设计目标有两个:
- 一步到位:
load_image返回的即torch.Tensor,形状为(C, H, W),无需在 numpy / PIL 与张量之间手动搬运; - 低内存开销:图像解码由
kornia-rs(用 Rust 编写的低级计算机视觉库,作为 Kornia 的依赖自动安装,Linux、macOS、Windows 均有预编译 wheel)完成,解码结果通过 DLPack 协议交给 PyTorch,避免额外的数据拷贝,保持极小的内存占用。
kornia.io 对外暴露的公共 API 非常精简,集中在 kornia/io/init.py:
from .io import ImageLoadType, load_image, write_image
from .sample import get_sample_images
__all__ = ["ImageLoadType", "get_sample_images", "load_image", "write_image"]
在 Kornia 顶层,io 模块被作为便捷导入挂载(见 kornia/init.py),因此实践中通常直接写 kornia.io.load_image 或 K.io.load_image。
快速上手:五种加载类型一次看懂
load_image 的完整签名(定义于 kornia/io/io.py):
def load_image(
path_file: str | Path,
desired_type: ImageLoadType = ImageLoadType.RGB32,
device: Union[str, torch.device, None] = "cpu",
) -> torch.Tensor
path_file:有效的图像文件路径(字符串或pathlib.Path);desired_type:期望的图像类型,由「色彩空间 + 数据类型」共同决定;device:张量放置的设备,支持"cpu"、"cuda"或torch.device,默认"cpu"。
官方文档(docs/source/io.rst)给出的最小示例:
import torch
import kornia as K
from kornia.io import ImageLoadType
file_path = "image.jpg"
img = K.io.load_image(file_path, ImageLoadType.UNCHANGED, device="cuda")
# (C, H, W) 保留文件原始 dtype 与通道数,位于 "cuda"
img = K.io.load_image(file_path, ImageLoadType.RGB8, device="cpu")
# (3, H, W) torch.uint8,取值范围 [0, 255],位于 "cpu"
img = K.io.load_image(file_path, ImageLoadType.GRAY8, device="cuda")
# (1, H, W) torch.uint8,取值范围 [0, 255],位于 "cuda"
img = K.io.load_image(file_path, ImageLoadType.GRAY32, device="cpu")
# (1, H, W) torch.float32,取值范围 [0, 1],位于 "cpu"
img = K.io.load_image(file_path, ImageLoadType.RGB32, device="cuda")
# (3, H, W) torch.float32,取值范围 [0, 1],位于 "cuda"
K.io.write_image("copy.jpg", (img * 255).to(torch.uint8).cpu()) # 期望 (3, H, W) uint8
ImageLoadType 枚举全解析
ImageLoadType 是一个 Enum(定义于 kornia/io/io.py),共 6 个成员:
| 枚举值 | 数值 | 输出通道数 | 输出 dtype | 取值范围 | 典型用途 |
|---|---|---|---|---|---|
UNCHANGED |
0 | 由解码器决定 | 由文件决定 | 原样 | 无损还原、调试、处理 16 位 PNG/TIFF |
GRAY8 |
1 | 1 | torch.uint8 |
[0, 255] | 灰度分析、传统 CV 前处理 |
RGB8 |
2 | 3 | torch.uint8 |
[0, 255] | 与 PIL / OpenCV 结果互操作 |
RGBA8 |
3 | 4 | torch.uint8 |
[0, 255] | 需要透明通道 |
GRAY32 |
4 | 1 | torch.float32 |
[0, 1] | 灰度深度学习输入 |
RGB32 |
5 | 3 | torch.float32 |
[0, 1] | 深度学习默认推荐 |
小提示:绝大多数 Kornia 算子期望输入为带 batch 维的
(B, C, H, W)float 张量且取值在[0, 1];因此官方建议用ImageLoadType.RGB32加载,再通过img[None]补上 batch 维(见 docs/source/io.rst 中的 tip 框)。
底层原理:从文件到张量的完整调用链
load_image 内部实际经历了「格式感知解码 → HWC numpy → CHW 张量 → 类型转换 → 设备迁移」五个环节(kornia/io/io.py)。
按扩展名分派的解码路径
if path_file.suffix.lower() in [".jpg", ".jpeg"]:
img = _rs_io.read_image_jpegturbo(str(path_file))
elif path_file.suffix.lower() == ".png":
color_type = _read_png_color_type(path_file)
mode = _PNG_COLOR_TYPE_TO_MODE.get(color_type)
if mode is None or mode == "rgb":
img = _rs_io.read_image(str(path_file))
else:
img = _rs_io.read_image_png_u8(str(path_file), mode)
else:
img = _rs_io.read_image(str(path_file))
- JPEG:走
kornia_rs.io.read_image_jpegturbo,使用 libjpeg-turbo 高速解码; - PNG:Kornia 会先读取 PNG 文件头的 color type 字节(见
_read_png_color_type),再决定解码模式——灰度(type 0)与索引色(type 3)按单通道"mono"解码,RGBA(type 6)按"rgba"解码,RGB 与其他未知类型回退到通用read_image(映射表见 kornia/io/io.py); - 其他格式(如 TIFF):走通用
kornia_rs.io.read_image。
解码结果先以 HxWxC 的 numpy 数组形式返回,再经 image_to_tensor(img, keepdim=True) 转成 (C, H, W) 张量,最后通过 torch.device(device) 迁移到目标设备。值得一提的是,kornia_rs 自 0.1.11 起把所有 read_image_* / write_image_* 函数迁移到 kornia_rs.io 命名空间下,Kornia 在 kornia#4325 中同步跟进(测试类注释对此有完整说明,见 tests/io/test_io_image.py)。
8 位与高位深图像的边界
UNCHANGED 直接返回解码器产出的原始张量,因此 16 位 PNG/TIFF 会以 torch.uint16 返回,float TIFF 会以 torch.float32 返回。而其余所有加载类型都是为 8 位输入定义的,若解码结果不是 uint8,_convert_image_type 会抛出 NotImplementedError,并提示「改用 ImageLoadType.UNCHANGED 自行转换」(kornia/io/io.py)。这一点在测试中有明确的针对验证(tests/io/test_io_image.py):UNCHANGED 能无损还原 uint16/float32 TIFF,而 RGB8、GRAY8、RGB32 遇到 float 解码会直接报错。
类型转换:通道与数据类型的自动适配
_convert_image_type(kornia/io/io.py)负责把解码得到的 (C, H, W) uint8 张量换算为目标类型。核心逻辑包括:
- RGBA → RGB 归一化:当源图有 4 个通道而目标类型不是
RGBA8时,会先经rgba_to_rgb去掉透明通道; - 模式匹配表:
(目标类型, 源通道数)组合逐一匹配,例如(GRAY8, 3)表示三通道输入转灰度,(RGB8, 1)表示单通道输入复制成三通道,(GRAY32, 3)表示三通道先转灰度再归一化到[0, 1]等; - 颜色转换全部复用
kornia.color模块:如rgb_to_grayscale、grayscale_to_rgb、rgb_to_rgba、rgba_to_rgb(分别定义于 kornia/color/gray.py 与 kornia/color/rgb.py); - 8 位与浮点互转:
_to_uint8执行image.mul(255.0).byte(),_to_float32执行image.float() / 255.0,并各自用KORNIA_CHECK校验输入 dtype。
也就是说,无论源文件是灰度图还是 RGBA 图,只要指定了目标 ImageLoadType,输出张量的通道数与 dtype 都是确定且可预期的——这与测试 test_load_image / test_load_rgba_png 的参数化断言一致(tests/io/test_io_image.py)。
write_image:支持的格式、dtype 与 JPEG 质量
write_image 的完整签名(kornia/io/io.py):
def write_image(path_file: str | Path, image: torch.Tensor, quality: int = 80) -> None
path_file:输出路径,仅支持.jpg、.jpeg、.png、.tiff四种扩展名,其余扩展名直接抛NotImplementedError;image:形状为(3, H, W)、(1, H, W)或(H, W)的张量;quality:JPEG 编码质量(0–100),仅对 JPEG 生效,PNG/TIFF 无损容器会忽略该参数,默认 80。
写入时按 dtype 分派:
| 输入 dtype | 可用格式 | 底层调用 |
|---|---|---|
torch.uint8 |
.jpg / .jpeg / .png / .tiff |
write_image_jpeg(带 quality)、write_image_png_u8、write_image_tiff_u8 |
torch.uint16 |
.png / .tiff |
write_image_png_u16、write_image_tiff_u16 |
torch.float32 |
.tiff |
write_image_tiff_f32 |
写入前 write_image 会做两项校验:扩展名合法性(KORNIA_CHECK)与张量维度(至少 2D),随后通过 tensor_to_image(image, keepdim=True, force_contiguous=True) 转回 HxWxC 的连续 numpy 数组,二维输入会自动补上通道维。
测试中的回环验证(tests/io/test_io_image.py)表明:无损容器(PNG/TIFF)写入再以 UNCHANGED 读回是逐位一致的(torch.equal(loaded, img) 为真),JPEG 因有损压缩不保证逐位一致。
注意:
write_image期望的输入是(3, H, W)的 uint8 张量;若你手头是[0, 1]的 float 张量,请先乘 255 再转 uint8(如文档示例所示),或直接以 float32 写入.tiff。
get_sample_images:一键批量加载示例图集
get_sample_images(kornia/io/sample.py)是从 kornia.utils.sample 迁移并恢复的公共 API,用于从预设 URL 批量加载示例图像,适合快速测试与演示:
def get_sample_images(
resize: Optional[Tuple[int, int]] = None,
paths: List[str] = _IMAGE_URLS,
download: bool = True,
cache_dir: Optional[str] = None,
as_list: Optional[bool] = None,
divisible_factor: Optional[int] = None,
**kwargs: Any,
) -> Union[torch.Tensor, List[torch.Tensor]]
关键参数行为:
paths:图像来源列表,默认是 6 张公开示例图(panda.jpg、simba.png、girona.png、baby_giraffe.png、persistencia_memoria.jpg、delorean.png,见 kornia/io/sample.py)。以http开头的项会先下载后加载,本地路径则直接读取;download/cache_dir:下载开关与缓存目录,默认缓存到.kornia_hub/images;已缓存的文件不会重复下载,download=False且文件不存在时会输出 error 日志并继续(底层由download_image借助urlopen拉取,超时 30 秒,见 kornia/io/sample.py);resize:(height, width)目标尺寸,通过kornia.geometry.resize缩放;divisible_factor则调用resize_to_be_divisible缩放到指定因子的整数倍;- 返回形态:提供了
resize且未显式设置as_list时,返回torch.stack后的单个(B, C, H, W)批量张量;否则返回列表,每项为原始形状(C, H, W)的张量。
import kornia as K
# 返回批量张量 (B, 3, H, W),统一缩放到 512x512
batch = K.io.get_sample_images(resize=(512, 512))
# 返回列表,每项保留原始尺寸
imgs = K.io.get_sample_images()
工程实践建议
- 深度学习管线首选
RGB32+img[None]:Kornia 绝大多数算子期望(B, C, H, W)的[0, 1]float 输入,这样加载即可直接进入增强/几何流程; - 需要与 PIL/OpenCV 结果对齐时选 8 位类型:
RGB8/GRAY8输出uint8,便于对比、可视化或与既有传统 CV 代码衔接; - 处理高位深医学/科学图像必须用
UNCHANGED:16 位 PNG/TIFF 与 float TIFF 只有该模式能保留原始 dtype 与数值精度,其余加载类型会明确报错而非静默截断; - 利用
device参数直接落在 GPU:load_image(path, ImageLoadType.RGB32, device="cuda")把设备迁移内聚在一次调用中,无需额外.to(),且 DLPack 零拷贝协议保证了整体内存开销最小; - 写回时注意格式 × dtype 矩阵:8 位图四格式皆可,16 位图仅 PNG/TIFF,float 图仅 TIFF;JPEG 请通过
quality控制体积与画质平衡。
至此,你已经掌握了 Kornia 图像 IO 的完整拼图——从 ImageLoadType 六种加载语义、PNG 按 color type 分派的解码细节、8 位与高位深的边界行为,到 write_image 的格式约束与 get_sample_images 的批量加载技巧,足以在真实项目中直接落地使用。