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
- 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¶