imgtools.core

Core math tools

  • Wavelet transform and its inverse transform.

  • Decomposition or matrix decomposition, such as PCA.

Documents

class imgtools.core.Wavelet(wavelet_name: str, device: device | str | None = None, dtype: dtype | None = None, normalize: bool = True)

Discrete Wavelet Object.

Attributes:
dec_len

Decomposition filter length.

device

The device of filters.

dtype

The data type of filters.

filter_bank

Returns filters tuple for the current wavelet in the following

rec_len

Reconstruction filter length.

s

The normalization factor.

Methods

dwt2(img[, mode])

Discrete wavelet transform of an image.

dwt2_hh(img[, mode])

Return the high-high component of the discrete wavelet transform.

dwt2_ll(img[, mode])

Return the low-low component of the discrete wavelet transform.

idwt2(img[, mode])

Discrete wavelet transform of an image.

to([device, dtype])

Applies torch.Tensor.to to decomposition and reconstruction filter valuess.
property dec_len: int

Decomposition filter length.

property device: device

The device of filters.

property dtype: dtype

The data type of filters.

dwt2(img: Tensor, mode: Literal['constant', 'reflect', 'replicate', 'circular'] = 'reflect') → Tensor

Discrete wavelet transform of an image.

Parameters:
imgtorch.Tensor

An image with shape (*, C, H, W).

mode{‘constant’, ‘reflect’, ‘replicate’, ‘circular’}, default=’reflect’

Padding mode. Same as the argument mode in torch.nn.functional.pad.

Returns:
torch.Tensor

Shape (*, C, 4, Ho, Wo), where Ho = (H + 1) // 2 and Wo = (W + 1) // 2. The wavelet decomposition components with the following order:

[LL, LH, HL, HH]

dwt2_hh(img: Tensor, mode: Literal['constant', 'reflect', 'replicate', 'circular'] = 'reflect') → Tensor

Return the high-high component of the discrete wavelet transform.

Parameters:
imgtorch.Tensor

An image with shape (*, C, H, W).

mode{‘constant’, ‘reflect’, ‘replicate’, ‘circular’}, default=’reflect’

Padding mode. Same as the argument mode in torch.nn.functional.pad.

Returns:
torch.Tensor

The high-high component of image. Shape (*, C, 4, Ho, Wo), where Ho = (H + 1) // 2 and Wo = (W + 1) // 2.

dwt2_ll(img: Tensor, mode: Literal['constant', 'reflect', 'replicate', 'circular'] = 'reflect') → Tensor

Return the low-low component of the discrete wavelet transform.

Parameters:
imgtorch.Tensor

An image with shape (*, C, H, W).

mode{‘constant’, ‘reflect’, ‘replicate’, ‘circular’}, default=’reflect’

Padding mode. Same as the argument mode in torch.nn.functional.pad.

Returns:
torch.Tensor

The low-low component of image. Shape (*, C, 4, Ho, Wo), where Ho = (H + 1) // 2 and Wo = (W + 1) // 2.

property filter_bank: tuple[Tensor, Tensor, Tensor, Tensor]

Returns filters tuple for the current wavelet in the following order:

(dec_lo, dec_hi, rec_lo, rec_hi)

idwt2(img: Tensor, mode: Literal['constant', 'reflect', 'replicate', 'circular'] = 'reflect') → Tensor

Discrete wavelet transform of an image.

Parameters:
imgtorch.Tensor

An image with shape (*, C, H, W).

mode{‘constant’, ‘reflect’, ‘replicate’, ‘circular’}, default=’reflect’

Padding mode. Same as the argument mode in torch.nn.functional.pad.

Returns:
torch.Tensor

The reconstructed image. Shape (*, C, 2*H, 2*W). Note that the val

property rec_len: int

Reconstruction filter length.

property s: float

The normalization factor.

to(device: device | str | int | None = None, dtype: dtype | None = None) → tuple[Tensor, Tensor, Tensor, Tensor]

Applies torch.Tensor.to to decomposition and reconstruction filter valuess. Returns the filter bank.

family_name: str

Wavelet family name.

short_family_name: str

Wavelet short family name.

name: str

Wavelet name.

orthogonal: bool

Whether the wavelet is orthogonal.

biorthogonal: bool

Whether the wavelet is biorthogonal.

symmetry: Literal['asymmetric', 'near symmetric', 'symmetric']

asymmetric, near symmetric, symmetric

dec_low: Tensor

Scaling coefficients of the decomposition filter.

dec_high: Tensor

Wavelet coefficients of the decomposition filter.

rec_low: Tensor

Scaling coefficients of the reconstruction filter.

rec_high: Tensor

Wavelet coefficients of the reconstruction filter.

imgtools.core.get_families(short: bool = False) → list[str]

Return a list of available discrete wavelet families.

Parameters:
shortbool, default=False

Use short name.

Returns:
list[str]

List of available wavelet families.

imgtools.core.get_wavelets(family: str | None = None) → list[str]

Return list of available discrete wavelet names for the given family name.

Parameters:
familystr | None, default=None

Short family name. If the family name is None (default), then all support wavelets are returned.

Returns:
list[str]

List of available wavelet names.

imgtools.core.pca(img: Tensor) → tuple[Tensor, Tensor]

Image PCA.

Parameters:
imgtorch.Tensor

Image with shape (*, C, H, W)

Returns:
Ltorch.Tensor

Eigenvalues in ascending order.

Vttorch.Tensor

Corresponding eigenvectors.

imgtools.core.calc_padding(ksize: tuple[int, int]) → tuple[int, int, int, int]

Calculate padding by a given ksize.

Parameters:
ksizetuple[int, int]

Kernel shape (y_direction, x_direction).

Returns:
tuple[int, int, int, int]

(padding_left, padding_right, padding_top, padding_bottom).

imgtools.core.deg_to_rad(deg: Tensor)

Convert the angle unit from degree to radian.

Parameters:
degtorch.Tensor

Degree values.

Returns:
torch.Tensor

Radian values.

imgtools.core.filter2d(img: Tensor, kernel: Tensor, padding: list[int] | str | None = 'same', mode: str = 'reflect') → Tensor

Image convolution with a 2D kernel.

Parameters:
imgtorch.Tensor

Image, a tensor with shape (*, C, H, W).

kerneltorch.Tensor

A convolution kernel with shape (k_x,), (k_y, k_x), (1 or k * C, k_y, k_x), or (B, k * C, k_y, k_x), where k is a positive integer.

paddinglist[int] | ‘same’ | None, default=’same’

The padding size.

  • list[int]: padding size: (left, right, top, bottom). See torch.nn.functional.pad.

  • ‘same’: computes from kernel size.

  • None: filter without pad.

mode{‘constant’, ‘reflect’, ‘replicate’, ‘circular’}, default=’reflect’

Padding mode. Same as the argument mode in torch.nn.functional.pad.

Returns:
torch.Tensor

The image with shape (*, C, H0, W0).

imgtools.core.matrix_transform(img: Tensor, matrix: Tensor) → Tensor

Converts the channels of an image by linear transformation.

Parameters:
imgtorch.Tensor

Image, a tensor with shape (*, C, H, W).

matrixtorch.Tensor

The transformation matrix with shape (*, C_out, C).

Returns:
torch.Tensor

The image with shape (*, C_out, H, W).

imgtools.core.rad_to_deg(deg: Tensor)

Convert the angle unit from radian to degree.

Parameters:
degtorch.Tensor

Radian values.

Returns:
torch.Tensor

Degree values.

imgtools.core.dwt2(img: Tensor, scaling: Tensor, wavelet: Tensor, mode: str = 'reflect') → Tensor

Performs discrete wavelet transform (DWT) of an image.

Parameters:
imgtorch.Tensor

An image with shape (*, C, H, W).

scalingtorch.Tensor

The scaling filter (father wavelet) with shape (K,).

wavelettorch.Tensor

The wavelet filter (mother wavelet) with shape (K,).

mode{‘constant’, ‘reflect’, ‘replicate’, ‘circular’}, default=’reflect’

Padding mode. Same as the argument mode in torch.nn.functional.pad.

Returns:
torch.Tensor

The DWT components of the image. Shape (*, C, 4, Ho, Wo), where Ho = (H + 1) // 2 and Wo = (W + 1) // 2. The components has the following order: [LL, LH, HL, HH], or equivalently, [cA, cV, cH, cD]

imgtools.core.dwt2_partial(img: Tensor, scaling: Tensor | None, wavelet: Tensor | None, target: str, mode: str = 'reflect') → Tensor

Returns a component of the discrete wavelet transform (DWT).

Parameters:
imgtorch.Tensor

An image with shape (*, C, H, W).

scalingtorch.Tensor | None

The scaling filter (father wavelet) with shape (K,).

wavelettorch.Tensor | None

The wavelet filter (mother wavelet) with shape (K,).

target{‘LL’, ‘LH’, ‘HL’, ‘HH’}

The component of discrete wavelet transform. The argument is case insensitive. The first letter represents the filter (lowpass/highpass) in x-direction.

mode{‘constant’, ‘reflect’, ‘replicate’, ‘circular’}, default=’reflect’

Padding mode. Same as the argument mode in torch.nn.functional.pad.

Returns:
torch.Tensor

The component of the DWT with shape (*, C, Ho, Wo), where Ho = (H + 1) // 2 and Wo = (W + 1) // 2.

imgtools.core.idwt2(img: Tensor, scaling: Tensor, wavelet: Tensor, mode: str = 'reflect') → Tensor

Performs inverse discrete wavelet transform (IDWT) of wavelet.

Parameters:
imgtorch.Tensor

An image with shape (*, C, 4, H, W).

scalingtorch.Tensor

The scaling filter (father wavelet) with shape (K,).

wavelettorch.Tensor

The wavelet filter (mother wavelet) with shape (K,).

mode{‘constant’, ‘reflect’, ‘replicate’, ‘circular’}, default=’reflect’

Padding mode. Same as the argument mode in torch.nn.functional.pad.

Returns:
torch.Tensor

The reconstructed image. Shape (*, C, 2*H, 2*W).

Notes

The value may not correctly recontructed at the boundary of the image.