torch.nn.functional.grid_sample

torch.nn.functional.grid_sample(input, grid, mode='bilinear', padding_mode='zeros', align_corners=None)

計算網格取樣。

給定 input 和流場 grid，使用 input 的值和 grid 中的畫素位置計算 output。

目前，僅支援空間 (4-D) 和體資料 (5-D) 的 input。

在空間 (4-D) 情況下，對於形狀為 $(N, C, H_\text{in}, W_\text{in})$ 的 input 和形狀為 $(N, H_\text{out}, W_\text{out}, 2)$ 的 grid，輸出的形狀將是 $(N, C, H_\text{out}, W_\text{out})$。

對於每個輸出位置 output[n, :, h, w]，大小為 2 的向量 grid[n, h, w] 指定了 input 的畫素位置 x 和 y，這些位置用於插值計算輸出值 output[n, :, h, w]。對於 5D 輸入，grid[n, d, h, w] 指定了用於插值計算 output[n, :, d, h, w] 的畫素位置 x、y 和 z。引數 mode 指定了用於取樣輸入畫素的 nearest 或 bilinear 插值方法。

grid 指定了按 input 空間維度歸一化的取樣畫素位置。因此，其大多數值應在 [-1, 1] 範圍內。例如，值 x = -1, y = -1 表示 input 的左上角畫素，而值 x = 1, y = 1 表示 input 的右下角畫素。

如果 grid 的值超出 [-1, 1] 範圍，則根據 padding_mode 的定義處理相應的輸出。選項包括

• padding_mode="zeros": 對超出邊界的網格位置使用 0，

• padding_mode="border": 對超出邊界的網格位置使用邊界值，

• padding_mode="reflection": 對超出邊界的網格位置使用邊界反射的位置的值。對於遠離邊界的位置，它會不斷反射直到進入邊界內，例如，(歸一化) 畫素位置 x = -3.5 經過邊界 -1 反射後變為 x' = 1.5，然後經過邊界 1 反射後變為 x'' = -0.5。

注意

此函式通常與 affine_grid() 結合使用，用於構建空間變換網路 (Spatial Transformer Networks) 。

注意

使用 CUDA 後端時，此操作在其反向傳播過程中可能會導致不易關閉的非確定性行為。有關背景資訊，請參閱可復現性 須知。

注意

grid 中的 NaN 值將被解釋為 -1。

引數

• input (Tensor) – 形狀為 $(N, C, H_\text{in}, W_\text{in})$ (4-D 情況) 或 $(N, C, D_\text{in}, H_\text{in}, W_\text{in})$ (5-D 情況) 的輸入

• grid (Tensor) – 形狀為 $(N, H_\text{out}, W_\text{out}, 2)$ (4-D 情況) 或 $(N, D_\text{out}, H_\text{out}, W_\text{out}, 3)$ (5-D 情況) 的流場

• mode (str) – 用於計算輸出值的插值模式：'bilinear' | 'nearest' | 'bicubic'。預設值：'bilinear' 注意：mode='bicubic' 僅支援 4-D 輸入。當 mode='bilinear' 且輸入為 5-D 時，內部使用的插值模式實際上是三線性插值。然而，當輸入為 4-D 時，插值模式才是真正的雙線性插值。

• padding_mode (str) – 超出網格範圍值的填充模式：'zeros' | 'border' | 'reflection'。預設值：'zeros'

• align_corners (bool, 可選) – 在幾何上，我們將輸入的畫素視為正方形而不是點。如果設定為 True，極值（-1 和 1）被視為指向輸入角畫素的中心點。如果設定為 False，它們則被視為指向輸入角畫素的頂點，這使得采樣與解析度更無關。此選項與 interpolate() 中的 align_corners 選項類似，因此在此處使用的選項也應在進行網格取樣之前調整輸入影像大小時使用。預設值：False

返回值

輸出張量

返回型別

output (Tensor)

警告

當 align_corners = True 時，網格位置取決於畫素大小相對於輸入影像大小的比例，因此對於不同解析度（即經過上取樣或下采樣後）的相同輸入，grid_sample() 取樣的位置將不同。直到 1.2.0 版本，預設行為是 align_corners = True。自那以後，預設行為已更改為 align_corners = False，以便與 interpolate() 的預設行為保持一致。

注意

mode='bicubic' 使用三次卷積演算法實現，其中 $\alpha=-0.75$。常數 $\alpha$ 在不同軟體包中可能有所不同。例如，PIL 和 OpenCV 分別使用 -0.5 和 -0.75。此演算法可能會“超出”插值範圍。例如，在對 [0, 255] 範圍內的輸入進行插值時，它可能會產生負值或大於 255 的值。使用 torch.clamp() 限制結果範圍，確保它們在有效範圍內。