Skip to content

Modules

provides the SparseMasksTensor class.

Copyright (C) 2025 MaKaNu

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see https://www.gnu.org/licenses/.

SparseMasksTensor

A 3D Sparse Matrix which represents a stack of binary class masks.

Source code in src/pytorch_sparse_special/special/sparse_mask.py 
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
class SparseMasksTensor:
    """A 3D Sparse Matrix which represents a stack of binary class masks."""

    def __init__(self, indices: torch.Tensor, values: torch.Tensor, size: tuple[int]) -> None:
        """initilaize a SparseMaskTensor instance.
        The actual tensor is a property of the class object.
        For further information about the class arguments refer:
        [sparse_coo_tensor](https://pytorch.org/docs/stable/generated/torch.sparse_coo_tensor.html)

        Args:
            indices (torch.Tensor): [DxP] The coordinates for the values of the Matrix. D equals 3.
            values (torch.Tensor): [1xP] The values of the masks.
            size (tuple[int]): Size of the Matrix. Has to be three values. [NxHxW]
                N = Number of masks
                H = Height of image
                W = Width of image

        Raises:
            SizeValueError: If Size or indices doesn't match 3D.
        """
        if len(size) != 3 or indices.shape[0] != 3:
            raise SizeValueError(self)
        self.sparse_tensor: torch.Tensor = torch.sparse_coo_tensor(indices, values, size, is_coalesced=True)
        self.n_total: int = size[0]

    def extract_sparse_region(self, bbox: torch.Tensor) -> tuple[torch.Tensor, torch.Tensor]:
        """
        Extract non-zero elements within a bounding box from a sparse tensor.

        Args:
            bbox (torch.Tensor): The BBox, which inhouses the pixels

        Returns:
            tuple[torch.Tensor, torch.Tensor]: filtered indices and values which are inside the bbox.
        """

        x_min, y_min, x_max, y_max = bbox
        indices = self.sparse_tensor.indices()
        values = self.sparse_tensor.values()

        # Mask for indices within the bounding box
        mask_x = (indices[1] >= x_min) & (indices[1] < x_max)
        mask_y = (indices[2] >= y_min) & (indices[2] < y_max)
        mask = mask_x & mask_y

        # Extract the relevant indices and values
        filtered_indices = indices[:, mask]
        filtered_values = values[mask]

        return filtered_indices, filtered_values

    def _get_full_count(self, indices: torch.Tensor) -> torch.Tensor:
        """Creates for all masks count of pixels based on indices.

        Args:
            indices (torch.Tensor): Tensor with indices.

        Returns:
            torch.Tensor: Tensor of shape [N, 1] with the number of pixels based on indices.
        """
        # count the values on the N axis
        unique_index, count = indices[0, :].unique(return_counts=True)

        # Create Tensor with the range of all mask
        # necessary, if mask not inside bbox and we want to keep the actual shape
        num_masks = torch.arange(self.n_total)

        # Final variable which has the shape matching all masks
        full_count = torch.zeros(num_masks.shape, dtype=torch.long)

        # The unique_index correlates with the mask layer index
        # which enables infusing the count into full_count
        full_count[unique_index] = count
        return full_count

    def pixel_per_mask(self) -> torch.Tensor:
        """Count the number of pixels per masks from the sparse matrix.

        Returns:
            Tensor: Number of unique values on z axis.
        """
        indices = self.sparse_tensor.indices()
        return self._get_full_count(indices)

    def pixel_per_mask_inside(self, bbox: torch.Tensor) -> torch.Tensor:
        """Count the number of pixels per mask inside the given bbox from the sparse matrix.

        Args:
            bbox (Tensor): holds the bbox information (xmin, ymin, xmax, ymax)

        Returns:
            Tensor: Number of unique values on z axis inside bbox
        """
        inside_indices, _ = self.extract_sparse_region(bbox)
        return self._get_full_count(inside_indices)

__init__(indices, values, size)

initilaize a SparseMaskTensor instance. The actual tensor is a property of the class object. For further information about the class arguments refer: sparse_coo_tensor

Parameters:

Name Type Description Default
indices Tensor

[DxP] The coordinates for the values of the Matrix. D equals 3.

 required
values Tensor

[1xP] The values of the masks.

 required
size tuple[int]

Size of the Matrix. Has to be three values. [NxHxW] N = Number of masks H = Height of image W = Width of image

 required

Raises:

Type Description
SizeValueError

If Size or indices doesn't match 3D.
Source code in src/pytorch_sparse_special/special/sparse_mask.py 
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
def __init__(self, indices: torch.Tensor, values: torch.Tensor, size: tuple[int]) -> None:
    """initilaize a SparseMaskTensor instance.
    The actual tensor is a property of the class object.
    For further information about the class arguments refer:
    [sparse_coo_tensor](https://pytorch.org/docs/stable/generated/torch.sparse_coo_tensor.html)

    Args:
        indices (torch.Tensor): [DxP] The coordinates for the values of the Matrix. D equals 3.
        values (torch.Tensor): [1xP] The values of the masks.
        size (tuple[int]): Size of the Matrix. Has to be three values. [NxHxW]
            N = Number of masks
            H = Height of image
            W = Width of image

    Raises:
        SizeValueError: If Size or indices doesn't match 3D.
    """
    if len(size) != 3 or indices.shape[0] != 3:
        raise SizeValueError(self)
    self.sparse_tensor: torch.Tensor = torch.sparse_coo_tensor(indices, values, size, is_coalesced=True)
    self.n_total: int = size[0]

extract_sparse_region(bbox)

Extract non-zero elements within a bounding box from a sparse tensor.

Parameters:

Name Type Description Default
bbox Tensor

The BBox, which inhouses the pixels

 required

Returns:

Type Description
tuple[Tensor, Tensor]

tuple[torch.Tensor, torch.Tensor]: filtered indices and values which are inside the bbox.
Source code in src/pytorch_sparse_special/special/sparse_mask.py 
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
def extract_sparse_region(self, bbox: torch.Tensor) -> tuple[torch.Tensor, torch.Tensor]:
    """
    Extract non-zero elements within a bounding box from a sparse tensor.

    Args:
        bbox (torch.Tensor): The BBox, which inhouses the pixels

    Returns:
        tuple[torch.Tensor, torch.Tensor]: filtered indices and values which are inside the bbox.
    """

    x_min, y_min, x_max, y_max = bbox
    indices = self.sparse_tensor.indices()
    values = self.sparse_tensor.values()

    # Mask for indices within the bounding box
    mask_x = (indices[1] >= x_min) & (indices[1] < x_max)
    mask_y = (indices[2] >= y_min) & (indices[2] < y_max)
    mask = mask_x & mask_y

    # Extract the relevant indices and values
    filtered_indices = indices[:, mask]
    filtered_values = values[mask]

    return filtered_indices, filtered_values

pixel_per_mask()

Count the number of pixels per masks from the sparse matrix.

Returns:

Name Type Description
Tensor Tensor

Number of unique values on z axis.
Source code in src/pytorch_sparse_special/special/sparse_mask.py 
 99
100
101
102
103
104
105
106
def pixel_per_mask(self) -> torch.Tensor:
    """Count the number of pixels per masks from the sparse matrix.

    Returns:
        Tensor: Number of unique values on z axis.
    """
    indices = self.sparse_tensor.indices()
    return self._get_full_count(indices)

pixel_per_mask_inside(bbox)

Count the number of pixels per mask inside the given bbox from the sparse matrix.

Parameters:

Name Type Description Default
bbox Tensor

holds the bbox information (xmin, ymin, xmax, ymax)

 required

Returns:

Name Type Description
Tensor Tensor

Number of unique values on z axis inside bbox
Source code in src/pytorch_sparse_special/special/sparse_mask.py 
108
109
110
111
112
113
114
115
116
117
118
def pixel_per_mask_inside(self, bbox: torch.Tensor) -> torch.Tensor:
    """Count the number of pixels per mask inside the given bbox from the sparse matrix.

    Args:
        bbox (Tensor): holds the bbox information (xmin, ymin, xmax, ymax)

    Returns:
        Tensor: Number of unique values on z axis inside bbox
    """
    inside_indices, _ = self.extract_sparse_region(bbox)
    return self._get_full_count(inside_indices)
provides the metric functions for pytorch_sparse_special.

Copyright (C) 2025 MaKaNu

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see https://www.gnu.org/licenses/.

iou_sparse_masks_bbox(sparse_masks, bbox)

Calculates the Intersection over Union for SparseMasksTensor and a bbox

Parameters:

Name Type Description Default
sparse_masks SparseMasksTensor

Multiple sparse depictions of a class valued. [WxHxN]

 required
bbox Tensor

bbox representation in from [xmin, ymin, xmax, ymax].

 required

Returns:

Type Description
Tensor

torch.Tensor: iou of all masks against the bbox
Source code in src/pytorch_sparse_special/metrics.py 
25
26
27
28
29
30
31
32
33
34
35
36
37
38
def iou_sparse_masks_bbox(sparse_masks: SparseMasksTensor, bbox: torch.Tensor) -> torch.Tensor:
    """Calculates the Intersection over Union for SparseMasksTensor and a bbox

    Args:
        sparse_masks (SparseMasksTensor): Multiple sparse depictions of a class valued. [WxHxN]
        bbox (torch.Tensor): bbox representation in from [xmin, ymin, xmax, ymax].

    Returns:
        torch.Tensor: iou of all masks against the bbox
    """
    iou = sparse_masks.pixel_per_mask_inside(bbox) / (
        area_of_bbox(bbox) + sparse_masks.pixel_per_mask() - sparse_masks.pixel_per_mask_inside(bbox)
    )
    return iou
provides the utils functions for pytorch_sparse_special.

Copyright (C) 2025 MaKaNu

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see https://www.gnu.org/licenses/.

area_of_bbox(bbox)

Calculate the area of a given bbox

Parameters:

Name Type Description Default
bbox Tensor

bbox in form [xmin, ymin, xmax, ymax]

 required

Returns:

Type Description
Tensor

torch.Tensor: Area of bbox.
Source code in src/pytorch_sparse_special/utils.py 
22
23
24
25
26
27
28
29
30
31
32
33
def area_of_bbox(bbox: torch.Tensor) -> torch.Tensor:
    """Calculate the area of a given bbox

    Args:
        bbox (torch.Tensor): bbox in form [xmin, ymin, xmax, ymax]

    Returns:
        torch.Tensor: Area of bbox.
    """
    xmin, ymin, xmax, ymax = bbox
    result: torch.Tensor = (xmax - xmin) * (ymax - ymin)
    return result
provides the error classes for pytorch_sparse_special.

Copyright (C) 2025 MaKaNU

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see https://www.gnu.org/licenses/.

SizeValueError

Bases: ValueError

A SizeValueError extends ValueError.

Should be raised if the vize value of an object does not met the criteria.

Source code in src/pytorch_sparse_special/errors.py 
22
23
24
25
26
27
28
29
30
31
32
33
34
class SizeValueError(ValueError):
    """A SizeValueError extends ValueError.

    Should be raised if the vize value of an object does not met the criteria.
    """

    def __init__(self, obj: Any) -> None:
        """creates instance of SizeValueError

        Args:
            obj (Any): The object which size value does not met the criteria.
        """
        super().__init__(f"{type(obj)} is defined as 3D Matrix. Fix size or indices attribute!")

__init__(obj)

creates instance of SizeValueError

Parameters:

Name Type Description Default
obj Any

The object which size value does not met the criteria.

 required
Source code in src/pytorch_sparse_special/errors.py 
28
29
30
31
32
33
34
def __init__(self, obj: Any) -> None:
    """creates instance of SizeValueError

    Args:
        obj (Any): The object which size value does not met the criteria.
    """
    super().__init__(f"{type(obj)} is defined as 3D Matrix. Fix size or indices attribute!")