目錄
  • 文件 >
  • 轉換和擴增影像
捷徑

轉換和擴增影像

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 影像轉換，或用於轉換資料類型和範圍。

Tensor 影像預期為 (C, H, W) 的形狀，其中 C 是通道數，而 H 和 W 分別代表高度和寬度。大多數的轉換都支援批次 tensor 輸入。一批 Tensor 影像的 shape 為 (N, C, H, W)，其中 N 是批次中的影像數量。 v2 轉換通常接受任意數量的 leading dimensions (..., C, H, W)，並且可以處理批次影像或批次影片。

Dtype 和預期數值範圍

tensor 影像的預期數值範圍由 tensor dtype 隱式定義。 float dtype 的 tensor 影像預期數值範圍為 [0, 1]。 integer dtype 的 tensor 影像預期數值範圍為 [0, MAX_DTYPE]，其中 MAX_DTYPE 是該 dtype 中可以表示的最大值。 通常，torch.uint8 dtype 的影像預期數值範圍為 [0, 255]。

使用 ToDtype 來轉換輸入的 dtype 和範圍。

V1 或 V2？我應該使用哪一個？

簡而言之，我們建議使用 torchvision.transforms.v2 中的轉換，而不是 torchvision.transforms 中的轉換。 它們更快，而且可以做更多的事情。 只要更改 import 即可。 展望未來，新的功能和改進只會考慮用於 v2 轉換。

在 Torchvision 0.15 (2023 年 3 月) 中，我們發布了一組新的轉換，這些轉換可在 torchvision.transforms.v2 命名空間中使用。 與 v1 版本 (torchvision.transforms 中) 相比，這些轉換具有許多優勢

這些轉換與 v1 版本完全向後相容，因此如果您已經在使用 torchvision.transforms 中的轉換，您需要做的就是將 import 更新為 torchvision.transforms.v2。 在輸出方面，由於實作差異，可能存在微不足道的差異。

效能考量

我們建議遵循以下準則，以獲得轉換的最佳效能

  • 依賴 torchvision.transforms.v2 中的 v2 轉換

  • 使用 tensors 而不是 PIL 影像

  • 使用 torch.uint8 dtype，尤其是在調整大小時

  • 使用 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]),
])

以上應該在典型的訓練環境中為您提供最佳效能，該環境依賴於具有 num_workers > 0 的 torch.utils.data.DataLoader。

轉換往往對輸入的 strides / 記憶體格式很敏感。 有些轉換在使用 channels-first 影像時會更快，而另一些轉換則更喜歡 channels-last。 像 torch 運算符一樣，大多數轉換會保留輸入的記憶體格式，但由於實作細節，這可能並不總是受到尊重。 如果您追求最佳效能，您可能需要進行一些實驗。 在單獨的轉換上使用 torch.compile() 也可能有助於分解記憶體格式變數 (例如，在 Normalize 上)。 請注意，我們談論的是記憶體格式，而不是 tensor shape。

請注意，諸如 Resize 和 RandomResizedCrop 之類的調整大小轉換通常更喜歡 channels-last 輸入，並且目前不會從 torch.compile() 中受益。

轉換類別、functions 和 kernels

轉換可以透過類別 (class) 的方式使用，例如 Resize，也可以透過函數 (functional) 的方式使用，例如 resize()，位於 torchvision.transforms.v2.functional 命名空間。這與 torch.nn 套件非常相似，該套件同時定義了類別和函數等效項目在 torch.nn.functional 中。

這些函數支援 PIL 圖像、純 tensors 或 TVTensors，例如 resize(image_tensor) 和 resize(boxes) 都是有效的。

注意

隨機轉換 (random transforms)，例如 RandomCrop，每次調用時都會隨機採樣一些參數。它們的函數對應項 (crop()) 不執行任何隨機採樣，因此具有略微不同的參數化。轉換類別的 get_params() 類別方法可用於在使用函數 API 時執行參數採樣。

torchvision.transforms.v2.functional 命名空間也包含我們稱之為「核心 (kernels)」的東西。這些是底層函數，用於實現特定類型的核心功能，例如 resize_bounding_boxes 或 `resized_crop_mask。它們是公開的，儘管沒有文件記錄。檢查 程式碼 以查看哪些可用（請注意，那些以底線開頭的不是公開的！）。如果您想要 bounding boxes 或 masks 等類型的 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()，您實際上會得到它的 (scripted) v1 等效項。由於 v1 和 v2 之間的實現差異，這可能會導致 scripted 和 eager 執行之間產生略微不同的結果。

如果您真的需要 v2 轉換的 torchscript 支援，我們建議 script torchvision.transforms.v2.functional 命名空間中的函數，以避免意外。

另請注意，這些函數僅支援純 tensors 的 torchscript，這些 tensors 始終被視為圖像。如果您需要 bounding boxes 或 masks 等其他類型的 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]（反之亦然）。請參閱 Dtype 和預期數值範圍。

ToPILImage([mode])

將 tensor 或 ndarray 轉換為 PIL Image

ToTensor()

將 PIL Image 或 ndarray 轉換為張量並相應地縮放值。

PILToTensor()

將 PIL Image 轉換為相同類型的 tensor - 此操作不會縮放數值。

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

以 [channels, height, width] 形式回傳影像的尺寸。

get_image_num_channels(img)

回傳影像的通道數量。

get_image_size(img)

以 [width, height] 形式回傳影像的大小。

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 轉換為相同類型的 tensor。

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

將 tensor 或 ndarray 轉換為 PIL Image。

to_tensor(pic)

將 PIL Image 或 numpy.ndarray 轉換為 tensor。

vflip(img)

垂直翻轉給定的圖片。

文件

存取 PyTorch 的全面開發者文件

檢視文件

教學

取得針對初學者和進階開發者的深入教學

檢視教學

資源

尋找開發資源並獲得您的問題解答

檢視資源

為了分析流量並優化您的體驗，我們在這個網站上使用 cookie。 點擊或瀏覽，即表示您同意允許我們使用 cookie。 作為本網站目前的維護者，Facebook 的 Cookie 政策適用。 了解更多，包括有關可用控件： Cookie 政策。