图像变换和增强¶
Torchvision 在 torchvision.transforms
和 torchvision.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})
变换通常作为 数据集 的 transform
或 transforms
参数传递。
从这里开始¶
无论您是 Torchvision 变换的新手,还是已经有经验的用户,我们都鼓励您从v2 变换入门开始,以了解更多关于新的 v2 变换可以做什么。
然后,浏览此页面下方的章节,了解一般信息和性能技巧。可用的变换和函数列在API 参考中。
更多信息和教程也可以在我们的示例库中找到,例如v2 变换:端到端对象检测/分割示例或如何编写自己的 v2 变换。
支持的输入类型和约定¶
大多数变换同时接受 PIL 图像和张量输入。CPU 和 CUDA 张量都受支持。两个后端(PIL 或张量)的结果应该非常接近。一般来说,我们建议依赖张量后端以获得性能。转换变换可用于转换为 PIL 图像和从 PIL 图像转换,或用于转换数据类型和范围。
张量图像应为 (C, H, W)
形状,其中 C
是通道数,H
和 W
分别指高度和宽度。大多数变换支持批量张量输入。一批张量图像是形状为 (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
中)相比,这些变换有很多优势
它们可以变换图像,还可以变换边界框、掩码或视频。这为超出图像分类的任务提供了支持:检测、分割、视频分类等。请参阅v2 变换入门和v2 变换:端到端对象检测/分割示例。
它们支持更多变换,例如
CutMix
和MixUp
。请参阅如何使用 CutMix 和 MixUp。它们更快。
它们支持任意输入结构(字典、列表、元组等)。
未来的改进和功能将仅添加到 v2 变换中。
这些变换与 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 > 0
的 torch.utils.data.DataLoader
。
变换往往对输入步幅/内存格式敏感。某些变换在通道优先图像上会更快,而另一些则更喜欢通道最后。与 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
命名空间还包含我们称之为“内核”的内容。这些是实现特定类型的核心功能的底层函数,例如 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 支持。
V2 API 参考 - 推荐¶
几何变换¶
调整大小¶
|
将输入调整为给定大小。 |
|
根据"Simple Copy-Paste is a Strong Data Augmentation Method for Instance Segmentation"对输入执行大尺度抖动。 |
|
随机调整输入大小。 |
|
随机调整输入大小。 |
函数
|
有关详细信息,请参阅 |
裁剪¶
|
在随机位置裁剪输入。 |
|
裁剪输入的随机部分并将其调整为给定大小。 |
|
来自"SSD: Single Shot MultiBox Detector"的随机 IoU 裁剪变换。 |
|
在中心裁剪输入。 |
|
将图像或视频裁剪为四个角和中心裁剪。 |
|
将图像或视频裁剪为四个角和中心裁剪,以及这些的翻转版本(默认使用水平翻转)。 |
函数
|
有关详细信息,请参阅 |
|
有关详细信息,请参阅 |
|
有关详细信息,请参阅 |
|
有关详细信息,请参阅 |
|
有关详细信息,请参阅 |
其他¶
以给定的概率水平翻转输入。 |
|
以给定的概率垂直翻转输入。 |
|
|
使用给定的“pad”值在所有边上填充输入。 |
|
来自"SSD: Single Shot MultiBox Detector"的“缩小”变换。 |
|
按角度旋转输入。 |
|
保持中心不变的随机仿射变换输入。 |
|
以给定的概率对输入执行随机透视变换。 |
|
使用弹性变换变换输入。 |
函数
有关详细信息,请参阅 |
|
有关详细信息,请参阅 |
|
|
有关详细信息,请参阅 |
|
有关详细信息,请参阅 |
|
有关详细信息,请参阅 |
|
有关详细信息,请参阅 |
|
参见 |
颜色¶
|
随机更改图像或视频的亮度、对比度、饱和度和色调。 |
随机置换图像或视频的通道 |
|
|
随机扭曲图像或视频,如 SSD: Single Shot MultiBox Detector 中所用。 |
|
将图像或视频转换为灰度。 |
|
将图像或视频转换为 RGB 格式(如果它们还不是 RGB 格式)。 |
|
以概率 p(默认为 0.1)随机将图像或视频转换为灰度。 |
|
使用随机选择的高斯模糊内核模糊图像。 |
|
向图像或视频添加高斯噪声。 |
|
以给定的概率反转给定图像或视频的颜色。 |
|
通过减少每个颜色通道的位数,以给定的概率对图像或视频进行海报化处理。 |
|
通过反转所有高于阈值的像素值,以给定的概率对图像或视频进行日晒处理。 |
|
以给定的概率调整图像或视频的锐度。 |
以给定的概率自动对比给定图像或视频的像素。 |
|
|
以给定的概率均衡给定图像或视频的直方图。 |
函数
|
根据给定的置换方式置换输入的通道。 |
|
参见 |
参见 |
|
|
参见 |
|
参见 |
|
参见 |
|
参见 |
|
参见 |
|
参见 |
|
参见 |
参见 |
|
|
参见 |
|
参见 |
|
调整亮度。 |
|
调整饱和度。 |
|
调整色调 |
|
调整伽马值。 |
组合¶
|
将多个变换组合在一起。 |
|
以给定的概率随机应用变换列表中的变换。 |
|
从列表中随机选择并应用单个变换。 |
|
以随机顺序应用变换列表中的变换。 |
其他¶
使用离线计算的平方变换矩阵和 mean_vector 变换张量图像或视频。 |
|
|
使用均值和标准差归一化张量图像或视频。 |
|
在输入图像或视频中随机选择一个矩形区域并擦除其像素。 |
|
将用户定义的函数用作变换。 |
|
移除退化/无效的边界框及其对应的标签和掩码。 |
将边界框钳制到其对应的图像尺寸内。 |
|
|
从视频的时间维度均匀地子采样 |
|
对给定的图像应用 JPEG 压缩和解压缩。 |
函数
|
参见 |
|
参见 |
|
移除退化/无效的边界框并返回相应的索引掩码。 |
|
参见 |
参见 |
|
|
参见 |
转换¶
注意
请注意,以下一些转换变换在执行转换时会缩放值,而另一些可能不会进行任何缩放。 缩放是指例如 uint8
-> float32
会将 [0, 255] 范围映射到 [0, 1](反之亦然)。 参见 数据类型和预期值范围。
将张量、ndarray 或 PIL 图像转换为 |
|
将所有 TVTensor 转换为纯张量,移除关联的元数据(如果有)。 |
|
将 PIL 图像转换为相同类型的张量 - 这不会缩放值。 |
|
|
将张量或 ndarray 转换为 PIL 图像 |
|
将输入转换为特定的 dtype,可以选择缩放图像或视频的值。 |
|
将边界框坐标转换为给定的 |
函数式方法
|
参见 |
将 |
|
|
将张量或 ndarray 转换为 PIL 图像。 |
|
参见 |
参见 |
已弃用
[已弃用] 请使用 |
|
|
[已弃用] 请使用 to_image() 和 to_dtype() 代替。 |
|
[已弃用] 请使用 |
|
[已弃用] 请使用 to_dtype() 代替。 |
自动增强¶
AutoAugment 是一种常见的数据增强技术,可以提高图像分类模型的准确率。 虽然数据增强策略与其训练数据集直接相关,但经验研究表明,ImageNet 策略在应用于其他数据集时可提供显着改进。 在 TorchVision 中,我们实现了在以下数据集上学习的 3 种策略:ImageNet、CIFAR10 和 SVHN。 新的变换可以单独使用,也可以与现有变换混合搭配使用
|
基于 "AutoAugment: Learning Augmentation Strategies from Data" 的 AutoAugment 数据增强方法。 |
|
基于 "RandAugment: Practical automated data augmentation with a reduced search space" 的 RandAugment 数据增强方法。 |
|
使用 TrivialAugment Wide 的数据集无关的数据增强,如 "TrivialAugment: Tuning-free Yet State-of-the-Art Data Augmentation" 中所述。 |
|
基于 "AugMix: A Simple Data Processing Method to Improve Robustness and Uncertainty" 的 AugMix 数据增强方法。 |
CutMix - MixUp¶
CutMix 和 MixUp 是特殊的变换,旨在用于批次而不是单个图像,因为它们将图像对组合在一起。 这些可以在数据加载器之后(样本批量处理后)或作为整理函数的一部分使用。 有关详细的使用示例,请参见 如何使用 CutMix 和 MixUp 。
|
将 CutMix 应用于提供的图像和标签批次。 |
|
将 MixUp 应用于提供的图像和标签批次。 |
开发者工具¶
用于实现您自己的 v2 变换的基类。 |
|
装饰器一个内核,将其注册到一个函数式方法和一个(自定义)tv_tensor 类型。 |
|
返回高度和宽度。 |
|
返回通道数、高度和宽度。 |
|
返回输入中的边界框。 |
V1 API 参考¶
几何变换¶
|
将输入图像调整为给定大小。 |
|
在随机位置裁剪给定的图像。 |
|
裁剪图像的随机部分并将其调整为给定大小。 |
|
在中心裁剪给定的图像。 |
|
将给定的图像裁剪为四个角和中心裁剪。 |
|
将给定的图像裁剪为四个角和中心裁剪,以及这些裁剪的翻转版本(默认使用水平翻转)。 |
|
在给定图像的所有边上用给定的“pad”值进行填充。 |
|
按角度旋转图像。 |
|
保持中心不变的图像的随机仿射变换。 |
|
对给定图像执行具有给定概率的随机透视变换。 |
|
使用弹性变换来变换张量图像。 |
|
以给定的概率随机水平翻转给定图像。 |
|
以给定的概率随机垂直翻转给定图像。 |
颜色¶
|
随机更改图像的亮度、对比度、饱和度和色调。 |
|
将图像转换为灰度图。 |
|
以概率 p(默认 0.1)随机将图像转换为灰度图。 |
|
使用随机选择的高斯模糊来模糊图像。 |
|
以给定的概率随机反转给定图像的颜色。 |
|
通过减少每个颜色通道的位数,以给定的概率随机对图像进行海报化处理。 |
|
通过反转所有高于阈值的像素值,以给定的概率随机对图像进行日晒处理。 |
|
以给定的概率随机调整图像的锐度。 |
|
以给定的概率随机自动对比度调整给定图像的像素。 |
|
以给定的概率随机均衡给定图像的直方图。 |
组合¶
|
将多个变换组合在一起。 |
|
以给定的概率随机应用变换列表中的变换。 |
|
从列表中随机选择并应用单个变换。 |
|
以随机顺序应用变换列表中的变换。 |
其他¶
|
使用方形变换矩阵和离线计算的 mean_vector 来变换张量图像。 |
|
使用均值和标准差来标准化张量图像。 |
|
在 torch.Tensor 图像中随机选择一个矩形区域并擦除其像素。 |
|
应用用户定义的 lambda 作为变换。 |
转换¶
注意
请注意,以下一些转换变换在执行转换时会缩放值,而另一些可能不会进行任何缩放。 缩放是指例如 uint8
-> float32
会将 [0, 255] 范围映射到 [0, 1](反之亦然)。 参见 数据类型和预期值范围。
|
将张量或 ndarray 转换为 PIL 图像 |
|
将 PIL 图像或 ndarray 转换为张量,并相应地缩放值。 |
将 PIL 图像转换为相同类型的张量 - 这不会缩放值。 |
|
|
将张量图像转换为给定的 |
自动增强¶
AutoAugment 是一种常见的数据增强技术,可以提高图像分类模型的准确率。 虽然数据增强策略与其训练数据集直接相关,但经验研究表明,ImageNet 策略在应用于其他数据集时可提供显着改进。 在 TorchVision 中,我们实现了在以下数据集上学习的 3 种策略:ImageNet、CIFAR10 和 SVHN。 新的变换可以单独使用,也可以与现有变换混合搭配使用
|
在不同数据集上学习的 AutoAugment 策略。 |
|
基于 "AutoAugment: Learning Augmentation Strategies from Data" 的 AutoAugment 数据增强方法。 |
|
基于 "RandAugment: Practical automated data augmentation with a reduced search space" 的 RandAugment 数据增强方法。 |
|
使用 TrivialAugment Wide 的数据集无关的数据增强,如 "TrivialAugment: Tuning-free Yet State-of-the-Art Data Augmentation" 中所述。 |
|
基于 "AugMix: A Simple Data Processing Method to Improve Robustness and Uncertainty" 的 AugMix 数据增强方法。 |
函数式变换¶
|
调整图像的亮度。 |
|
调整图像的对比度。 |
|
对图像执行伽马校正。 |
|
调整图像的色调。 |
|
调整图像的颜色饱和度。 |
|
调整图像的锐度。 |
|
对图像应用仿射变换,保持图像中心不变。 |
|
通过重新映射每个通道的像素来最大化图像的对比度,使最低的变为黑色,最亮的变为白色。 |
|
在中心裁剪给定的图像。 |
|
将张量图像转换为给定的 |
|
在指定位置和输出大小裁剪给定图像。 |
|
通过对输入应用非线性映射来均衡图像的直方图,以便在输出中创建灰度值的均匀分布。 |
|
使用给定值擦除输入张量图像。 |
|
将给定的图像裁剪为四个角和中心裁剪。 |
|
通过给定的内核对图像执行高斯模糊。 |
|
返回图像的维度,格式为 [通道数, 高度, 宽度]。 |
返回图像的通道数。 |
|
|
返回图像的大小,格式为 [宽度, 高度]。 |
|
水平翻转给定图像。 |
|
反转 RGB/灰度图像的颜色。 |
|
使用均值和标准差来标准化浮点张量图像。 |
|
在给定图像的所有边上用给定的“pad”值进行填充。 |
|
对给定图像执行透视变换。 |
|
将 |
|
通过减少每个颜色通道的位数来对图像进行海报化处理。 |
|
将输入图像调整为给定大小。 |
|
裁剪给定图像并将其调整为所需大小。 |
|
将 RGB 图像转换为灰度图像版本。 |
|
按角度旋转图像。 |
|
通过反转所有高于阈值的像素值来对 RGB/灰度图像进行日晒处理。 |
|
从给定图像生成十个裁剪后的图像。 |
|
将任何模式(RGB、HSV、LAB 等)的 PIL 图像转换为灰度图像版本。 |
|
将张量或 ndarray 转换为 PIL 图像。 |
|
将 |
|
垂直翻转给定图像。 |