torchvision.io¶

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

视频¶

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

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

Parameters

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

Returns

第 T 帧视频 aframes (Tensor[K, L])：音频帧，其中 K 是通道数，L 是点的数量 info (Dict)：视频和音频的元数据。可以包含字段 video_fps (float) 和 audio_fps (int)

Return type

vframes (张量[T, H, W, C])

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

列出视频帧的时间戳。

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

Parameters

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

Returns

视频中每一帧的时间戳。 video_fps (float，可选)：视频的帧率

Return type

pts (List[int] 如果 pts_unit = ‘pts’，List[Fraction] 如果 pts_unit = ‘sec’)

torchvision.io.write_video(filename: str, video_array: torch.Tensor, fps: float, video_codec: str = 'libx264', options: Optional[Dict[str, Any]] = None, audio_array: Optional[torch.Tensor] = None, audio_fps: Optional[float] = None, audio_codec: Optional[str] = None, audio_options: Optional[Dict[str, Any]] = None) → None[source]¶

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

Parameters

filename (str) – 视频将被保存的路径
video_array (张量[T, H, W, C]) – 包含单个帧的张量，格式为[T, H, W, C]的uint8张量
帧率 (数字) – 每秒视频帧数
视频编解码器名称 (str) – 视频编解码器的名称，例如“libx264”，“h264”等。
选项 (字典) – 包含要传递给PyAV视频流的选项的字典
audio_array (张量[C, N]) – 包含音频的张量，其中 C 是通道数而 N 是样本数
音频采样率 (数字) – 音频样本率，通常是44100或48000
音频编解码器名称 (str) – 音频编解码器的名称，例如“mp3”，“aac”等。
音频选项 (字典) – 包含要传递给PyAV音频流的选项的字典

细粒度视频API¶

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

class torchvision.io.VideoReader(path, stream='video')[source]¶

细粒度视频读取 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__()[source]¶

解码并返回当前流的下一帧。帧被编码为一个字典，其中包含必要的数据和 pts 字段，数据是一个张量，pts 是以浮点数表示的帧的显示时间戳，单位为秒。

Returns: 一个字典，包含解码后的帧（data）和对应的以秒为单位的时间戳（pts）
Return type: (字典)

get_metadata()[source]¶

返回视频元数据

Returns: 包含每个流的时长和帧率的字典
Return type: (字典)

seek(time_s: float)[source]¶

在当前流中查找。

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

注意

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

set_current_stream(stream: str)[source]¶

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

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

查看视频示例：

import torchvision
video_path = "path to a test video"
# Constructor allocates memory and a threaded decoder
# instance per video. At the moment 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")

图像¶

class torchvision.io.ImageReadMode[source]¶

支持以各种模式读取图像。

使用 ImageReadMode.UNCHANGED 以原始格式加载图像， ImageReadMode.GRAY 转换为灰度图像， ImageReadMode.GRAY_ALPHA 带透明度的灰度图像， ImageReadMode.RGB 用于RGB图像， ImageReadMode.RGB_ALPHA 用于带透明度的RGB图像。

torchvision.io.read_image(path: str, mode: torchvision.io.image.ImageReadMode = <ImageReadMode.UNCHANGED: 0>) → torch.Tensor[source]¶

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

Parameters

路径 (字符串) – JPEG或PNG图像的路径。
模式 (ImageReadMode) – 可选用于转换图像的读取模式。默认值：ImageReadMode.UNCHANGED。有关各种可用模式的更多信息，请参见ImageReadMode类。

Returns

输出 (张量[图像通道数，图像高度，图像宽度])

使用 read_image 的示例:

torchvision.io.decode_image(input: torch.Tensor, mode: torchvision.io.image.ImageReadMode = <ImageReadMode.UNCHANGED: 0>) → torch.Tensor[source]¶

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

可选地将图像转换为所需的格式。输出张量的值为0到255之间的uint8类型。

Parameters

输入 (张量) – 包含PNG或JPEG图像原始字节的一维uint8张量。
模式 (ImageReadMode) – 可选用于转换图像的读取模式。默认值：ImageReadMode.UNCHANGED。有关各种可用模式的更多信息，请参见ImageReadMode类。

Returns

输出 (张量[图像通道数，图像高度，图像宽度])

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

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

Parameters

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

Returns

A one dimensional int8 tensor that contains the raw bytes of the: JPEG 文件。

Return type

输出 (张量[1])

torchvision.io.decode_jpeg(input: torch.Tensor, mode: torchvision.io.image.ImageReadMode = <ImageReadMode.UNCHANGED: 0>, device: str = 'cpu') → torch.Tensor[source]¶

解码一张JPEG图像为三维的RGB张量。可选地将图像转换为所需的格式。输出张量的值为0到255之间的uint8类型。

Parameters

输入 (Tensor[1]) – 一个一维的uint8张量，包含JPEG图像的原始字节。该张量必须在CPU上，无论device参数如何。
模式 (ImageReadMode) – 用于可选地转换图像的读取模式。默认值：ImageReadMode.UNCHANGED。有关各种可用模式的更多信息，请参见ImageReadMode类。
设备 (str 或 torch.device) – 存储解码图像的设备。如果指定了cuda设备，则图像将以nvjpeg进行解码。这仅支持CUDA版本 >= 10.1

Returns

输出 (张量[图像通道数，图像高度，图像宽度])

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

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

Parameters

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

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

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

Parameters

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

Returns

A one dimensional int8 tensor that contains the raw bytes of the: PNG文件。

Return type

Tensor[1]

torchvision.io.decode_png(input: torch.Tensor, mode: torchvision.io.image.ImageReadMode = <ImageReadMode.UNCHANGED: 0>) → torch.Tensor[source]¶

将一张 PNG 图像解码为三维的 RGB 张量。可选地将图像转换为所需的格式。输出张量的值为介于 0 和 255 之间的 uint8 类型。

Parameters

输入 (张量[1]) – 包含PNG图像原始字节的一维uint8张量。
模式 (ImageReadMode) – 用于可选地转换图像的读取模式。默认值：ImageReadMode.UNCHANGED。有关各种可用模式的更多信息，请参见 ImageReadMode 类。

Returns

输出 (张量[图像通道数，图像高度，图像宽度])

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

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

Parameters

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

torchvision.io.read_file(path: str) → torch.Tensor[source]¶

读取并以一维 uint8 张量的形式输出文件的字节内容。

Parameters: 路径 (字符串) – 要读取文件的路径
Returns: 数据 (张量)

torchvision.io.write_file(filename: str, data: torch.Tensor) → None[source]¶

将一个一维的 uint8 张量内容写入文件。

Parameters

文件名 (str) – 要写入的文件路径
数据 (张量) – 要写入输出文件的内容

torchvision.io¶

视频¶

细粒度视频API¶

图像¶

文档

教程

资源