torch.nn.functional.grid_sample

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

Дано input и поле потока grid, вычисляет output используя input значения и местоположения пикселей из grid.

В настоящее время поддерживаются только пространственные (4-мерные) и объёмные (5-мерные) input.

В пространственном (4-мерном) случае, для input с формой $(N, C, H_\text{in}, W_\text{in})$ и grid с формой $(N, H_\text{out}, W_\text{out}, 2)$, вывод будет иметь форму $(N, C, H_\text{out}, W_\text{out})$.

Для каждой выходной точки output[n, :, h, w], двумерный вектор grid[n, h, w] указывает input местоположения пикселей x и y, которые используются для интерполяции выходного значения output[n, :, h, w]. В случае 5D входных данных, grid[n, d, h, w] указывает x, y, z местоположения пикселей для интерполяции output[n, :, d, h, w]. Аргумент 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() для построения пространственных трансформерных сетей.

Примечание

При использовании графического процессора CUDA эта операция может вызывать непредсказуемое поведение в обратном проходе, которое трудно отключить. См. примечания по воспроизводимости для получения дополнительной информации.

Примечание

Значения NaN в grid будут интерпретироваться как -1.

Параметры:

• input (Tensor) – вход с формой $(N, C, H_\text{in}, W_\text{in})$ (4-мерный случай) или $(N, C, D_\text{in}, H_\text{in}, W_\text{in})$ (5-мерный случай)
• grid (Tensor) – поле потока с формой $(N, H_\text{out}, W_\text{out}, 2)$ (4-мерный случай) или $(N, D_\text{out}, H_\text{out}, W_\text{out}, 3)$ (5-мерный случай)
• mode (str) – режим интерполяции для вычисления выходных значений 'bilinear' | 'nearest' | 'bicubic'. По умолчанию: 'bilinear' Примечание: mode='bicubic' поддерживает только 4-мерный вход. Если mode='bilinear' и вход 5-мерный, внутренне используется режим интерполяции трилинейной. Но если вход 4-мерный, режим интерполяции — билинейный.
• padding_mode (str) – режим заполнения для значений сетки вне границ 'zeros' | 'border' | 'reflection'. По умолчанию: 'zeros'
• align_corners (bool, optional) – Геометрически, мы рассматриваем пиксели входа как квадраты, а не точки. Если установлено значение True, экстремумы (-1 и 1) рассматриваются как относящиеся к центральным точкам угловых пикселей входа. Если установлено значение False, они рассматриваются как относящиеся к угловым точкам угловых пикселей входа, что делает выборку более независимой от разрешения. Этот параметр аналогичен параметру align_corners в interpolate(), поэтому тот же параметр должен быть использован там для изменения размера входного изображения перед выбором по сетке. По умолчанию: 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. Используйте :func: torch.clamp для ограничения результатов, чтобы они находились в допустимом диапазоне.