`imgtools.filters`

Basic spatial and frequency domain filters.

Spatial domain filters
- Edge: Laplacian, Sobel, Kirsch, etc.
- Blurring filters: box blur, Gaussian, guided filter
Frequency domain filters: based on rfft2
- Laplacian
- Gaussian highpass/lowpass
- Butterworthhighpass/lowpass.

Links

_edges

`gradient_magnitude`	Computes the magnitude of the gradients: norm(gradients)
`kirsch`	Edge detection by the Kirsch compass operators.
`laplacian`	Computes the laplacian of an image.
`prewitt`	Edge detection by the Prewitt operators.
`robinson`	Edge detection by the Robinson compass operators.
`scharr`	Edge detection by the Scharr operators.
`sobel`	Edge detection by the Sobel operators.

Blur

`box_blur`	Blurs an image with box kernel (filled with the same value).
`gaussian_blur`	Blurs an image with a gaussian kernel.
`get_gaussian_kernel`	Create a 2D Gaussian kernel.
`guided_filter`	Guided image filter, an edge-preserving smoothing filter [1].

Rfft

`get_butterworth_highpass`	Create a 2D Butterworth highpass filter for rfft image.
`get_butterworth_lowpass`	Create a 2D Butterworth lowpass filter for rfft image.
`get_freq_laplacian`	Create a frequency domain Laplacian filter for rfft image.
`get_gaussian_highpass`	Create a 2D Gaussian highpass filter for rfft image.
`get_gaussian_lowpass`	Create a 2D Gaussian lowpass filter for rfft image.

Documents

imgtools.filters.gradient_magnitude(grad_y: Tensor, grad_x: Tensor, magnitude: str | int | float = 2) → Tensor

Computes the magnitude of the gradients: norm(gradients)

Parameters:

grad_y

The derivatives with respect to y of an image. Shape (*, C, H, W).

grad_x

The derivatives with respect to x of an image. Shape (*, C, H, W).

magnitude{‘stack’, ‘inf’, ‘-inf’} | int | float, default=2

The strategy of magnitude computation.

‘stack’ : Stack derivatives.
‘inf’ : Take the maximum alone all derivatives.
‘-inf’ : Take the minimum alone all derivatives.
int or float : Apply p-norm to the derivatives if p > 0.

Returns:

torch.Tensor: The magnitude of gradient. The shape is (*, C, H, W) if magnitude is NOT ‘stack’; and is (2, *, C, H, W) if magnitude is ‘stack’.

Raises:

ValueError: When magnitude <= 0.
TypeError: When the magnitude != ‘stack’ and magnitude cant not be converted to a number.

Examples

>>> from imgtools.filters import gradient_magnitude
>>>
>>> grad_y = torch.rand(3, 512, 512)
>>> grad_x = torch.rand(3, 512, 512)
>>>
>>> mag = gradient_magnitude(grad_y, grad_x)
>>> mag.shape  # (3, 512, 512)
>>>
>>> mag = gradient_magnitude(grad_y, grad_x, 'stack')
>>> mag.shape  # (2, 3, 512, 512)

imgtools.filters.kirsch(img: Tensor, ret_angle: bool = False, angle_unit: str = 'deg') → Tensor | tuple[Tensor, Tensor]

Edge detection by the Kirsch compass operators.

Parameters:

imgtorch.Tensor: An image with shape (*, C, H, W).
ret_anglebool, default=False: Returns the direction of gradient or not.
angle_unit{‘rad’, ‘deg’}, default=’deg’: The representation of angle is in radian or in degree.

Returns:

magtorch.Tensor: Image gradient’s magnitude. The value is the maximum along all compass kernel.
angletorch.Tensor: Image gradient’s direction with shape (*, C, H, W). angle is returned only if ret_angle is true.

imgtools.filters.laplacian(img: Tensor, diagonal: bool = False, inflection_only: bool = False) → Tensor

Computes the laplacian of an image.

Parameters:

imgtorch.Tensor: Image with shape (*, C, H, W).
diagonalbool, default=False: The kernel detects 45 degree and 135 degree.
inflection_onlybool, default=False: Set non-inflection points to 0. A inflection point means that the sign of laplacian changes near the point.

Returns:

torch.Tensor: The laplacian of an image with shape (*, C, H, W).

Examples

>>> from imgtools.filters import laplacian
>>>
>>> img = torch.rand(3, 512, 512)
>>> grad = laplacian(img)

imgtools.filters.prewitt(img: Tensor, magnitude: str | int | float = 2, ret_angle: bool = False, angle_unit: str = 'deg') → Tensor | tuple[Tensor, Tensor]

Edge detection by the Prewitt operators.

Parameters:

imgtorch.Tensor: An image with shape (*, C, H, W).
magnitude{‘stack’, ‘inf’, ‘-inf’} | int | float, default=2: Norm for computing gradient’s magnitude.
ret_anglebool, default=False: Returns the direction of gradient or not.
angle_unit{‘rad’, ‘deg’}, default=’deg’: The representation of angle is in radian or in degree.

Returns:

magtorch.Tensor: Image gradient’s magnitude.The magnitude stacks (y-direction, x-direction) if magnitude is ‘stack’.For details, check torch_imagetools.filters.gradient_magnitude.
angletorch.Tensor: Image gradient’s direction with shape (*, C, H, W). angle is returned only if ret_angle is true.

imgtools.filters.robinson(img: Tensor, ret_angle: bool = False, angle_unit: str = 'deg') → Tensor | tuple[Tensor, Tensor]

Edge detection by the Robinson compass operators.

Parameters:

imgtorch.Tensor: An image with shape (*, C, H, W).
ret_anglebool, default=False: Returns the direction of gradient or not.
angle_unit{‘rad’, ‘deg’}, default=’deg’: The representation of angle is in radian or in degree.

Returns:

magtorch.Tensor: Image gradient’s magnitude. The value is the maximum along all compass kernel.
angletorch.Tensor: Image gradient’s direction with shape (*, C, H, W). angle is returned only if ret_angle is true.

imgtools.filters.scharr(img: Tensor, magnitude: str | int | float = 2, ret_angle: bool = False, angle_unit: str = 'deg') → Tensor | tuple[Tensor, Tensor]

Edge detection by the Scharr operators.

Parameters:

imgtorch.Tensor: An image with shape (*, C, H, W).
magnitude{‘stack’, ‘inf’, ‘-inf’} | int | float, default=2: Norm for computing gradient’s magnitude.
ret_anglebool, default=False: Returns the direction of gradient or not.
angle_unit{‘rad’, ‘deg’}, default=’deg’: The representation of angle is in radian or in degree.

Returns:

magtorch.Tensor: Image gradient’s magnitude.The magnitude stacks (y-direction, x-direction) if magnitude is ‘stack’.For details, check torch_imagetools.filters.gradient_magnitude.
angletorch.Tensor: Image gradient’s direction with shape (*, C, H, W). angle is returned only if ret_angle is true.

imgtools.filters.sobel(img: Tensor, magnitude: str | int | float = 2, ret_angle: bool = False, angle_unit: str = 'deg') → Tensor | tuple[Tensor, Tensor]

Edge detection by the Sobel operators.

Parameters:

imgtorch.Tensor: An image with shape (*, C, H, W).
magnitude{‘stack’, ‘inf’, ‘-inf’} | int | float, default=2: Stratge for computing gradient’s magnitude.
ret_anglebool, default=False: Returns the direction of gradient or not.
angle_unit{‘rad’, ‘deg’}, default=’deg’: The representation of angle is in radian or in degree.

Returns:

magtorch.Tensor: Image gradient’s magnitude.The magnitude stacks (y-direction, x-direction) if magnitude is ‘stack’.For details, check torch_imagetools.filters.gradient_magnitude.
angletorch.Tensor: Image gradient’s direction with shape (*, C, H, W). angle is returned only if ret_angle is true.

imgtools.filters.box_blur(img: Tensor, ksize: int | tuple[int, int] = 3, normalize: bool = True) → Tensor

Blurs an image with box kernel (filled with the same value). Computes local mean if normalize is True; local sum if normalize is False.

Parameters:

imgtorch.Tensor: Image with shape (*, C, H, W).
ksizeint | tuple[int, int], default=3: Kernel size. Must be a positive integer or a sequence of positive integers.
normalizebool, default=True: Normalize the kernel to sum(kernel) == 1.

Returns:

torch.Tensor: Blurred image with the same shape as input.

imgtools.filters.gaussian_blur(img: Tensor, ksize: int | tuple[int, int] = 3, sigma: float | tuple[float, float] = 0.0) → Tensor

Blurs an image with a gaussian kernel.

Parameters:

imgtorch.Tensor: Image with shape (*, C, H, W).
ksizeint | tuple[int, int], default=5: Kernel size. If ksize is non-positive, the value will be computed from sigma: ksize = odd(6 * sigma + 1), where odd() returns the closest odd integer.
sigmafloat | tuple[float, float], default=0.0: The width of gaussian function. If sigma is non-positive, the value will be computed from ksize: sigma = 0.3 * ((ksize - 1) * 0.5 - 1) + 0.8

Returns:

torch.Tensor: Blurred image with the same shape as input.

imgtools.filters.get_gaussian_kernel(ksize: int | tuple[int, int] = 5, sigma: float | tuple[float, float] = 0.0, normalize: bool = True) → Tensor

Create a 2D Gaussian kernel.

Parameters:

ksizeint | tuple[int, int], default=5: Kernel size. If ksize is non-positive, the value will be computed from sigma_s: ksize = odd(max(6 * sigma_s / downsample + 1, 3)), where odd(x) returns the smallest odd integer such that odd(x) >= x.
sigmafloat | tuple[float, float], default=0.0: The width of gaussian function. If sigma is non-positive, the value will be computed from ksize: sigma = 0.3 * ((ksize - 1) * 0.5 - 1) + 0.8
normalizebool, default=True: Normalize the summation of the kernel to 1.0.

Returns:

torch.Tensor: 2D Gaussian kernel with given ksize.

imgtools.filters.guided_filter(img: Tensor, guidance: Tensor | None = None, ksize: int | tuple[int, int] = 5, eps: float = 0.01)

Guided image filter, an edge-preserving smoothing filter [1].

Parameters:

imgtorch.Tensor: An image with shape (*, C, H, W).
guidancetorch.Tensor | None, default=None: Guidance image with shape (*, C, H, W). If guidance is None, then img will be regard as guidance.
ksizeint | tuple[int, int], default=5: Kernel size.
epsfloat, optional: Regularization parameter. A larger value means the output is more smoothing.

Returns:

torch.Tensor: Smooth image with shape (*, C, H, W).

References

[1] He, Kaiming; Sun, Jian; Tang, Xiaoou (2013).: “Guided Image Filtering”. IEEE Transactions on Pattern Analysis and Machine Intelligence. 35 (6): 1397-1409. doi:10.1109/TPAMI.2012.213.

imgtools.filters.get_butterworth_highpass(img_size: int | tuple[int, int] | Tensor, cutoff: float, order: float = 1.0, d: float | None = None, dtype: dtype = None, device: device = None) → Tensor

Create a 2D Butterworth highpass filter for rfft image.

Parameters:

img_sizeint | tuple[int, int] | torch.Tensor: The size of rfft image. Shape (size_y, size_x). Or, the rfft image with shape (…, H, W).
cutofffloat: The cutoff frequency of Butterworth filter.
orderfloat, default=1.0: The order of Butterworth filter.
dfloat | None, default=None: The sampling length scale. If None, uses 1 / img_size. For details, see torch.fft.fftfreq and torch.fft.rfftfreq.
dtypetorch.dtype, default=None: The Data type of the filter.
devicetorch.device, default=None: The Device of the returned filter.

Returns:

torch.Tensor: 2D Butterworth highpass filter.

Examples

>>> img_f = torch.fft.rfft2(img)
>>> highpass = get_butterworth_highpass(img_f, 10)
>>> edge_f = img_f * highpass
>>> edge = torch.fft.irfft2(edge_f)

imgtools.filters.get_butterworth_lowpass(img_size: int | tuple[int, int] | Tensor, cutoff: float, order: float = 1.0, d: float | None = None, dtype: dtype = None, device: device = None) → Tensor

Create a 2D Butterworth lowpass filter for rfft image.

Parameters:

img_sizeint | tuple[int, int] | torch.Tensor: The size of rfft image. Shape (size_y, size_x). Or, the rfft image with shape (…, H, W).
cutofffloat: The cutoff frequency of Butterworth filter.
orderfloat, default=1.0: The order of Butterworth filter.
dfloat | None, default=None: The sampling length scale. If None, uses 1 / img_size. For details, see torch.fft.fftfreq and torch.fft.rfftfreq.
dtypetorch.dtype, default=None: The Data type of the filter.
devicetorch.device, default=None: The Device of the returned filter.

Returns:

torch.Tensor: 2D Butterworth lowpass filter.

Examples

>>> img_f = torch.fft.rfft2(img)
>>> lowpass = get_butterworth_lowpass(img_f, 10)
>>> blurred_f = img_f * lowpass
>>> blurred = torch.fft.irfft2(blurred_f)

imgtools.filters.get_freq_laplacian(img_size: int | tuple[int, int] | Tensor, form: Literal['continuous', '4-neighbor', '8-neighbor'] = 'continuous', d: float | None = 1.0, dtype: dtype = None, device: device = None) → Tensor

Create a frequency domain Laplacian filter for rfft image.

Parameters:

img_sizeint | tuple[int, int] | torch.Tensor

The size of rfft image. Shape [size_y, size_x].

form{‘continuous’, ‘4-neighbor’}, default=’continuous’

The form of approximation of discrete Laplacian filter in frequency domain.

‘continuous’: Discretize the Fourier transform of the continuous

Laplacian operator. Better - ‘4-neighbor’: Computes the Fourier transform of the discrete 4-neighbor Laplacian operator. This can be used to solve the PDE. - ‘8-neighbor’: Computes the Fourier transform of the discrete 8-neighbor Laplacian operator.

dfloat | None, default=1.0

The sampling length scale. If None, uses 1 / img_size. For details, see torch.fft.fftfreq and torch.fft.rfftfreq.

dtypetorch.dtype, default=None

The Data type of the filter.

devicetorch.device, default=None

The Device of the returned filter.

Returns:

torch.Tensor: 2D Laplacian filter.

Notes

The results of 4-neighbor and 8-neighbor (in frequency domain) are similar to the result by using the convolution. Theese options are present for solving PDE in the frequency domain.

Examples

>>> img_f = torch.fft.rfft2(img)
>>> highpass = get_freq_laplacian(img_f, 10)
>>> edge_f = img_f * highpass
>>> edge = torch.fft.irfft2(edge_f)

imgtools.filters.get_gaussian_highpass(img_size: int | tuple[int, int] | Tensor, sigma: float | tuple[float, float], d: float | None = None, scale: bool = False, dtype: dtype = None, device: device = None) → Tensor

Create a 2D Gaussian highpass filter for rfft image.

Parameters:

img_sizeint | tuple[int, int] | torch.Tensor: The size of rfft image. Shape (size_y, size_x). Or, the rfft image with shape (…, H, W).
sigmafloat | tuple[float, float]: The width of Gaussian function. Shape [sigma_y, sigma_x].
dfloat | None, default=None: The sampling length scale. If None, uses 1 / img_size. For details, see torch.fft.fftfreq and torch.fft.rfftfreq.
scalebool, default=False: Scale the filter by 1 / (2 * torch.pi * ).
dtypetorch.dtype, default=None: The Data type of the filter.
devicetorch.device, default=None: The Device of the returned filter.

Returns:

torch.Tensor: 2D Gaussian highpass filter.

Examples

>>> img_f = torch.fft.rfft2(img)
>>> highpass = get_gaussian_highpass(img_f, 2)
>>> edge_f = img_f * highpass
>>> edge = torch.fft.irfft2(edge_f)

imgtools.filters.get_gaussian_lowpass(img_size: int | tuple[int, int] | Tensor, sigma: float | tuple[float, float], d: float | None = None, scale: bool = False, dtype: dtype = None, device: device = None) → Tensor

Create a 2D Gaussian lowpass filter for rfft image.

Parameters:

img_sizeint | tuple[int, int] | torch.Tensor: The size of rfft image. Shape (size_y, size_x). Or, the rfft image with shape (…, H, W).
sigmafloat | tuple[float, float]: The width of Gaussian function. Shape [sigma_y, sigma_x].
dfloat | None, default=None: The sampling length scale. If None, uses 1 / img_size. For details, see torch.fft.fftfreq and torch.fft.rfftfreq.
scalebool, default=False: Scale the filter by 1 / (2 * torch.pi * ).
dtypetorch.dtype, default=None: The Data type of the filter.
devicetorch.device, default=None: The Device of the returned filter.

Returns:

torch.Tensor: 2D Gaussian lowpass filter.

Examples

>>> img_f = torch.fft.rfft2(img)
>>> lowpass = get_gaussian_lowpass(img_f, 2)
>>> blurred_f = img_f * lowpass
>>> blurred = torch.fft.irfft2(blurred_f)

imgtools.filters

Links

_edges

Blur

Rfft

Documents

`imgtools.filters`