目录
  • 文档 >
  • 转换图像、视频、框等
快捷方式

转换图像、视频、边界框等

Torchvision 在 torchvision.transforms.v2 模块中支持常见的计算机视觉转换。这些转换可用于在训练或推理时转换和增强数据。支持以下对象：

  • 作为纯张量、Image 或 PIL 图像的图像

  • 作为 Video 的视频

  • 作为 BoundingBoxes 的轴对齐和旋转边界框

  • 作为 Mask 的分割和检测掩码

  • 作为 KeyPoints 的关键点。

# Image Classification
import torch
from torchvision.transforms import v2

H, W = 32, 32
img = torch.randint(0, 256, size=(3, H, W), dtype=torch.uint8)

transforms = v2.Compose([
    v2.RandomResizedCrop(size=(224, 224), antialias=True),
    v2.RandomHorizontalFlip(p=0.5),
    v2.ToDtype(torch.float32, scale=True),
    v2.Normalize(mean=[0.485, 0.456, 0.406], std=[0.229, 0.224, 0.225]),
])
img = transforms(img)

# Detection (re-using imports and transforms from above)
from torchvision import tv_tensors

img = torch.randint(0, 256, size=(3, H, W), dtype=torch.uint8)
boxes = torch.randint(0, H // 2, size=(3, 4))
boxes[:, 2:] += boxes[:, :2]
boxes = tv_tensors.BoundingBoxes(boxes, format="XYXY", canvas_size=(H, W))

# The same transforms can be used!
img, boxes = transforms(img, boxes)
# And you can pass arbitrary input structures
output_dict = transforms({"image": img, "boxes": boxes})

转换通常作为 数据集 (Datasets) 的 transform 或 transforms 参数传递。

从这里开始

无论您是 Torchvision 转换的新手，还是已经经验丰富，我们都建议您从 Transforms v2 入门 开始，以了解如何使用新的 v2 转换。

然后，浏览本页面下方的部分以获取常规信息和性能提示。可用的转换和函数列在 API 参考 中。

更多信息和教程可以在我们的 示例库 中找到，例如 Transforms v2：端到端目标检测/分割示例 或 如何编写您自己的 v2 转换。

支持的输入类型和约定

大多数转换同时接受 PIL 图像和张量输入。支持 CPU 和 CUDA 张量。两个后端（PIL 或张量）的结果应该非常接近。通常，我们建议为了性能考虑依赖张量后端。转换（Conversion）操作 可用于在 PIL 图像之间转换，或者用于转换数据类型和数值范围。

张量图像的预期形状为 (C, H, W)，其中 C 是通道数，H 和 W 分别指高度和宽度。大多数转换支持批处理张量输入。一批张量图像是一个形状为 (N, C, H, W) 的张量，其中 N 是批处理中图像的数量。v2 转换通常接受任意数量的前导维度 (..., C, H, W)，并且可以处理批处理图像或批处理视频。

数据类型和预期的数值范围

张量图像数值的预期范围由张量数据类型（dtype）隐式定义。浮点型数据类型的张量图像预期数值在 [0, 1] 之间。整型数据类型的张量图像预期数值在 [0, MAX_DTYPE] 之间，其中 MAX_DTYPE 是该数据类型可表示的最大值。通常，数据类型为 torch.uint8 的图像预期数值在 [0, 255] 之间。

使用 ToDtype 来转换输入的 dtype 和范围。

V1 还是 V2？我该使用哪一个？

简而言之：我们建议使用 torchvision.transforms.v2 转换，而不是 torchvision.transforms 中的转换。它们更快，功能更强大。只需更改导入语句，即可顺利运行。未来，新功能和改进将仅针对 v2 转换进行考虑。

在 Torchvision 0.15（2023 年 3 月）中，我们在 torchvision.transforms.v2 命名空间中发布了一套新的转换。与 v1（在 torchvision.transforms 中）相比，这些转换具有许多优势：

这些转换与 v1 完全向后兼容，因此如果您已经在从 torchvision.transforms 使用转换，您只需将导入更改为 torchvision.transforms.v2 即可。在输出方面，由于实现差异，可能会有微不足道的偏差。

性能考量

我们建议遵循以下指南以从转换中获得最佳性能：

  • 依赖来自 torchvision.transforms.v2 的 v2 转换

  • 使用张量而不是 PIL 图像

  • 使用 torch.uint8 数据类型，特别是在调整大小（resizing）时

  • 使用双线性（bilinear）或双三次（bicubic）模式调整大小

这是典型的转换管道的样子：

from torchvision.transforms import v2
transforms = v2.Compose([
    v2.ToImage(),  # Convert to tensor, only needed if you had a PIL image
    v2.ToDtype(torch.uint8, scale=True),  # optional, most input are already uint8 at this point
    # ...
    v2.RandomResizedCrop(size=(224, 224), antialias=True),  # Or Resize(antialias=True)
    # ...
    v2.ToDtype(torch.float32, scale=True),  # Normalize expects float input
    v2.Normalize(mean=[0.485, 0.456, 0.406], std=[0.229, 0.224, 0.225]),
])

上述建议应能在依赖 torch.utils.data.DataLoader 且 num_workers > 0 的典型训练环境中为您提供最佳性能。

转换往往对输入跨度（strides）/内存格式敏感。某些转换对“通道优先”（channels-first）的图像更快，而另一些则更喜欢“通道最后”（channels-last）。像 torch 操作符一样，大多数转换会保留输入的内存格式，但这可能并不总是被遵守（取决于实现细节）。如果您追求极致性能，您可能需要进行一些实验。在单个转换上使用 torch.compile() 可能也有助于消除内存格式变量（例如在 Normalize 上）。请注意，我们谈论的是内存格式，而不是张量形状。

请注意，像 Resize 和 RandomResizedCrop 这样的调整大小转换通常更喜欢通道最后的输入，并且目前往往无法从 torch.compile() 中受益。

转换类、函数和内核

转换不仅可以作为类（如 Resize），也可以作为函数（如 resize()）在 torchvision.transforms.v2.functional 命名空间中使用。这非常类似于 torch.nn 包，它同时定义了类和 torch.nn.functional 中的函数式等价物。

这些函数支持 PIL 图像、纯张量或 TVTensors，例如 resize(image_tensor) 和 resize(boxes) 都是有效的。

注意

像 RandomCrop 这样的随机转换在每次被调用时都会随机采样参数。它们的函数式对应物（crop()）不会进行任何形式的随机采样，因此具有略微不同的参数化方式。转换类的 get_params() 类方法可用于在使用函数式 API 时执行参数采样。

torchvision.transforms.v2.functional 命名空间还包含我们所谓的“内核”（kernels）。这些是为特定类型实现核心功能的底层函数，例如 resize_bounding_boxes 或 resized_crop_mask。它们是公开的，尽管没有文档记录。查看 代码 以查看哪些可用（注意那些以下划线开头的函数是非公开的！）。内核仅在您需要针对边界框或掩码等类型进行 Torchscript 支持 时才真正有用。

Torchscript 支持

大多数转换类和函数都支持 Torchscript。对于组合转换，请使用 torch.nn.Sequential 而不是 Compose。

transforms = torch.nn.Sequential(
    CenterCrop(10),
    Normalize((0.485, 0.456, 0.406), (0.229, 0.224, 0.225)),
)
scripted_transforms = torch.jit.script(transforms)

警告

v2 转换支持 Torchscript，但如果您对 v2 类转换调用 torch.jit.script()，您实际上最终会得到其（已脚本化的）v1 等价物。由于 v1 和 v2 之间的实现差异，这可能会导致脚本化执行和即时（eager）执行之间的结果略有不同。

如果您确实需要 v2 转换的 Torchscript 支持，我们建议脚本化 torchvision.transforms.v2.functional 命名空间中的函数，以避免意外。

还要注意，函数仅对纯张量支持 Torchscript，纯张量总是被视为图像。如果您需要针对边界框或掩码等其他类型的 Torchscript 支持，您可以依赖底层内核。

任何要与 torch.jit.script 一起使用的自定义转换都应派生自 torch.nn.Module。

参见：Torchscript 支持。

V1 API 参考

几何操作

Resize(size[, interpolation, max_size, ...])

将输入图像调整为给定大小。

RandomCrop(size[, padding, pad_if_needed, ...])

在随机位置裁剪给定图像。

RandomResizedCrop(size[, scale, ratio, ...])

裁剪图像的随机部分并将其调整为给定大小。

CenterCrop(size)

在中心裁剪给定图像。

FiveCrop(size)

将给定图像裁剪为四个角和中心裁剪。

TenCrop(size[, vertical_flip])

将给定图像裁剪为四个角和中心裁剪，加上这些裁剪的翻转版本（默认使用水平翻转）。

Pad(padding[, fill, padding_mode])

用给定的“填充”值在各侧填充给定图像。

RandomRotation(degrees[, interpolation, ...])

按角度旋转图像。

RandomAffine(degrees[, translate, scale, ...])

图像保持中心不变的随机仿射变换。

RandomPerspective([distortion_scale, p, ...])

以给定的概率对给定图像执行随机透视变换。

ElasticTransform([alpha, sigma, ...])

用弹性变换转换张量图像。

RandomHorizontalFlip([p])

以给定的概率随机水平翻转给定图像。

RandomVerticalFlip([p])

以给定的概率随机垂直翻转给定图像。

颜色

ColorJitter([brightness, contrast, ...])

随机更改图像的亮度、对比度、饱和度和色调。

Grayscale([num_output_channels])

将图像转换为灰度。

RandomGrayscale([p])

以 p 的概率随机将图像转换为灰度（默认为 0.1）。

GaussianBlur(kernel_size[, sigma])

用随机选择的高斯模糊模糊图像。

RandomInvert([p])

以给定的概率随机反转给定图像的颜色。

RandomPosterize(bits[, p])

通过减少每个颜色通道的位数，以给定的概率随机对图像进行色调分离。

RandomSolarize(threshold[, p])

通过反转超过阈值的所有像素值，以给定的概率随机对图像进行曝光。

RandomAdjustSharpness(sharpness_factor[, p])

以给定的概率随机调整图像的锐度。

RandomAutocontrast([p])

以给定的概率随机自动对比给定图像的像素。

RandomEqualize([p])

以给定的概率随机均衡给定图像的直方图。

组合

Compose(transforms)

将多个转换组合在一起。

RandomApply(transforms[, p])

以给定的概率随机应用一系列变换。

RandomChoice(transforms[, p])

应用从列表中随机挑选的单个转换。

RandomOrder(transforms)

以随机顺序应用一系列转换。

其他

LinearTransformation(transformation_matrix, ...)

用平方变换矩阵和离线计算的均值向量变换张量图像。

Normalize(mean, std[, inplace])

用均值和标准差归一化张量图像。

RandomErasing([p, scale, ratio, value, inplace])

随机选择 torch.Tensor 图像中的矩形区域并擦除其像素。

Lambda(lambd)

应用用户定义的 lambda 作为转换。

转换操作

注意

请注意，下面的一些转换操作在执行转换时会缩放数值，而一些可能不会进行任何缩放。通过缩放，我们指例如 uint8 -> float32 会将 [0, 255] 范围映射到 [0, 1]（反之亦然）。详情请参阅 数据类型和预期的数值范围。

ToPILImage([mode])

将张量或 ndarray 转换为 PIL 图像

ToTensor()

将 PIL 图像或 ndarray 转换为张量并相应地缩放值。

PILToTensor()

将 PIL Image 转换为相同类型的张量 - 此操作不缩放值。

ConvertImageDtype(dtype)

将张量图像转换为给定的 dtype 并相应地缩放数值。

自动增强

AutoAugment 是一种常用的数据增强技术，可以提高图像分类模型的准确性。虽然数据增强策略直接与训练数据集挂钩，但实证研究表明，当应用于其他数据集时，ImageNet 策略也能提供显著改进。在 TorchVision 中，我们在以下数据集上实现了 3 种习得策略：ImageNet、CIFAR10 和 SVHN。这种新的转换可以单独使用，也可以与现有转换混合搭配使用。

AutoAugmentPolicy(value)

在不同数据集上学习到的 AutoAugment 策略。

AutoAugment([policy, interpolation, fill])

基于 “AutoAugment: Learning Augmentation Strategies from Data” 的 AutoAugment 数据增强方法。

RandAugment([num_ops, magnitude, ...])

基于 “RandAugment: Practical automated data augmentation with a reduced search space” 的 RandAugment 数据增强方法。

TrivialAugmentWide([num_magnitude_bins, ...])

如 “TrivialAugment: Tuning-free Yet State-of-the-Art Data Augmentation” 中所述，使用 TrivialAugment Wide 进行数据集无关的数据增强。

AugMix([severity, mixture_width, ...])

基于 “AugMix: A Simple Data Processing Method to Improve Robustness and Uncertainty” 的 AugMix 数据增强方法。

函数式转换

adjust_brightness(img, brightness_factor)

调整图像的亮度。

adjust_contrast(img, contrast_factor)

调整图像的对比度。

adjust_gamma(img, gamma[, gain])

对图像执行伽马校正。

adjust_hue(img, hue_factor)

调整图像的色调。

adjust_saturation(img, saturation_factor)

调整图像的颜色饱和度。

adjust_sharpness(img, sharpness_factor)

调整图像的锐度。

affine(img, angle, translate, scale, shear)

对图像应用仿射变换，保持图像中心不变。

autocontrast(img)

通过逐通道重新映射像素来最大化图像的对比度，使最暗的像素变为黑色，最亮的变为白色。

center_crop(img, output_size)

在中心裁剪给定图像。

convert_image_dtype(image[, dtype])

将张量图像转换为给定的 dtype 并相应地缩放数值。此函数不支持 PIL Image。

crop(img, top, left, height, width)

在指定位置和输出大小裁剪给定图像。

equalize(img)

通过对输入应用非线性映射来均衡图像直方图，以便在输出中创建灰度值的均匀分布。

erase(img, i, j, h, w, v[, inplace])

使用给定值擦除输入的张量图像。

five_crop(img, size)

将给定图像裁剪为四个角和中心裁剪。

gaussian_blur(img, kernel_size[, sigma])

通过给定的卷积核对图像执行高斯模糊。

get_dimensions(img)

以 [通道, 高, 宽] 的形式返回图像的维度。

get_image_num_channels(img)

返回图像的通道数。

get_image_size(img)

以 [宽, 高] 的形式返回图像的大小。

hflip(img)

将给定的图像水平翻转。

invert(img)

反转 RGB/灰度图像的颜色。

normalize(tensor, mean, std[, inplace])

使用均值和标准差对浮点型张量图像进行归一化。

pad(img, padding[, fill, padding_mode])

用给定的“填充”值在各侧填充给定图像。

perspective(img, startpoints, endpoints[, ...])

对给定图像执行透视变换。

pil_to_tensor(pic)

将 PIL Image 转换为相同类型的张量。

posterize(img, bits)

通过减少每个颜色通道的位数来实现图像色调分离（Posterize）。

resize(img, size[, interpolation, max_size, ...])

将输入图像调整为给定大小。

resized_crop(img, top, left, height, width, size)

裁剪给定的图像并将其调整为目标大小。

rgb_to_grayscale(img[, num_output_channels])

将 RGB 图像转换为灰度版本。

rotate(img, angle[, interpolation, expand, ...])

按角度旋转图像。

solarize(img, threshold)

通过反转超过阈值的所有像素值，对 RGB/灰度图像进行曝光（Solarize）处理。

ten_crop(img, size[, vertical_flip])

从给定图像中生成十个裁剪后的图像。

to_grayscale(img[, num_output_channels])

将任何模式（RGB, HSV, LAB 等）的 PIL 图像转换为灰度版本。

to_pil_image(pic[, mode])

将张量或 ndarray 转换为 PIL Image。

to_tensor(pic)

将 PIL Image 或 numpy.ndarray 转换为张量。

vflip(img)

将给定的图像垂直翻转。

文档

访问全面的 PyTorch 开发者文档

查看文档

教程

为初学者和高级开发者提供深入的教程

查看教程

资源

查找开发资源并让您的问题得到解答

查看资源

为了分析流量并优化您的体验，我们在此网站上使用 Cookie。点击或浏览即表示您同意我们使用 Cookie。作为本网站的当前维护者，Facebook 的 Cookie 政策适用。了解更多信息，包括可用的控件： Cookie 政策。