解码 / 编码图像和视频

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 或灰度张量。
encode_png(input[, compression_level])	接受 CHW 布局的输入张量，并返回包含其对应 PNG 文件内容的缓冲区。
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 通过下面列出的不同 API 支持视频解码，其中一些 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。