torchvision.io

该 torchvision.io 包提供了执行IO操作的函数。它们目前专门用于读取和写入视频和图像。

视频

torchvision.io.read_video(filename: str, start_pts: int = 0, end_pts: Union[float, NoneType] = None, pts_unit: str = 'pts') → Tuple[torch.Tensor, torch.Tensor, Dict[str, Any]]

从文件中读取视频，返回视频帧和音频帧。

Parameters:

• 文件名 (str) – 视频文件路径
• 起始时间点 (整数，当时间单位为 'pts' 时，可选) – 浮点数/分数，当时间单位为 ‘秒’ 时，可选 视频的起始显示时间
• 结束时间点 (整数，如果时间单位为 'pts'，可选) – 浮点数/分数，如果时间单位为 ‘秒’，可选 结束呈现时间
• pts_unit (str, 可选) – start_pts 和 end_pts 值将被解释的单位，可以是 ‘pts’ 或 ‘sec’。默认为 ‘pts’。

Returns:

• vframes (张量[T, H, W, C]) – the T 视频帧
• 音频帧 (Tensor[K, L]) – 音频帧，其中K是通道数，L是 点的数量
• 信息 (字典) – 视频和音频的元数据。可以包含字段视频帧率（浮点数） 和音频帧率（整数）

torchvision.io.read_video_timestamps(filename: str, pts_unit: str = 'pts') → Tuple[List[int], Union[float, NoneType]]

列出视频帧的时间戳。

注意，该函数会逐帧解码整个视频。

Parameters:

• 文件名 (str) – 视频文件路径
• pts_unit (str, optional) – 返回时间戳值的单位，可以是‘pts’或‘sec’。默认为‘pts’。

Returns:

• pts (如果 pts_unit = ‘pts’，则为 List[int]；如果 pts_unit = ‘sec’，则为 List[Fraction]) – 视频中每一帧的显示时间戳。
• 视频帧率 (浮点数，可选) – 视频的帧率

torchvision.io.write_video(filename: str, video_array: torch.Tensor, fps: float, video_codec: str = 'libx264', options: Union[Dict[str, Any], NoneType] = None) → None

以[T, H, W, C]格式写入4D张量到视频文件中

Parameters:

• filename (str) – 视频将被保存的路径
• video_array (张量[T, H, W, C]) – 包含单个帧的张量，格式为[T, H, W, C]的uint8张量
• fps (数字) – 每秒帧数

细粒度视频API

除了read_video函数之外，我们还提供了一个高性能的低级API，与read_video函数相比，它提供了更精细的控制。它在完全支持torchscript的同时实现了这一切。

class torchvision.io.VideoReader(path, stream='video')

细粒度视频读取 API。 支持从单个视频容器中逐帧读取各种流。

示例

以下示例创建了一个VideoReader对象，定位到2秒处，并返回单个帧：

import torchvision
video_path = "path_to_a_test_video"

reader = torchvision.io.VideoReader(video_path, "video")
reader.seek(2.0)
frame = next(reader)

VideoReader 实现了可迭代 API，这使得它适合与 itertools 结合使用，以实现更高级的读取功能。 因此，我们可以在 for 循环中使用 VideoReader 实例：

reader.seek(2)
for frame in reader:
    frames.append(frame['data'])
# additionally, `seek` implements a fluent API, so we can do
for frame in reader.seek(2):
    frames.append(frame['data'])

使用itertools，我们可以通过以下代码读取2到5秒之间的所有帧：

for frame in itertools.takewhile(lambda x: x['pts'] <= 5, reader.seek(2)):
    frames.append(frame['data'])

类似地，读取 2 秒时间戳之后的 10 帧可以按照如下方式实现：

for frame in itertools.islice(reader.seek(2), 10):
    frames.append(frame['data'])

注意

每个流描述符由两部分组成：流类型（例如‘视频’）和 一个唯一的流标识符（由视频编码确定）。 通过这种方式，如果视频容器包含多个相同类型的流， 用户可以访问他们想要的那个。 如果仅传递流类型，解码器会自动检测该类型的第一个流。

Parameters:

• 路径 (字符串) – 支持格式的视频文件路径
• 流 (字符串， 可选) – 所需流的描述符，后跟流id， 格式为{stream_type}:{stream_id}。默认值为"video:0"。 当前可用选项包括['video', 'audio']

__next__()

解码并返回当前流的下一个帧

Returns:一个包含字段 data 和 pts 的字典， 包含解码后的帧和对应的时间戳。 返回类型：(字典)

get_metadata()

返回视频元数据

Returns:包含每个流的时长和帧率的字典 返回类型：(字典)

seek(time_s: float)

在当前流中查找。

Parameters:time_s (float) – 秒数中的查找时间

注意

当前实现称为精确查找。这意味着在查找之后，调用next()将返回具有确切时间戳的帧（如果存在），或者返回时间戳大于time_s的第一个帧。

set_current_stream(stream: str)

设置当前流。 明确定义我们正在操作的流。

Parameters:流 (字符串) - 所需流的描述符。默认为"video:0"。 当前可用的流类型包括['video', 'audio']。 每个描述符由两部分组成：流类型（例如‘视频’）和 一个唯一的流标识符（由视频编码确定）。 通过这种方式，如果视频容器中包含多个相同类型的流， 用户可以访问他们想要的那个。 如果只传递了流类型，解码器会自动检测该类型的第一个流并返回它。 Returns:成功时为真，否则为假。 返回类型：(布尔值)

查看视频示例：

import torchvision
video_path = "path to a test video"
# Constructor allocates memory and a threaded decoder
# instance per video. At the momet it takes two arguments:
# path to the video file, and a wanted stream.
reader = torchvision.io.VideoReader(video_path, "video")

# The information about the video can be retrieved using the
# `get_metadata()` method. It returns a dictionary for every stream, with
# duration and other relevant metadata (often frame rate)
reader_md = reader.get_metadata()

# metadata is structured as a dict of dicts with following structure
# {"stream_type": {"attribute": [attribute per stream]}}
#
# following would print out the list of frame rates for every present video stream
print(reader_md["video"]["fps"])

# we explicitly select the stream we would like to operate on. In
# the constructor we select a default video stream, but
# in practice, we can set whichever stream we would like
video.set_current_stream("video:0")

图像

torchvision.io.read_image(path: str) → torch.Tensor

读取一张 JPEG 或 PNG 图像并将其转换为三维的 RGB 张量。 输出张量的值为介于 0 和 255 之间的 uint8 类型。

Parameters:path (字符串) – JPEG 或 PNG 图像的路径。 Returns:输出 返回类型：张量[3, image_height, image_width]

torchvision.io.decode_image(input: torch.Tensor) → torch.Tensor

检测图像是否为 JPEG 或 PNG，并执行适当的操作以将其解码为三维 RGB 张量。

输出张量的值为 0 到 255 之间的无符号 8 位整数。

Parameters:输入 (张量) – 包含PNG或JPEG图像原始字节的一维uint8张量。 Returns:输出 返回类型：张量[3, image_height, image_width]

torchvision.io.encode_jpeg(input: torch.Tensor, quality: int = 75) → torch.Tensor

接受一个布局为 CHW 的输入张量，并返回其对应 JPEG 文件的内容缓冲区。

Parameters:

• input (Tensor[channels, image_height, image_width])) – int8 图像张量，包含 c 个通道，其中 c 必须为 1 或 3。
• 质量 (int) – 输出JPEG文件的质量，必须是一个1到100之间的数字。默认值：75

Returns:

输出 – 一个一维的int8张量，包含JPEG文件的原始字节。

返回类型：

Tensor[1]

torchvision.io.write_jpeg(input: torch.Tensor, filename: str, quality: int = 75)

将布局为 CHW 的输入张量保存为 JPEG 文件。

Parameters:

• 输入 (张量[通道数, 图像高度, 图像宽度]) – int8 图像张量，包含 c 个通道，其中 c 必须为 1 或 3。
• filename (str) – 保存图像的路径。
• 质量 (int) – 结果JPEG文件的质量，必须是一个介于1和100之间的数字。默认值：75

torchvision.io.encode_png(input: torch.Tensor, compression_level: int = 6) → torch.Tensor

接受一个布局为 CHW 的输入张量，并返回其对应 PNG 文件的内容缓冲区。

Parameters:

• input (Tensor[channels, image_height, image_width]) – int8 图像张量，包含 0 个通道，其中 c 必须为 3 或 1。
• compression_level (int) – 结果文件的压缩因子，必须是介于 0 和 9 之间的数字。默认值：6

Returns:

输出 – 一个一维的int8张量，包含PNG文件的原始字节。

返回类型：

Tensor[1]

torchvision.io.write_png(input: torch.Tensor, filename: str, compression_level: int = 6)

接受一个布局为 CHW 的输入张量（对于灰度图像为 HW）， 并将其保存为 PNG 文件。

Parameters:

• 输入 (张量[通道数, 图像高度, 图像宽度]) – int8 图像张量，包含 c 个通道，其中 c 必须为 1 或 3。
• filename (str) – 保存图像的路径。
• compression_level (int) – 结果文件的压缩因子，必须是介于 0 和 9 之间的数字。默认值：6