skshapes.SparseImage

class skshapes.SparseImage(*, indices=None, flat_indices=None, values, shape, constant=0, dtype=None, device=None)

Bases: ImageStructure

A D-dimensional grid, with a K-dimensional value associated to each of its voxels.

An SparseImage object only stores non-zero elements of the image, ensuring memory and time efficiency when working with images with many zeros. It can be created from a list of indices and a list of values, both provided as torch.Tensors.

Parameters:

• indices (Int64[Tensor, '*_'] | None) – A tensor of shape (N, D) containing the voxel positions where the values are specified.

• values (Float32[Tensor, '*_'] | Int64[Tensor, '*_']) – A tensor of shape (N,) or (N,V_1,...,V_K) containing the values at the specified positions.

• shape (tuple[int, ...]) – The shape of the full image.

• constant (Float32[Tensor, '*_'] | Int64[Tensor, '*_'] | int | float) – The value of the image at the positions not specified in indices. It must be a number or a tensor of shape (V_1,...,V_K), depending on the values shape. By default, it is set to a tensor full of zeros.

• dtype (dtype | None) – The data type of the image values. If None it is inferred from values.

• device (str | device | None) – The device on which the shape is stored (e.g. "cpu" or "cuda"). If None it is inferred from the values.

Examples

import skshapes as sks

image = sks.SparseImage(
    indices=torch.tensor([[0, 1], [2, 1], [2, 2]]),
    values=torch.tensor([0.1, 0.25, 0.47]),
    shape=(3, 4),
)
print(image.values)

tensor([[0.0000, 0.1000, 0.0000, 0.0000],
        [0.0000, 0.0000, 0.0000, 0.0000],
        [0.0000, 0.2500, 0.4700, 0.0000]])

import skshapes as sks

image = sks.SparseImage(
    indices=torch.tensor([[0, 1], [2, 1], [2, 2]]),
    values=torch.tensor([0.1, 0.25, 0.47]),
    shape=(3, 4),
    constant=3.0,
)
print(image.values)

tensor([[3.0000, 0.1000, 3.0000, 3.0000],
        [3.0000, 3.0000, 3.0000, 3.0000],
        [3.0000, 0.2500, 0.4700, 3.0000]])

__init__(*, indices=None, flat_indices=None, values, shape, constant=0, dtype=None, device=None)

Methods

__init__(*[, indices, flat_indices, ...])
apply_pointwise(operation[, other])	Apply a function at each point of the image.
apply_reduction(operation, *[, requires_count])
convolution(*, offsets[, weights, clip, kernel])
copy()
fill(shape, *, fill_value[, dtype, device])
histogram(bins)	!-> cpu
isin(test_elements)
masked_convolution(*, mask, offsets[, ...])
max()
min()
plot([backend])
reshape_values([values_shape])
to(device)	Copy the instance onto a given device.
to_dense(*[, dtype, device])
unique(*[, sorted, return_counts])
values_at(*, query_indices[, flat_query_indices])	Get the values of the image at the indices specified in input.
zeros(shape, *[, values_shape, dtype, device])

Attributes

constant
device	Device getter.
dim	The dimension D of the D-dimensional grid.
dtype	Dtype getter.
full_shape	The full shape of the image.
numel	The total number of voxels in the image.
shape	The shape of the D-dimensional grid.
values	The image values expressed as a tensor.
values_dim	The dimension of the value tensors
values_shape	For tensor-valued images, the shape of the value tensor.

property values: Float32[Tensor, '*_'] | Int64[Tensor, '*_']

The image values expressed as a tensor.

values_at(*, query_indices, flat_query_indices=None)

Get the values of the image at the indices specified in input.

Return type:

Float32[Tensor, '*_'] | Int64[Tensor, '*_']