Binary Morphology

Binary operators treat nonzero values as foreground and expect tensors shaped as (B, C, Spatial...).

torchmorph.binary_dilation

binary_dilation(
    input,
    structure=None,
    iterations=1,
    mask=None,
    output=None,
    border_value=False,
    origin=0,
)

Dilate binary objects in a batched CUDA tensor

A value is foreground when it is nonzero. The operation supports one to eight spatial dimensions and always treats the first two dimensions as batch and channel. When iterations is less than one, dilation continues until the result no longer changes.

Parameters:

Name	Type	Description	Default
input	Tensor	CUDA tensor with shape (B, C, Spatial...).	required
structure	Tensor	Spatial structuring element. Nonzero entries participate in the neighborhood. If None, uses :func:generate_binary_structure with connectivity 1.	None
iterations	int	Number of sequential dilations. Values less than 1 repeat the operation until convergence.	1
mask	Tensor	Tensor with the same shape as input. Only locations where the mask is nonzero may change.	None
output	Tensor	Preallocated tensor with the same shape and device as input. When supplied, receives and is returned as the result.	None
border_value	bool	Value used outside the input boundary.	False
origin	int or tuple[int, ...]	Offset of the structuring-element anchor. A scalar is applied to every spatial dimension.	0

Returns:

Type	Description
Tensor	torch.Tensor: Boolean dilation result, or output when it is supplied.

Example

>>> import torch
>>> import torchmorph as tm
>>> x = torch.zeros((1, 1, 5, 5), device="cuda")
>>> x[0, 0, 2, 2] = 1
>>> y = tm.binary_dilation(x, structure=torch.ones(3, 3))
>>> y.dtype, y.sum().item()
(torch.bool, 9)

torchmorph.binary_erosion

binary_erosion(
    input,
    structure=None,
    iterations=1,
    mask=None,
    output=None,
    border_value=False,
    origin=0,
)

Erode binary objects in a batched CUDA tensor

A value is foreground when it is nonzero. The operation supports one to eight spatial dimensions and always treats the first two dimensions as batch and channel. When iterations is less than one, erosion continues until the result no longer changes.

Parameters:

Name	Type	Description	Default
input	Tensor	CUDA tensor with shape (B, C, Spatial...).	required
structure	Tensor	Spatial structuring element. Nonzero entries participate in the neighborhood. If None, uses :func:generate_binary_structure with connectivity 1.	None
iterations	int	Number of sequential erosions. Values less than 1 repeat the operation until convergence.	1
mask	Tensor	Tensor with the same shape as input. Only locations where the mask is nonzero may change.	None
output	Tensor	Preallocated tensor with the same shape and device as input. When supplied, receives and is returned as the result.	None
border_value	bool	Value used outside the input boundary.	False
origin	int or tuple[int, ...]	Offset of the structuring-element anchor. A scalar is applied to every spatial dimension.	0

Returns:

Type	Description
Tensor	torch.Tensor: Boolean erosion result, or output when it is supplied.

Example

>>> import torch
>>> import torchmorph as tm
>>> x = torch.ones((1, 1, 5, 5), device="cuda")
>>> y = tm.binary_erosion(x, structure=torch.ones(3, 3))
>>> y.dtype, y.sum().item()
(torch.bool, 9)

torchmorph.binary_propagation

binary_propagation(
    input, structure=None, mask=None, output=None, border_value=False, origin=0
)

Propagate a binary seed through a mask until convergence

This repeatedly dilates input while allowing changes only where mask is nonzero. It is useful for morphological reconstruction.

Parameters:

Name	Type	Description	Default
input	Tensor	Binary seed CUDA tensor with shape (B, C, Spatial...); nonzero values are foreground.	required
structure	Tensor	Spatial structuring element. If None, uses connectivity 1.	None
mask	Tensor	Tensor with the same shape as input. Only nonzero mask locations may change. If None, propagation is unconstrained.	None
output	Tensor	Preallocated result tensor with the same shape and device as input.	None
border_value	bool	Value used outside the input boundary.	False
origin	int or tuple[int, ...]	Structuring-element anchor offset.	0

Returns:

Type	Description
Tensor	torch.Tensor: Boolean converged result, or output when supplied.

Example

>>> import torch
>>> import torchmorph as tm
>>> seed = torch.zeros((1, 1, 5, 5), device="cuda")
>>> seed[0, 0, 2, 2] = 1
>>> mask = torch.ones_like(seed)
>>> tm.binary_propagation(seed, mask=mask).all().item()
True

torchmorph.binary_fill_holes

binary_fill_holes(input, structure=None, output=None, origin=0)

Fill holes enclosed by binary objects

Background connected to the tensor boundary is reconstructed and removed; enclosed background regions become foreground.

Parameters:

Name	Type	Description	Default
input	Tensor	CUDA tensor with shape (B, C, Spatial...); nonzero values are foreground.	required
structure	Tensor	Spatial structuring element used to determine background connectivity. If None, uses connectivity 1.	None
output	Tensor	Preallocated result tensor with the same shape and device as input.	None
origin	int or tuple[int, ...]	Structuring-element anchor offset.	0

Returns:

Type	Description
Tensor	torch.Tensor: Boolean tensor with enclosed holes filled, 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.binary_fill_holes(x)[0, 0, 2, 2].item()
True

torchmorph.binary_hit_or_miss

binary_hit_or_miss(
    input, structure1=None, structure2=None, output=None, origin1=0, origin2=None
)

Find binary configurations with the hit-or-miss transform

A location matches when structure1 fits the foreground and structure2 fits the background at the same anchor.

Parameters:

Name	Type	Description	Default
input	Tensor	CUDA tensor with shape (B, C, Spatial...); nonzero values are foreground.	required
structure1	Tensor	Foreground structuring element. If None, uses connectivity 1.	None
structure2	Tensor	Background structuring element. If None, uses the logical complement of structure1.	None
output	Tensor	Preallocated result tensor with the same shape and device as input.	None
origin1	int or tuple[int, ...]	Anchor offset for structure1.	0
origin2	int or tuple[int, ...]	Anchor offset for structure2. If None, uses origin1.	None

Returns:

Type	Description
Tensor	torch.Tensor: Boolean tensor marking matching locations, or output.

Example

>>> import torch
>>> import torchmorph as tm
>>> x = torch.zeros((1, 1, 3, 3), device="cuda")
>>> x[0, 0, 1, 1] = 1
>>> hit = tm.binary_hit_or_miss(x, structure1=torch.ones(1, 1))
>>> hit[0, 0, 1, 1].item()
True

torchmorph.binary_opening

binary_opening(
    input,
    structure=None,
    iterations=1,
    mask=None,
    output=None,
    border_value=False,
    origin=0,
)

Open binary objects by erosion followed by dilation

Opening removes foreground features that cannot contain the structuring element while largely preserving larger objects.

Parameters:

Name	Type	Description	Default
input	Tensor	CUDA tensor with shape (B, C, Spatial...); nonzero values are foreground.	required
structure	Tensor	Spatial structuring element. If None, uses connectivity 1.	None
iterations	int	Number of erosions followed by the same number of dilations. Values less than 1 iterate each stage to convergence.	1
mask	Tensor	Same-shaped tensor whose nonzero entries identify locations that may change.	None
output	Tensor	Preallocated result tensor with the same shape and device as input.	None
border_value	bool	Value used outside the input boundary.	False
origin	int or tuple[int, ...]	Structuring-element anchor offset.	0

Returns:

Type	Description
Tensor	torch.Tensor: Boolean opened tensor, or output when supplied.

Example

>>> import torch
>>> import torchmorph as tm
>>> x = torch.zeros((1, 1, 5, 5), device="cuda")
>>> x[0, 0, 1:4, 1:4] = 1
>>> x[0, 0, 0, 0] = 1
>>> tm.binary_opening(x).sum().item()
5

torchmorph.binary_closing

binary_closing(
    input,
    structure=None,
    iterations=1,
    mask=None,
    output=None,
    border_value=False,
    origin=0,
)

Close binary objects by dilation followed by erosion

Closing fills small gaps and joins nearby foreground regions while largely preserving the extent of larger objects.

Parameters:

Name	Type	Description	Default
input	Tensor	CUDA tensor with shape (B, C, Spatial...); nonzero values are foreground.	required
structure	Tensor	Spatial structuring element. If None, uses connectivity 1.	None
iterations	int	Number of dilations followed by the same number of erosions. Values less than 1 iterate each stage to convergence.	1
mask	Tensor	Same-shaped tensor whose nonzero entries identify locations that may change.	None
output	Tensor	Preallocated result tensor with the same shape and device as input.	None
border_value	bool	Value used outside the input boundary.	False
origin	int or tuple[int, ...]	Structuring-element anchor offset.	0

Returns:

Type	Description
Tensor	torch.Tensor: Boolean closed tensor, or output when supplied.

Example

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