Kornia IO 图像张量加载与保存实战:基于 kornia-rs 与 DLPack 的零拷贝图像读写指南

原创2026-09-23 17:02:501,934 阅读
文章标签:计算机视觉图像处理人工智能深度学习机器学习图形学科学计算

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 张量」直接打通,核心设计目标有两个:

  1. 一步到位:load_image 返回的即 torch.Tensor,形状为 (C, H, W),无需在 numpy / PIL 与张量之间手动搬运;
  2. 低内存开销:图像解码由 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 张量换算为目标类型。核心逻辑包括:

  1. RGBA → RGB 归一化:当源图有 4 个通道而目标类型不是 RGBA8 时,会先经 rgba_to_rgb 去掉透明通道;
  2. 模式匹配表:(目标类型, 源通道数) 组合逐一匹配,例如 (GRAY8, 3) 表示三通道输入转灰度,(RGB8, 1) 表示单通道输入复制成三通道,(GRAY32, 3) 表示三通道先转灰度再归一化到 [0, 1] 等;
  3. 颜色转换全部复用 kornia.color 模块:如 rgb_to_grayscale、grayscale_to_rgb、rgb_to_rgba、rgba_to_rgb(分别定义于 kornia/color/gray.py 与 kornia/color/rgb.py);
  4. 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()

工程实践建议

  1. 深度学习管线首选 RGB32 + img[None]:Kornia 绝大多数算子期望 (B, C, H, W) 的 [0, 1] float 输入,这样加载即可直接进入增强/几何流程;
  2. 需要与 PIL/OpenCV 结果对齐时选 8 位类型:RGB8 / GRAY8 输出 uint8,便于对比、可视化或与既有传统 CV 代码衔接;
  3. 处理高位深医学/科学图像必须用 UNCHANGED:16 位 PNG/TIFF 与 float TIFF 只有该模式能保留原始 dtype 与数值精度,其余加载类型会明确报错而非静默截断;
  4. 利用 device 参数直接落在 GPU:load_image(path, ImageLoadType.RGB32, device="cuda") 把设备迁移内聚在一次调用中,无需额外 .to(),且 DLPack 零拷贝协议保证了整体内存开销最小;
  5. 写回时注意格式 × dtype 矩阵:8 位图四格式皆可,16 位图仅 PNG/TIFF,float 图仅 TIFF;JPEG 请通过 quality 控制体积与画质平衡。

至此,你已经掌握了 Kornia 图像 IO 的完整拼图——从 ImageLoadType 六种加载语义、PNG 按 color type 分派的解码细节、8 位与高位深的边界行为,到 write_image 的格式约束与 get_sample_images 的批量加载技巧,足以在真实项目中直接落地使用。

登录后查看全文
kornia