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。

對於形狀為 $(N, C, H_\text{in}, W_\text{in})$ 的空間 (4-D) 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 後端時，此操作的後向傳播可能會引起不確定的行為，且不易關閉。請參閱 Reproducibility（可復現性）部分的說明以瞭解背景資訊。

注意

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, optional) – 在幾何上，我們將輸入畫素視為方形而非點。如果設定為 True，則極限值（-1 和 1）被視為指向輸入角畫素的中心點。如果設定為 False，則它們被視為指向輸入角畫素的角點，使取樣更具解析度無關性。此選項平行於 interpolate() 中的 align_corners 選項，因此在此處使用的任何選項都應該在調整輸入影像大小以進行網格取樣時一併使用。預設值：False

返回

輸出 Tensor

返回型別

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() 夾緊結果，以確保它們在有效範圍內。