目錄
  • 文件 >
  • 轉換影像、影片、框等
快捷方式

轉換影像、影片、邊界框等

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 轉換的新手，還是已經熟練使用它們，我們都鼓勵您從 開始使用 v2 轉換 入手，以瞭解有關新 v2 轉換功能的更多資訊。

然後，瀏覽本頁面下方的各部分，獲取一般資訊和效能提示。可用的轉換和函式列在 API 參考 中。

更多資訊和教程也可以在我們的 示例庫 中找到，例如 Torchvision 轉換 v2：端到端目標檢測/分割示例 或 如何編寫自己的 v2 轉換。

支援的輸入型別和約定

大多數轉換都接受 PIL 影像和張量輸入。CPU 和 CUDA 張量都支援。兩種後端（PIL 或張量）的結果應該非常接近。一般來說，我們建議 為了效能 依賴張量後端。 轉換轉換 可用於在 PIL 影像之間轉換，或用於轉換資料型別和範圍。

張量影像的形狀應為 (C, H, W)，其中 C 是通道數，H 和 W 分別表示高度和寬度。大多數轉換都支援批次張量輸入。張量影像的批次是形狀為 (N, C, H, W) 的張量，其中 N 是批次中的影像數量。v2 轉換（v2）通常接受任意數量的前導維度 (..., C, H, W)，並且可以處理批次影像或批次影片。

資料型別和預期值範圍

張量影像值的預期範圍由張量資料型別隱式定義。具有浮點資料型別的張量影像應具有 [0, 1] 中的值。具有整數資料型別的張量影像應具有 [0, MAX_DTYPE] 中的值，其中 MAX_DTYPE 是該資料型別可表示的最大值。通常，資料型別為 torch.uint8 的影像應具有 [0, 255] 中的值。

使用 ToDtype 來轉換輸入的資料型別和範圍。

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 資料型別，尤其是在調整大小時

  • 使用雙線性或雙三次模式進行 resize

典型的轉換流水線可能如下所示：

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 這樣的 resize 轉換通常更喜歡通道最後的輸入，並且目前不會從 torch.compile() 中受益。

轉換類、函式和核心

轉換以類的形式提供，例如 Resize，也以函式的形式提供，例如 torchvision.transforms.v2.functional 名稱空間中的 resize()。這非常類似於 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()，您將實際上得到其（scripted）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])

在所有邊上用給定的“填充”值填充給定影像。

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

以給定的機率（預設為 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 中，我們實現了三個在以下資料集上學習到的策略：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)

以[通道數, 高度, 寬度]的格式返回影像的尺寸。

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 影像轉換為相同型別的張量。

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 Image。

to_tensor(pic)

將PIL Image或numpy.ndarray轉換為張量。

vflip(img)

垂直翻轉給定影像。

文件

訪問全面的 PyTorch 開發者文件

檢視文件

教程

為初學者和高階開發者提供深入的教程

檢視教程

資源

查詢開發資源並讓您的問題得到解答

檢視資源

為了分析流量並最佳化您的體驗，我們在此網站上使用 Cookie。點選或瀏覽即表示您同意我們使用 Cookie。作為本網站的當前維護者，Facebook 的 Cookie 政策適用。瞭解更多資訊，包括可用的控制元件： Cookie 政策。