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

计算机视觉人工智能深度学习图像处理【免费下载链接】kornia Geometric Computer Vision Library for Spatial AI项目地址https://gitcode.com/gh_mirrors/ko/kornia点击查看免费下载导读本指南围绕 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.pyfrom .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.pydef load_image( path_file: str | Path, desired_type: ImageLoadType ImageLoadType.RGB32, device: Union[str, torch.device, None] cpu, ) - torch.Tensorpath_file有效的图像文件路径字符串或pathlib.Pathdesired_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, devicecuda) # (C, H, W) 保留文件原始 dtype 与通道数位于 cuda img K.io.load_image(file_path, ImageLoadType.RGB8, devicecpu) # (3, H, W) torch.uint8取值范围 [0, 255]位于 cpu img K.io.load_image(file_path, ImageLoadType.GRAY8, devicecuda) # (1, H, W) torch.uint8取值范围 [0, 255]位于 cuda img K.io.load_image(file_path, ImageLoadType.GRAY32, devicecpu) # (1, H, W) torch.float32取值范围 [0, 1]位于 cpu img K.io.load_image(file_path, ImageLoadType.RGB32, devicecuda) # (3, H, W) torch.float32取值范围 [0, 1]位于 cuda K.io.write_image(copy.jpg, (img * 255).to(torch.uint8).cpu()) # 期望 (3, H, W) uint8ImageLoadType 枚举全解析ImageLoadType是一个Enum定义于 kornia/io/io.py共 6 个成员枚举值数值输出通道数输出 dtype取值范围典型用途UNCHANGED0由解码器决定由文件决定原样无损还原、调试、处理 16 位 PNG/TIFFGRAY811torch.uint8[0, 255]灰度分析、传统 CV 前处理RGB823torch.uint8[0, 255]与 PIL / OpenCV 结果互操作RGBA834torch.uint8[0, 255]需要透明通道GRAY3241torch.float32[0, 1]灰度深度学习输入RGB3253torch.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 高速解码PNGKornia 会先读取 PNG 文件头的 color type 字节见_read_png_color_type再决定解码模式——灰度type 0与索引色type 3按单通道mono解码RGBAtype 6按rgba解码RGB 与其他未知类型回退到通用read_image映射表见 kornia/io/io.py其他格式如 TIFF走通用kornia_rs.io.read_image。解码结果先以HxWxC的 numpy 数组形式返回再经image_to_tensor(img, keepdimTrue)转成(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.pyUNCHANGED能无损还原uint16/float32TIFF而RGB8、GRAY8、RGB32遇到 float 解码会直接报错。类型转换通道与数据类型的自动适配_convert_image_typekornia/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.py8 位与浮点互转_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.pydef write_image(path_file: str | Path, image: torch.Tensor, quality: int 80) - Nonepath_file输出路径仅支持.jpg、.jpeg、.png、.tiff四种扩展名其余扩展名直接抛NotImplementedErrorimage形状为(3, H, W)、(1, H, W)或(H, W)的张量qualityJPEG 编码质量0–100仅对 JPEG 生效PNG/TIFF 无损容器会忽略该参数默认 80。写入时按 dtype 分派输入 dtype可用格式底层调用torch.uint8.jpg/.jpeg/.png/.tiffwrite_image_jpeg带 quality、write_image_png_u8、write_image_tiff_u8torch.uint16.png/.tiffwrite_image_png_u16、write_image_tiff_u16torch.float32.tiffwrite_image_tiff_f32写入前write_image会做两项校验扩展名合法性KORNIA_CHECK与张量维度至少 2D随后通过tensor_to_image(image, keepdimTrue, force_contiguousTrue)转回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_imageskornia/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已缓存的文件不会重复下载downloadFalse且文件不存在时会输出 error 日志并继续底层由download_image借助urlopen拉取超时 30 秒见 kornia/io/sample.pyresize(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()工程实践建议深度学习管线首选RGB32img[None]Kornia 绝大多数算子期望(B, C, H, W)的[0, 1]float 输入这样加载即可直接进入增强/几何流程需要与 PIL/OpenCV 结果对齐时选 8 位类型RGB8/GRAY8输出uint8便于对比、可视化或与既有传统 CV 代码衔接处理高位深医学/科学图像必须用UNCHANGED16 位 PNG/TIFF 与 float TIFF 只有该模式能保留原始 dtype 与数值精度其余加载类型会明确报错而非静默截断利用device参数直接落在 GPUload_image(path, ImageLoadType.RGB32, devicecuda)把设备迁移内聚在一次调用中无需额外.to()且 DLPack 零拷贝协议保证了整体内存开销最小写回时注意格式 × dtype 矩阵8 位图四格式皆可16 位图仅 PNG/TIFFfloat 图仅 TIFFJPEG 请通过quality控制体积与画质平衡。至此你已经掌握了 Kornia 图像 IO 的完整拼图——从ImageLoadType六种加载语义、PNG 按 color type 分派的解码细节、8 位与高位深的边界行为到write_image的格式约束与get_sample_images的批量加载技巧足以在真实项目中直接落地使用。赞分享计算机视觉人工智能深度学习图像处理【免费下载链接】kornia Geometric Computer Vision Library for Spatial AI项目地址https://gitcode.com/gh_mirrors/ko/kornia点击查看免费下载相关推荐Kornia 图像 IO 修复实录对齐 kornia_rs 0.1.14 模块结构解锁 16-bit 与浮点图像读写Kornia 图像 IO 修复实录对齐 kornia_rs 0.1.14 模块结构解锁 16 bit 与浮点图像读写 本文聚焦 Kornia 仓库中 cha计算机视觉深度学习人工智能图像处理JAX 与 DLPack跨框架零拷贝张量互操作的协议实现与实战指南JAX 与 DLPack跨框架零拷贝张量互操作的协议实现与实战指南 本文围绕 docs/jax.dlpack.rst https://link.gitcode人工智能机器学习深度学习编译器高性能计算如何把 detectron2/projects 下的扩展项目如 PointRend接入自己的训练脚本如何把 detectron2/projects 下的扩展项目如 PointRend接入自己的训练脚本 detectron2 的 projects/ 目录存放计算机视觉人工智能深度学习图像处理上一篇Gatsby Provision 约定详解:为站点内容自动预置数据源的标准化方案下一篇终极自定义播放器引擎从PlayerFactory到AbstractPlayer扩展的完整指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考