• 文档 >
  • 图像变换和增强
快捷方式

图像变换和增强

Torchvision 在 torchvision.transformstorchvision.transforms.v2 模块中支持常见的计算机视觉变换。变换可用于变换或增强数据,以用于不同任务(图像分类、检测、分割、视频分类)的训练或推理。

# 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})

变换通常作为 数据集transformtransforms 参数传递。

从这里开始

无论您是 Torchvision 变换的新手,还是已经有经验的用户,我们都鼓励您从v2 变换入门开始,以了解更多关于新的 v2 变换可以做什么。

然后,浏览此页面下方的章节,了解一般信息和性能技巧。可用的变换和函数列在API 参考中。

更多信息和教程也可以在我们的示例库中找到,例如v2 变换:端到端对象检测/分割示例如何编写自己的 v2 变换

支持的输入类型和约定

大多数变换同时接受 PIL 图像和张量输入。CPU 和 CUDA 张量都受支持。两个后端(PIL 或张量)的结果应该非常接近。一般来说,我们建议依赖张量后端以获得性能转换变换可用于转换为 PIL 图像和从 PIL 图像转换,或用于转换数据类型和范围。

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

数据类型和预期值范围

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

使用 ToDtype 来转换输入的数据类型和范围。

V1 还是 V2?我应该使用哪一个?

TL;DR 我们建议使用 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 数据类型,尤其是在调整大小时

  • 使用双线性或双三次模式调整大小

以下是一个典型的变换管道示例

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]),
])

以上应在典型的训练环境中为您提供最佳性能,该环境依赖于具有 num_workers > 0torch.utils.data.DataLoader

变换往往对输入步幅/内存格式敏感。某些变换在通道优先图像上会更快,而另一些则更喜欢通道最后。与 torch 运算符一样,大多数变换将保留输入的内存格式,但这可能并不总是因实现细节而得到尊重。如果您正在追求最佳性能,您可能需要进行一些实验。在单个变换上使用 torch.compile() 也可能有助于分解内存格式变量(例如,在 Normalize 上)。请注意,我们讨论的是内存格式,而不是张量形状

请注意,调整大小变换(如 ResizeRandomResizedCrop)通常更喜欢通道最后输入,并且目前受益于 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 命名空间还包含我们称之为“内核”的内容。这些是实现特定类型的核心功能的底层函数,例如 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 之间的实现差异,这可能会导致脚本化执行和即时执行之间略有不同的结果。

如果您确实需要 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])

在给定图像的所有边上用给定的“pad”值进行填充。

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, ...)

使用方形变换矩阵和离线计算的 mean_vector 来变换张量图像。

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 图像转换为相同类型的张量 - 这不会缩放值。

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 Wide 的数据集无关的数据增强,如 "TrivialAugment: Tuning-free Yet State-of-the-Art Data Augmentation" 中所述。

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 图像。

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])

在给定图像的所有边上用给定的“pad”值进行填充。

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

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

pil_to_tensor(pic)

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

posterize(img, bits)

通过减少每个颜色通道的位数来对图像进行海报化处理。

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/灰度图像进行日晒处理。

ten_crop(img, size[, vertical_flip])

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

to_grayscale(img[, num_output_channels])

将任何模式(RGB、HSV、LAB 等)的 PIL 图像转换为灰度图像版本。

to_pil_image(pic[, mode])

将张量或 ndarray 转换为 PIL 图像。

to_tensor(pic)

PIL Imagenumpy.ndarray 转换为张量。

vflip(img)

垂直翻转给定图像。

文档

访问 PyTorch 的综合开发者文档

查看文档

教程

获取面向初学者和高级开发者的深度教程

查看教程

资源

查找开发资源并获得问题解答

查看资源