Skip to content

bases

Utilities for image basis transforms and small helpers.

Full API

ImageBasis ¤

Bases: Base

Linear image basis wrapper.

Parameters:

Name Type Description Default
transform_matrix Array

Matrix that maps basis coefficients to flattened image pixels. The class stores the forward matrix M and a pseudo-inverse M_inv used to move between pixel and basis representations.

 required
Notes

The class intentionally accepts non-orthogonal bases and computes the pseudo-inverse when ortho=False.

Source code in src/dorito/bases.py 
 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
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
class ImageBasis(Base):
    """Linear image basis wrapper.

    Parameters
    ----------
    transform_matrix
        Matrix that maps basis coefficients to flattened image pixels. The
        class stores the forward matrix `M` and a pseudo-inverse `M_inv` used
        to move between pixel and basis representations.

    Notes
    -----
    The class intentionally accepts non-orthogonal bases and computes the
    pseudo-inverse when `ortho=False`.
    """

    M: Array
    M_inv: Array
    n_basis: int = eqx.field(static=True)
    size: int = eqx.field(static=True)

    def __init__(self, transform_matrix: Array, n_basis: int = None, ortho=False):
        if n_basis is None:
            n_basis = transform_matrix.shape[1]
        self.n_basis = n_basis
        self.M = transform_matrix[:, :n_basis]
        if ortho:
            self.M_inv = self.M.T
        else:
            self.M_inv = np.linalg.pinv(self.M)
        self.size = int(np.sqrt(self.M.shape[0]))

    def to_basis(self, img: Array) -> Array:
        """Project a 2D image into the basis and return coefficients.

        Parameters
        ----------
        img : Array
            2D image array with shape (size, size).

        Returns
        -------
        Array
            Basis coefficients (flattened).
        """
        return np.dot(self.M_inv, img.flatten())

    def from_basis(self, coeffs: Array) -> Array:
        """Reconstruct an image from basis coefficients.

        Parameters
        ----------
        coeffs : Array
            Basis coefficients.

        Returns
        -------
        Array
            2D image reconstructed from the provided coefficients.
        """
        return np.dot(self.M, coeffs).reshape((self.size, self.size))

to_basis(img) ¤

Project a 2D image into the basis and return coefficients.

Parameters:

Name Type Description Default
img Array

2D image array with shape (size, size).

 required

Returns:

Type Description
Array

Basis coefficients (flattened).
Source code in src/dorito/bases.py 
119
120
121
122
123
124
125
126
127
128
129
130
131
132
def to_basis(self, img: Array) -> Array:
    """Project a 2D image into the basis and return coefficients.

    Parameters
    ----------
    img : Array
        2D image array with shape (size, size).

    Returns
    -------
    Array
        Basis coefficients (flattened).
    """
    return np.dot(self.M_inv, img.flatten())

from_basis(coeffs) ¤

Reconstruct an image from basis coefficients.

Parameters:

Name Type Description Default
coeffs Array

Basis coefficients.

 required

Returns:

Type Description
Array

2D image reconstructed from the provided coefficients.
Source code in src/dorito/bases.py 
134
135
136
137
138
139
140
141
142
143
144
145
146
147
def from_basis(self, coeffs: Array) -> Array:
    """Reconstruct an image from basis coefficients.

    Parameters
    ----------
    coeffs : Array
        Basis coefficients.

    Returns
    -------
    Array
        2D image reconstructed from the provided coefficients.
    """
    return np.dot(self.M, coeffs).reshape((self.size, self.size))

inscribed_circ_basis(size, return_window=True) ¤

Create an image basis using pixels inside an inscribed circular window.

The function builds a linear basis matrix M that maps basis coefficients to the flattened image pixels for the pixels that lie inside a circular top-hat window inscribed in a square of side size.

Parameters:

Name Type Description Default
size int

Number of pixels on a side of the (square) image. The function constructs a size x size window and selects pixels inside the inscribed top-hat.

 required
return_window bool

If True (default) return a tuple (ImageBasis, window_arr) where window_arr is the boolean mask of selected pixels. Otherwise return only the ImageBasis instance.

 True

Returns:

Type Description
ImageBasis or (ImageBasis, ndarray)

The basis mapping (and optionally the boolean window mask).
Source code in src/dorito/bases.py 
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
def inscribed_circ_basis(size: int, return_window=True) -> Array:
    """Create an image basis using pixels inside an inscribed circular window.

    The function builds a linear basis matrix `M` that maps basis
    coefficients to the flattened image pixels for the pixels that lie
    inside a circular top-hat window inscribed in a square of side ``size``.

    Parameters
    ----------
    size : int
        Number of pixels on a side of the (square) image. The function
        constructs a ``size x size`` window and selects pixels inside the
        inscribed top-hat.
    return_window : bool, optional
        If True (default) return a tuple ``(ImageBasis, window_arr)`` where
        ``window_arr`` is the boolean mask of selected pixels. Otherwise
        return only the ``ImageBasis`` instance.

    Returns
    -------
    ImageBasis or (ImageBasis, ndarray)
        The basis mapping (and optionally the boolean window mask).
    """

    window_arr = TopHatWindow(1)((size, size))
    mask = onp.where(window_arr.flatten())[0]
    M = onp.eye(size**2)[:, mask]
    if return_window:
        return ImageBasis(np.array(M), ortho=True), window_arr
    return ImageBasis(np.array(M))

inscribed_annulus_basis(size, iterations=2, return_window=True) ¤

Create an image basis for an annulus (inscribed ring) window.

Constructs a basis matrix selecting pixels that lie in an annulus defined by subtracting an inner dilated mask from an outer top-hat window. The inner radius is controlled by iterations passed to scipy.ndimage.binary_dilation so larger iterations produce a wider inner hole.

Parameters:

Name Type Description Default
size int

Number of pixels on a side of the (square) image.

 required
iterations int

Number of binary dilation iterations used to build the inner hole (default: 2).

 2
return_window bool

If True (default) return a tuple (ImageBasis, window_arr) where window_arr is the boolean mask of selected annulus pixels.

 True

Returns:

Type Description
ImageBasis or (ImageBasis, ndarray)

The basis mapping (and optionally the boolean window mask).
Source code in src/dorito/bases.py 
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
def inscribed_annulus_basis(size: int, iterations=2, return_window=True) -> Array:
    """Create an image basis for an annulus (inscribed ring) window.

    Constructs a basis matrix selecting pixels that lie in an annulus
    defined by subtracting an inner dilated mask from an outer top-hat
    window. The inner radius is controlled by ``iterations`` passed to
    ``scipy.ndimage.binary_dilation`` so larger ``iterations`` produce a
    wider inner hole.

    Parameters
    ----------
    size : int
        Number of pixels on a side of the (square) image.
    iterations : int, optional
        Number of binary dilation iterations used to build the inner hole
        (default: 2).
    return_window : bool, optional
        If True (default) return a tuple ``(ImageBasis, window_arr)`` where
        ``window_arr`` is the boolean mask of selected annulus pixels.

    Returns
    -------
    ImageBasis or (ImageBasis, ndarray)
        The basis mapping (and optionally the boolean window mask).
    """

    outer = TopHatWindow(1)((size, size))
    inner = binary_dilation(
        np.zeros_like(outer).at[size // 2, size // 2].set(1), iterations=iterations
    )
    window_arr = outer - inner

    mask = onp.where(window_arr.flatten())[0]
    M = onp.eye(size**2)[:, mask]
    if return_window:
        return ImageBasis(np.array(M), ortho=True), window_arr
    return ImageBasis(np.array(M))