torchimage.pooling package

Submodules

torchimage.pooling.gaussian module

class torchimage.pooling.gaussian.GaussianPoolNd(kernel_size, sigma, order=0, stride=None, *, same_padder=None)

Bases: torchimage.pooling.base.SeparablePoolNd

N-dimensional Gaussian Pooling

This module is implemented using separable pooling. Recall that Gaussian kernel is separable, i.e. An n-dimensional Gaussian kernel is the outer product of n 1D Gaussian kernels. N-dimensional Gaussian convolution is equivalent to sequentially applying n 1D Gaussian convolutions sequentially to each axis of interest. We can thus reduce the computational complexity from O(Nk^d) to O(Nkd), where N is the number of elements in the input tensor, k is kernel size, and d is the number of dimensions to convolve.

kernel_size: torchimage.utils.ndspec.NdSpec
stride: torchimage.utils.ndspec.NdSpec
torchimage.pooling.gaussian.gaussian_kernel_1d(kernel_size, sigma, order)

generate a 1-dimensional Gaussian kernel given kernel_size and sigma.

Multi-dimensional gaussian can be created by repeatedly obtaining outer products from 1-d Gaussian kernels. But when the application is Gaussian filtering (pooling) implemented through convolution, separable convolution is much more efficient.

This function uses the utility function from scipy.ndimage to generate gaussian kernels

Parameters

  • kernel_size (int) –

    length of the 1-d Gaussian kernel

    Please be aware that while even-length gaussian kernels can be generated, they are not well-defined and will cause a shift.

  • sigma (float) – standard deviation of Gaussian kernel

  • order (int) – An order of 0 corresponds to convolution with a Gaussian kernel. A positive order corresponds to convolution with that derivative of a Gaussian.

Returns

1-d Gaussian kernel of length kernel_size with standard deviation sigma

Return type

np.ndarray

torchimage.pooling.generic module

Module contents

We use pooling to refer to convolution-like operations that don’t have learnable parameters, such as average pooling and gaussian pooling.

In torchimage, what makes pooling different from filtering is that a filter layer usually consists of its pooling layer counterpart with stride 1, after a “same” padding layer that ensures the output and the input will have the same shape. We separate filtering and pooling so that users can have greater freedom and the code becomes easier to maintain.

class torchimage.pooling.AvgPoolNd(kernel_size, stride=None, *, count_include_pad=True, same_padder=None)

Bases: torchimage.pooling.base.SeparablePoolNd

forward(x: torch.Tensor, axes=slice(2, None, None))

Perform separable pooling on a tensor.

Parameters

  • x (torch.Tensor) – Input tensor.

  • axes (None, int, slice, tuple of int) –

    An ordered list of axes to be processed. Default: slice(2, None)

    Axes can be repeated. If None, it will be all the axes from axis 0 to the last axis.

    The default slice(2, None) assumes that the first 2 axes are batch (N) and channel (C) dimensions.

Returns

x – Output tensor after pooling

Return type

torch.Tensor

kernel_size: torchimage.utils.ndspec.NdSpec
stride: torchimage.utils.ndspec.NdSpec
class torchimage.pooling.BasePoolNd(*, same_padder=None)

Bases: torch.nn.modules.module.Module

abstract forward(x: torch.Tensor, axes)

Defines the computation performed at every call.

Should be overridden by all subclasses.

Note

Although the recipe for forward pass needs to be defined within this function, one should call the Module instance afterwards instead of this since the former takes care of running the registered hooks while the latter silently ignores them.

kernel_size: torchimage.utils.ndspec.NdSpec
pad(x: torch.Tensor, axes)

Use the bound same padder to pad the input tensor before performing actual convolution

Parameters

  • x (torch.Tensor) – Input tensor

  • axes (int, slice, tuple of int) – Axes to convolve (processed to be nonnegative integers)

Returns

x – padded tensor

Return type

torch.Tensor

read_stride(stride)

Read an input stride after self.kernel_size has been initialized.

If stride is None at any axis, it will be the same as kernel size.

This is a constant function (doesn’t modify self).

Parameters

stride (None, int, list, NdSpec) – Input stride

Returns

stride – Processed stride

Return type

NdSpec

stride: torchimage.utils.ndspec.NdSpec
to_filter(padder=None)

Modify this pooling module in-place, so that the stride is 1 and a same or valid padder is supplied.

In torchimage, filtering is a special subset of pooling that has stride=1 and (usually) same padding. (Considering that torch has not implemented a general method to perform dilated unfold on a tensor, dilation=1 is the default.)

Parameters

padder (None, str or Padder) – A same padder for this pooling module in the forward stage. A not-None padder will override self.same_padder. So if self.same_padder and padder are both None, valid padding will be used.

Returns

self – A modified self

Return type

SeparablePoolNd

class torchimage.pooling.GaussianPoolNd(kernel_size, sigma, order=0, stride=None, *, same_padder=None)

Bases: torchimage.pooling.base.SeparablePoolNd

N-dimensional Gaussian Pooling

This module is implemented using separable pooling. Recall that Gaussian kernel is separable, i.e. An n-dimensional Gaussian kernel is the outer product of n 1D Gaussian kernels. N-dimensional Gaussian convolution is equivalent to sequentially applying n 1D Gaussian convolutions sequentially to each axis of interest. We can thus reduce the computational complexity from O(Nk^d) to O(Nkd), where N is the number of elements in the input tensor, k is kernel size, and d is the number of dimensions to convolve.

kernel_size: torchimage.utils.ndspec.NdSpec
stride: torchimage.utils.ndspec.NdSpec
training: bool
class torchimage.pooling.SeparablePoolNd(kernel=(), stride=None, *, same_padder=None)

Bases: torchimage.pooling.base.BasePoolNd

forward(x: torch.Tensor, axes=slice(2, None, None))

Perform separable pooling on a tensor.

Parameters

  • x (torch.Tensor) – Input tensor.

  • axes (None, int, slice, tuple of int) –

    An ordered list of axes to be processed. Default: slice(2, None)

    Axes can be repeated. If None, it will be all the axes from axis 0 to the last axis.

    The default slice(2, None) assumes that the first 2 axes are batch (N) and channel (C) dimensions.

Returns

x – Output tensor after pooling

Return type

torch.Tensor

kernel_size: torchimage.utils.ndspec.NdSpec
stride: torchimage.utils.ndspec.NdSpec
training: bool