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], вектор размером 2 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

Тип возвращаемого значения

выход (Tensor)

Предупреждение

При align_corners = True, позиции сетки зависят от размера пикселя относительно размера входного изображения, и поэтому места, выбранные с помощью grid_sample(), будут отличаться для одного и того же входа при разных разрешениях (то есть после масштабирования вверх или вниз). По умолчанию до версии 1.2.0 было align_corners = True. С тех пор поведение по умолчанию было изменено на align_corners = False, для соответствия по умолчанию interpolate().

Примечание

mode='bicubic' реализовано с использованием алгоритма кубической интерполяции по методу кубической свёртки (cubic convolution) с $\alpha=-0.75$. Константа $\alpha$ может отличаться в разных пакетах. Например, в PIL и OpenCV она равна -0.5 и -0.75 соответственно. Этот алгоритм может «пересекать» диапазон интерполируемых значений. Например, при интерполяции входных значений в диапазоне [0, 255] он может генерировать отрицательные значения или значения, превышающие 255. Используйте torch.clamp() для ограничения результатов в допустимом диапазоне.