图像和视频的解码/编码¶

torchvision.io 模块提供了用于图像和视频解码和编码的工具。

图像解码¶

Torchvision 目前支持解码 JPEG、PNG、WEBP、GIF、AVIF 和 HEIC 图像。JPEG 解码也可以在 CUDA GPU 上完成。

主要入口点是 decode_image() 函数，你可以将其用作 PIL.Image.open() 的替代方案。它将图像直接解码为图像张量，从而节省了转换步骤，并允许你在张量上原生运行转换/预处理。

from torchvision.io import decode_image

img = decode_image("path_to_image", mode="RGB")
img.dtype  # torch.uint8

# Or
raw_encoded_bytes = ...  # read encoded bytes from your file system
img = decode_image(raw_encoded_bytes, mode="RGB")

decode_image() 将自动检测图像格式，并调用相应的解码器（HEIC 和 AVIF 图像除外，详情见 decode_avif() 和 decode_heic()）。你也可以使用更底层的特定格式解码器，它们功能更强大，例如，如果你想在 CUDA 上进行 JPEG 编码/解码。

`decode_image`(input[, mode, ...])	从路径或原始编码字节中将图像解码为 uint8 张量。
`decode_jpeg`(input[, mode, device, ...])	在 CPU 或 CUDA 上将 JPEG 图像解码为 3D RGB 或灰度张量。
`decode_png`(input[, mode, apply_exif_orientation])	将 PNG 图像解码为 3 维 RGB 或灰度张量。
`decode_webp`(input[, mode])	将 WEBP 图像解码为 3 维 RGB[A] 张量。
`decode_avif`(input[, mode])	将 AVIF 图像解码为 3 维 RGB[A] 张量。
`decode_heic`(input[, mode])	将 HEIC 图像解码为 3 维 RGB[A] 张量。
`decode_gif`(input)	将 GIF 图像解码为 3 或 4 维 RGB 张量。

ImageReadMode(value)

解码时允许自动转换为 RGB、RGBA 等格式。

已废弃的解码函数

read_image(path[, mode, apply_exif_orientation])

[已废弃] 请改用 decode_image()。

图像编码¶

对于编码，支持 JPEG (CPU 和 CUDA) 和 PNG。

`encode_jpeg`(input[, quality])	在 CPU 或 CUDA 上将 RGB 张量编码为原始编码的 JPEG 字节。
`write_jpeg`(input, filename[, quality])	接收 CHW 布局的输入张量，并将其保存到 JPEG 文件中。
`encode_png`(input[, compression_level])	接收 CHW 布局的输入张量，并返回一个包含其相应 PNG 文件内容的缓冲区。
`write_png`(input, filename[, compression_level])	接收 CHW 布局（灰度图像为 HW 布局）的输入张量，并将其保存到 PNG 文件中。

IO 操作¶

`read_file`(path)	将文件的字节内容作为 uint8 1D 张量返回。
`write_file`(filename, data)	将 uint8 1D 张量的内容写入文件。

视频 - 已废弃¶

警告

已废弃：Torchvision 中所有的视频解码和编码功能从 0.22 版本起已废弃，并将在 0.24 版本中移除。我们建议你迁移到 TorchCodec，PyTorch 未来的解码/编码功能将整合到那里。

`read_video`(filename[, start_pts, end_pts, ...])	[已废弃] 从文件中读取视频，返回视频帧和音频帧
`read_video_timestamps`(filename[, pts_unit])	[已废弃] 列出视频帧的时间戳。
`write_video`(filename, video_array, fps[, ...])	[已废弃] 将 [T, H, W, C] 格式的 4 维张量写入视频文件。

细粒度视频 API

除了 read_video 函数之外，我们还提供了高性能的底层 API，与 read_video 函数相比，它提供了更细粒度的控制。它同时完全支持 torchscript。

VideoReader(src[, stream, num_threads])

[已废弃] 细粒度视频读取 API。