解码 / 编码图像和视频¶

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

图像解码¶

Torchvision 目前支持解码 JPEG、PNG、WEBP 和 GIF 图像。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() 会自动检测图像格式，并调用相应的解码器。你也可以使用更低级别的特定格式解码器，这些解码器可能更强大，例如，如果你想在CUDA上编码/解码JPEG。

`decode_image`(input[, mode, ...])	将图像解码为uint8张量，从路径或原始编码字节中。
`decode_jpeg`(input[, mode, device, ...])	将JPEG图像解码为3D RGB或灰度张量，可在CPU或CUDA上运行。
`encode_png`(input[, compression_level])	接收一个CHW布局的输入张量，并返回一个包含其对应PNG文件内容的缓冲区。
`decode_gif`(input)	将GIF图像解码为3维或4维的RGB张量。
`decode_webp`(input[, mode])	将WEBP图像解码为三维RGB[A]张量。

ImageReadMode(value)

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

过时的解码函数：

read_image(path[, mode, apply_exif_orientation])

[已过时] 请改用 decode_image()。

图像编码¶

对于编码，支持JPEG（CPU和CUDA）和PNG。

`encode_jpeg`(input[, quality])	将RGB张量编码为原始编码的jpeg字节，可在CPU或CUDA上运行。
`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 一维张量。
`write_file`(filename, data)	将一个uint8类型的一维张量的内容写入文件。

视频¶

警告

Torchvision 支持通过以下列出的不同 API 进行视频解码，其中一些仍处于 BETA 阶段。在不久的将来，我们计划将 PyTorch 的视频解码功能集中到 torchcodec 项目中。我们鼓励您尝试并提供反馈，因为 torchvision 的视频解码器最终将被弃用。

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

细粒度视频API

除了read_video函数外，我们还提供了一个高性能的低级API，与read_video函数相比，它提供了更细粒度的控制。它在完全支持torchscript的同时完成了所有这些功能。

VideoReader(src[, stream, num_threads])

细粒度的视频读取API。