Grayscale Morphology

Grayscale operators process floating-point or integer-valued tensors shaped as (B, C, Spatial...).

torchmorph.grey_dilation

grey_dilation(
    input,
    size=None,
    footprint=None,
    structure=None,
    output=None,
    mode="reflect",
    cval=0.0,
    origin=0,
)

Dilate a batched grayscale CUDA tensor

Computes the local maximum after adding the non-flat structure. Computation uses float32 and supports one to eight spatial dimensions.

Parameters:

Name	Type	Description	Default
input	Tensor	CUDA tensor with shape (B, C, Spatial...).	required
size	int or tuple[int, ...]	Shape of a flat, full structuring element. A scalar is broadcast to every spatial axis.	None
footprint	Tensor	Boolean mask selecting participating positions. Must match structure when both are supplied.	None
structure	Tensor	Non-flat additive structuring element. It takes precedence over footprint and size.	None
output	Tensor	Preallocated result tensor with the same shape and device as input.	None
mode	str	Boundary mode: "reflect", "constant", "nearest", "mirror", or "wrap".	'reflect'
cval	float	Boundary value used when mode="constant".	0.0
origin	int or tuple[int, ...]	Structuring-element anchor offset.	0

Returns:

Type	Description
Tensor	torch.Tensor: Dilated tensor in float32, or output when supplied.

Example

>>> import torch
>>> import torchmorph as tm
>>> x = torch.arange(9, device="cuda").reshape(1, 1, 3, 3)
>>> tm.grey_dilation(x, size=3).dtype
torch.float32

torchmorph.grey_erosion

grey_erosion(
    input,
    size=None,
    footprint=None,
    structure=None,
    output=None,
    mode="reflect",
    cval=0.0,
    origin=0,
)

Erode a batched grayscale CUDA tensor

Computes the local minimum after subtracting the non-flat structure. Computation uses float32 and supports one to eight spatial dimensions.

Parameters:

Name	Type	Description	Default
input	Tensor	CUDA tensor with shape (B, C, Spatial...).	required
size	int or tuple[int, ...]	Shape of a flat, full structuring element. A scalar is broadcast to every spatial axis.	None
footprint	Tensor	Boolean mask selecting participating positions. Must match structure when both are supplied.	None
structure	Tensor	Non-flat additive structuring element. It takes precedence over footprint and size.	None
output	Tensor	Preallocated result tensor with the same shape and device as input.	None
mode	str	Boundary mode: "reflect", "constant", "nearest", "mirror", or "wrap".	'reflect'
cval	float	Boundary value used when mode="constant".	0.0
origin	int or tuple[int, ...]	Structuring-element anchor offset.	0

Returns:

Type	Description
Tensor	torch.Tensor: Eroded tensor in float32, or output when supplied.

Example

>>> import torch
>>> import torchmorph as tm
>>> x = torch.arange(9, device="cuda").reshape(1, 1, 3, 3)
>>> tm.grey_erosion(x, size=3).shape
torch.Size([1, 1, 3, 3])

torchmorph.grey_opening

grey_opening(
    input,
    size=None,
    footprint=None,
    structure=None,
    output=None,
    mode="reflect",
    cval=0.0,
    origin=0,
)

Open a grayscale tensor by erosion followed by dilation

Opening suppresses bright features smaller than the selected structuring element. Computation uses float32.

Parameters:

Name	Type	Description	Default
input	Tensor	CUDA tensor with shape (B, C, Spatial...).	required
size	int or tuple[int, ...]	Shape of a flat, full structuring element.	None
footprint	Tensor	Boolean mask selecting participating positions.	None
structure	Tensor	Non-flat additive structuring element. It takes precedence over footprint and size.	None
output	Tensor	Preallocated result tensor with the same shape and device as input.	None
mode	str	Boundary mode: "reflect", "constant", "nearest", "mirror", or "wrap".	'reflect'
cval	float	Boundary value used when mode="constant".	0.0
origin	int or tuple[int, ...]	Structuring-element anchor offset.	0

Returns:

Type	Description
Tensor	torch.Tensor: Opened tensor in float32, or output when supplied.

Example

>>> import torch
>>> import torchmorph as tm
>>> x = torch.zeros((1, 1, 5, 5), device="cuda")
>>> x[0, 0, 2, 2] = 1
>>> tm.grey_opening(x, size=3).max().item()
0.0

torchmorph.grey_closing

grey_closing(
    input,
    size=None,
    footprint=None,
    structure=None,
    output=None,
    mode="reflect",
    cval=0.0,
    origin=0,
)

Close a grayscale tensor by dilation followed by erosion

Closing suppresses dark features smaller than the selected structuring element. Computation uses float32.

Parameters:

Name	Type	Description	Default
input	Tensor	CUDA tensor with shape (B, C, Spatial...).	required
size	int or tuple[int, ...]	Shape of a flat, full structuring element.	None
footprint	Tensor	Boolean mask selecting participating positions.	None
structure	Tensor	Non-flat additive structuring element. It takes precedence over footprint and size.	None
output	Tensor	Preallocated result tensor with the same shape and device as input.	None
mode	str	Boundary mode: "reflect", "constant", "nearest", "mirror", or "wrap".	'reflect'
cval	float	Boundary value used when mode="constant".	0.0
origin	int or tuple[int, ...]	Structuring-element anchor offset.	0

Returns:

Type	Description
Tensor	torch.Tensor: Closed tensor in float32, or output when supplied.

Example

>>> import torch
>>> import torchmorph as tm
>>> x = torch.ones((1, 1, 5, 5), device="cuda")
>>> x[0, 0, 2, 2] = 0
>>> tm.grey_closing(x, size=3).min().item()
1.0

torchmorph.morphological_gradient

morphological_gradient(
    input,
    size=None,
    footprint=None,
    structure=None,
    output=None,
    mode="reflect",
    cval=0.0,
    origin=0,
)

Compute the morphological gradient of a grayscale tensor

The gradient is dilation(input) - erosion(input) and emphasizes local intensity transitions.

Parameters:

Name	Type	Description	Default
input	Tensor	CUDA tensor with shape (B, C, Spatial...).	required
size	int or tuple[int, ...]	Shape of a flat, full structuring element.	None
footprint	Tensor	Boolean mask selecting participating positions.	None
structure	Tensor	Non-flat additive structuring element. It takes precedence over footprint and size.	None
output	Tensor	Preallocated result tensor with the same shape and device as input.	None
mode	str	Boundary mode: "reflect", "constant", "nearest", "mirror", or "wrap".	'reflect'
cval	float	Boundary value used when mode="constant".	0.0
origin	int or tuple[int, ...]	Structuring-element anchor offset.	0

Returns:

Type	Description
Tensor	torch.Tensor: Morphological gradient in float32, or output.

Example

>>> import torch
>>> import torchmorph as tm
>>> x = torch.arange(25, device="cuda").reshape(1, 1, 5, 5)
>>> tm.morphological_gradient(x, size=3).shape
torch.Size([1, 1, 5, 5])

torchmorph.morphological_laplace

morphological_laplace(
    input,
    size=None,
    footprint=None,
    structure=None,
    output=None,
    mode="reflect",
    cval=0.0,
    origin=0,
)

Compute the morphological Laplacian of a grayscale tensor

Computes dilation(input) + erosion(input) - 2 * input using float32 arithmetic.

Parameters:

Name	Type	Description	Default
input	Tensor	CUDA tensor with shape (B, C, Spatial...).	required
size	int or tuple[int, ...]	Shape of a flat, full structuring element.	None
footprint	Tensor	Boolean mask selecting participating positions.	None
structure	Tensor	Non-flat additive structuring element. It takes precedence over footprint and size.	None
output	Tensor	Preallocated result tensor with the same shape and device as input.	None
mode	str	Boundary mode: "reflect", "constant", "nearest", "mirror", or "wrap".	'reflect'
cval	float	Boundary value used when mode="constant".	0.0
origin	int or tuple[int, ...]	Structuring-element anchor offset.	0

Returns:

Type	Description
Tensor	torch.Tensor: Morphological Laplacian in float32, or output.

Example

>>> import torch
>>> import torchmorph as tm
>>> x = torch.arange(25, device="cuda").reshape(1, 1, 5, 5)
>>> tm.morphological_laplace(x, size=3).dtype
torch.float32

torchmorph.white_tophat

white_tophat(
    input,
    size=None,
    footprint=None,
    structure=None,
    output=None,
    mode="reflect",
    cval=0.0,
    origin=0,
)

Extract small bright features with a white top-hat filter

Computes input - grey_opening(input) using float32 arithmetic.

Parameters:

Name	Type	Description	Default
input	Tensor	CUDA tensor with shape (B, C, Spatial...).	required
size	int or tuple[int, ...]	Shape of a flat, full structuring element.	None
footprint	Tensor	Boolean mask selecting participating positions.	None
structure	Tensor	Non-flat additive structuring element. It takes precedence over footprint and size.	None
output	Tensor	Preallocated result tensor with the same shape and device as input.	None
mode	str	Boundary mode: "reflect", "constant", "nearest", "mirror", or "wrap".	'reflect'
cval	float	Boundary value used when mode="constant".	0.0
origin	int or tuple[int, ...]	Structuring-element anchor offset.	0

Returns:

Type	Description
Tensor	torch.Tensor: White top-hat response in float32, or output.

Example

>>> import torch
>>> import torchmorph as tm
>>> x = torch.zeros((1, 1, 5, 5), device="cuda")
>>> x[0, 0, 2, 2] = 2
>>> tm.white_tophat(x, size=3).max().item()
2.0

torchmorph.black_tophat

black_tophat(
    input,
    size=None,
    footprint=None,
    structure=None,
    output=None,
    mode="reflect",
    cval=0.0,
    origin=0,
)

Extract small dark features with a black top-hat filter

Computes grey_closing(input) - input using float32 arithmetic.

Parameters:

Name	Type	Description	Default
input	Tensor	CUDA tensor with shape (B, C, Spatial...).	required
size	int or tuple[int, ...]	Shape of a flat, full structuring element.	None
footprint	Tensor	Boolean mask selecting participating positions.	None
structure	Tensor	Non-flat additive structuring element. It takes precedence over footprint and size.	None
output	Tensor	Preallocated result tensor with the same shape and device as input.	None
mode	str	Boundary mode: "reflect", "constant", "nearest", "mirror", or "wrap".	'reflect'
cval	float	Boundary value used when mode="constant".	0.0
origin	int or tuple[int, ...]	Structuring-element anchor offset.	0

Returns:

Type	Description
Tensor	torch.Tensor: Black top-hat response in float32, or output.

Example

>>> import torch
>>> import torchmorph as tm
>>> x = torch.ones((1, 1, 5, 5), device="cuda")
>>> x[0, 0, 2, 2] = 0
>>> tm.black_tophat(x, size=3).max().item()
1.0