目录
目录

转换和增强图像

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

Transforms 通常是作为 transform 或 transforms 参数传递给 数据集。

从这里开始

无论您是初次接触Torchvision变换，还是已经对它们有所了解，我们都建议您从 开始使用变换v2开始， 以便了解更多关于新v2变换的功能。

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

更多信息和教程也可以在我们的示例画廊中找到，例如Transforms v2：端到端对象检测/分割示例 或如何编写自己的v2转换器。

支持的输入类型和约定

大多数变换同时接受PIL图像和张量输入。支持CPU和CUDA张量。 两种后端（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中）具有很多优势：

这些转换与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]),
])

上面的内容应该能在典型训练环境中提供最佳性能，该环境依赖于torch.utils.data.DataLoader和num_workers > 0。

Transforms 对输入的步幅/内存格式较为敏感。某些变换在通道优先的图像上会更快，而其他变换则更喜欢通道最后的格式。像 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时进行参数采样。

The 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 transforms支持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(大小[，插值，最大尺寸，...])

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

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

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

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

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

CenterCrop(大小)

裁剪给定图像的中心部分。

FiveCrop(大小)

将给定图像裁剪为四个角和中央区域。

TenCrop(size[, vertical_flip])

将给定图像裁剪为四个角和中央区域，并加上这些裁剪图的水平翻转版本。

Pad(填充[，填充值，填充模式])

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

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

以角度旋转图像。

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

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

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

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

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

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

RandomHorizontalFlip([p])

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

RandomVerticalFlip([p])

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

颜色

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

随机改变图像的亮度、对比度、饱和度和色相。

Grayscale([输出通道数])

将图像转换为灰度图像。

RandomGrayscale([p])

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

GaussianBlur(kernel_size[, sigma])

使用随机选择的高斯模糊对图像进行模糊处理。

RandomInvert([p])

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

RandomPosterize(bits[, p])

以给定的概率随机将图像二值化，通过减少每个颜色通道的位数来生成图像。

RandomSolarize(threshold[, p])

以给定的概率随机对图像进行 solarize 处理，方法是反转所有高于阈值的像素值。

RandomAdjustSharpness(sharpness_factor[, p])

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

RandomAutocontrast([p])

以给定的概率随机增强给定图像的像素对比度。

RandomEqualize([p])

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

组成

Compose(数据增强)

组合多个变换操作。

RandomApply(transforms[, p])

以指定的概率随机应用一组变换。

RandomChoice(transforms[, p])

从列表中随机选择一个变换进行应用。

RandomOrder(数据增强)

以随机顺序应用一组转换。

杂项

LinearTransformation(transformation_matrix, ...)

用一个正方形变换矩阵和一个离线计算出的均值向量转换张量图像。

Normalize(均值, 标准差[, 就地])

用均值和标准差对张量图像进行标准化。

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

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

Lambda(lambda)

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

转换

注意

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

ToPILImage([mode])

将张量或 ndarray 转换为 PIL 图像

ToTensor()

将 PIL 图像或 ndarray 转换为张量，并相应地调整值。

PILToTensor()

将 PIL 图像转换为相同类型的张量——这不会缩放值。

ConvertImageDtype(数据类型)

将张量图像转换为指定的dtype并相应地调整值。

Auto-Augmentation

AutoAugment 是一种常见的数据增强技术，可以提高图像分类模型的准确性。 尽管数据增强策略直接与其训练数据集相关联，但经验研究表明， ImageNet 策略在应用于其他数据集时提供了显著的改进。 在 TorchVision 中，我们实现了以下数据集上学习到的 3 种策略：ImageNet、CIFAR10 和 SVHN。 新的变换可以单独使用或与现有变换混合使用：

AutoAugmentPolicy(值)

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

AutoAugment([policy, interpolation, fill])

基于"AutoAugment: 从数据中学习增强策略"的AutoAugment数据增强方法。

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

RandAugment 数据增强方法基于 "RandAugment: 实用的自动化数据增强与减少搜索空间"。

TrivialAugmentWide([num_magnitude_bins, ...])

与数据集无关的数据增强，使用TrivialAugment Wide，如在"TrivialAugment: 无需调优且达到最先进的数据增强"中所述。

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

AugMix数据增强方法基于"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(图像, 角度, 平移, 缩放, 扭曲)

对图像进行仿射变换，保持图像中心不变。

autocontrast(图)

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

center_crop(img, output_size)

裁剪给定图像的中心部分。

convert_image_dtype(image[, dtype])

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

crop(图片, 顶部, 左边, 高度, 宽度)

在指定位置裁剪给定图像并输出所需大小。

equalize(图)

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

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

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

five_crop(图片, 大小)

将给定图像裁剪为四个角和中央区域。

gaussian_blur(img, kernel_size[, sigma])

对图像执行高斯模糊，给定内核。

get_dimensions(图)

返回图像的尺寸为 [通道数, 高度, 宽度]。

get_image_num_channels(图)

返回图像的通道数。

get_image_size(图)

返回图像的大小为 [宽度，高度]。

hflip(图)

水平翻转给定的图像。

invert(图)

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

normalize(张量，均值，标准差[，就地])

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

pad(图像, 填充, 填充模式)

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

perspective(图像, 起始点, 结束点[, ...])

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

pil_to_tensor(图片)

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

posterize(图片, 位元)

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

resize(图像, 大小[, 插值, 最大尺寸, ...])

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

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

裁剪给定的图像并将其调整为所需的尺寸。

rgb_to_grayscale(img[, num_output_channels])

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

rotate(图像, 角度[, 插值方式, 扩展, ...])

以角度旋转图像。

solarize(图片, 阈值)

通过反转所有高于阈值的像素值来对 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 图像。

to_tensor(图片)

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

vflip(图)

垂直翻转给定的图像。

文档

访问 PyTorch 的全面开发人员文档

查看文档

教程

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

查看教程

资源

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

查看资源