torch.nn.functional.grid_sample

torch.nn.functional.grid_sample(input, grid, mode='bilinear', padding_mode='zeros', align_corners=None) [исходный код]

Выполняет выборку по сетке.

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

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

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

Примечание

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

Примечание

Значения NaN в grid интерпретируются как -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, они считаются координатами угловых точек угловых пикселей входных данных, благодаря чему выборка становится менее зависимой от разрешения. Эта опция соответствует опции align_corners в interpolate(), поэтому при изменении размера входного изображения перед выборкой по сетке здесь следует использовать то же значение. По умолчанию: 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().