piqa.utils.functional#

General purpose tensor functionals

Functions#

`channel_conv`	Returns the channel-wise convolution of \(x\) with the kernel `kernel`.
`channel_convs`	Returns the channel-wise convolution of \(x\) with the series of kernel `kernels`.
`downsample`	Downsamples \(x\) to a target resolution.
`filter_grid`	Returns the (quadrant-shifted) frequency grid for \(x\).
`gaussian_kernel`	Returns the 1-dimensional Gaussian kernel of size \(K\).
`gradient_kernel`	Returns `kernel` transformed into a gradient.
`haar_kernel`	Returns the horizontal Haar kernel.
`kernel_views`	Returns the \(N\)-dimensional views of the 1-dimensional kernel `kernel`.
`l2_norm`	Returns the \(L_2\) norm of \(x\).
`log_gabor`	Returns the log-Gabor filter of \(f\).
`prewitt_kernel`	Returns the Prewitt kernel.
`reduce_tensor`	Returns the reduction of \(x\).
`scharr_kernel`	Returns the Scharr kernel.
`sobel_kernel`	Returns the Sobel kernel.

Descriptions#

piqa.utils.functional.channel_conv(x, kernel, padding=0)#

Returns the channel-wise convolution of \(x\) with the kernel kernel.

Parameters:

x (Tensor) – A tensor, \((N, C, *)\).
kernel (Tensor) – A kernel, \((C', 1, *)\).
padding (int) – The implicit paddings on both sides of the input dimensions.

Example

>>> x = torch.arange(25).float().reshape(1, 1, 5, 5)
>>> x
tensor([[[[ 0.,  1.,  2.,  3.,  4.],
          [ 5.,  6.,  7.,  8.,  9.],
          [10., 11., 12., 13., 14.],
          [15., 16., 17., 18., 19.],
          [20., 21., 22., 23., 24.]]]])
>>> kernel = torch.ones((1, 1, 3, 3))
>>> channel_conv(x, kernel)
tensor([[[[ 54.,  63.,  72.],
          [ 99., 108., 117.],
          [144., 153., 162.]]]])

piqa.utils.functional.channel_convs(x, kernels, padding=0)#

Returns the channel-wise convolution of \(x\) with the series of kernel kernels.

Parameters:

x (Tensor) – A tensor, \((N, C, *)\).
kernels (List[Tensor]) – A list of kernels, each \((C', 1, *)\).
padding (int) – The implicit paddings on both sides of the input dimensions.

Example

>>> x = torch.arange(25).float().reshape(1, 1, 5, 5)
>>> x
tensor([[[[ 0.,  1.,  2.,  3.,  4.],
          [ 5.,  6.,  7.,  8.,  9.],
          [10., 11., 12., 13., 14.],
          [15., 16., 17., 18., 19.],
          [20., 21., 22., 23., 24.]]]])
>>> kernels = [torch.ones((1, 1, 3, 1)), torch.ones((1, 1, 1, 3))]
>>> channel_convs(x, kernels)
tensor([[[[ 54.,  63.,  72.],
          [ 99., 108., 117.],
          [144., 153., 162.]]]])

piqa.utils.functional.gaussian_kernel(size, sigma=1.0)#

Returns the 1-dimensional Gaussian kernel of size \(K\).

\[G(x) = \gamma \exp \left(\frac{(x - \mu)^2}{2 \sigma^2}\right)\]

where \(\gamma\) is such that

\[\sum_{x = 1}^{K} G(x) = 1\]

and \(\mu = \frac{1 + K}{2}\).

Wikipedia

https://wikipedia.org/wiki/Gaussian_blur

Note

An \(N\)-dimensional Gaussian kernel is separable, meaning that applying it is equivalent to applying a series of \(N\) 1-dimensional Gaussian kernels, which has a lower computational complexity.

Parameters:

size (int) – The kernel size \(K\).
sigma (float) – The standard deviation \(\sigma\) of the distribution.

Returns:

The kernel vector, \((K,)\).

Return type:

Tensor

Example

>>> gaussian_kernel(5, sigma=1.5)
tensor([0.1201, 0.2339, 0.2921, 0.2339, 0.1201])

piqa.utils.functional.kernel_views(kernel, n=2)#

Returns the \(N\)-dimensional views of the 1-dimensional kernel kernel.

Parameters:

kernel (Tensor) – A kernel, \((C, 1, K)\).
n (int) – The number of dimensions \(N\).

Returns:

The list of views, each \((C, 1, \underbrace{1, \dots, 1}_{i}, K, \underbrace{1, \dots, 1}_{N - i - 1})\).

Return type:

List[Tensor]

Example

>>> kernel = gaussian_kernel(5, sigma=1.5).repeat(3, 1, 1)
>>> kernel.shape
torch.Size([3, 1, 5])
>>> views = kernel_views(kernel, n=2)
>>> views[0].shape, views[1].shape
(torch.Size([3, 1, 5, 1]), torch.Size([3, 1, 1, 5]))

piqa.utils.functional.haar_kernel(size)#

Returns the horizontal Haar kernel.

Wikipedia

https://wikipedia.org/wiki/Haar_wavelet

Parameters:: size (int) – The kernel (even) size \(K\).
Returns:: The kernel, \((K, K)\).
Return type:: Tensor

Example

>>> haar_kernel(2)
tensor([[ 0.5000, -0.5000],
        [ 0.5000, -0.5000]])

piqa.utils.functional.prewitt_kernel()#

Returns the Prewitt kernel.

Wikipedia

https://wikipedia.org/wiki/Prewitt_operator

Returns:: The kernel, \((3, 3)\).
Return type:: Tensor

Example

>>> prewitt_kernel()
tensor([[ 0.3333,  0.0000, -0.3333],
        [ 0.3333,  0.0000, -0.3333],
        [ 0.3333,  0.0000, -0.3333]])

piqa.utils.functional.sobel_kernel()#

Returns the Sobel kernel.

Wikipedia

https://wikipedia.org/wiki/Sobel_operator

Returns:: The kernel, \((3, 3)\).
Return type:: Tensor

Example

>>> sobel_kernel()
tensor([[ 0.2500,  0.0000, -0.2500],
        [ 0.5000,  0.0000, -0.5000],
        [ 0.2500,  0.0000, -0.2500]])

piqa.utils.functional.scharr_kernel()#

Returns the Scharr kernel.

Wikipedia

https://wikipedia.org/wiki/Scharr_operator

Returns:: The kernel, \((3, 3)\).
Return type:: Tensor

Example

>>> scharr_kernel()
tensor([[ 0.1875,  0.0000, -0.1875],
        [ 0.6250,  0.0000, -0.6250],
        [ 0.1875,  0.0000, -0.1875]])

piqa.utils.functional.gradient_kernel(kernel)#

Returns kernel transformed into a gradient.

Parameters:: kernel (Tensor) – A convolution kernel, \((K, K)\).
Returns:: The gradient kernel, \((2, 1, K, K)\).
Return type:: Tensor

Example

>>> g = gradient_kernel(prewitt_kernel())
>>> g.shape
torch.Size([2, 1, 3, 3])

piqa.utils.functional.filter_grid(x)#

Returns the (quadrant-shifted) frequency grid for \(x\).

Parameters:: x (Tensor) – A tensor, \((*, H, W)\).
Returns:: The radius and phase tensors, both \((H, W)\).
Return type:: Tuple[Tensor, Tensor]

Example

>>> x = torch.rand(5, 5)
>>> r, phi = filter_grid(x)
>>> r
tensor([[0.0000, 0.2500, 0.5000, 0.5000, 0.2500],
        [0.2500, 0.3536, 0.5590, 0.5590, 0.3536],
        [0.5000, 0.5590, 0.7071, 0.7071, 0.5590],
        [0.5000, 0.5590, 0.7071, 0.7071, 0.5590],
        [0.2500, 0.3536, 0.5590, 0.5590, 0.3536]])
>>> phi
tensor([[-0.0000, -1.5708, -1.5708,  1.5708,  1.5708],
        [-0.0000, -0.7854, -1.1071,  1.1071,  0.7854],
        [-0.0000, -0.4636, -0.7854,  0.7854,  0.4636],
        [-3.1416, -2.6779, -2.3562,  2.3562,  2.6779],
        [-3.1416, -2.3562, -2.0344,  2.0344,  2.3562]])

piqa.utils.functional.log_gabor(f, f_0, sigma_f)#

Returns the log-Gabor filter of \(f\).

\[G(f) = \exp \left( - \frac{\log(f / f_0)^2}{2 \sigma_f^2} \right)\]

Wikipedia

https://wikipedia.org/wiki/Log_Gabor_filter

Parameters:

f (Tensor) – A frequency tensor, \((*,)\).
f_0 (float) – The center frequency \(f_0\).
sigma_f (float) – The bandwidth (log-)deviation \(\sigma_f\).

Returns:

The filter tensor, \((*,)\).

Return type:

Tensor

Example

>>> x = torch.rand(5, 5)
>>> r, phi = filter_grid(x)
>>> log_gabor(r, 1.0, 1.0)
tensor([[0.0000, 0.3825, 0.7864, 0.7864, 0.3825],
        [0.3825, 0.5825, 0.8444, 0.8444, 0.5825],
        [0.7864, 0.8444, 0.9417, 0.9417, 0.8444],
        [0.7864, 0.8444, 0.9417, 0.9417, 0.8444],
        [0.3825, 0.5825, 0.8444, 0.8444, 0.5825]])

piqa.utils.functional.l2_norm(x, dim, keepdim=False)#

Returns the \(L_2\) norm of \(x\).

Wikipedia

https://wikipedia.org/wiki/Norm_(mathematics)

Parameters:

x (Tensor) – A tensor, \((*,)\).
dim (int) – The dimension along which to calculate the norm.
keepdim (bool) – Whether the output tensor has dim retained or not.

Example

>>> x = torch.arange(9).float().reshape(3, 3)
>>> x
tensor([[0., 1., 2.],
        [3., 4., 5.],
        [6., 7., 8.]])
>>> l2_norm(x, dim=0)
tensor([6.7082, 8.1240, 9.6437])

piqa.utils.functional.downsample(x, resolution=256)#

Downsamples \(x\) to a target resolution.

Parameters:

x (Tensor) – A tensor, \((N, C, H, W)\).
resolution (int) – The target resolution \(R\).

Returns:

math:f = lfloor frac{min(H, W)}{R} rfloor.

Return type:

The downsampled tensor, \((N, C, H / f, W / f)\) where

Example

>>> x = torch.rand(5, 3, 1920, 1080)
>>> x = downsample(x, resolution=256)
>>> x.shape
torch.Size([5, 3, 480, 270])

piqa.utils.functional.reduce_tensor(x, reduction='mean')#

Returns the reduction of \(x\).

Parameters:

x (Tensor) – A tensor, \((*,)\).
reduction (str) – Specifies the reduction type: 'none', 'mean' or 'sum'.

Example

>>> x = torch.arange(5)
>>> reduce_tensor(x, reduction='sum')
tensor(10)