microeye 2.3.2__py3-none-any.whl

microEye/analysis/rendering/base.py

@@ -0,0 +1,452 @@
+from enum import Enum
+
+import numba
+import numpy as np
+
+from microEye.analysis.rendering.core import model
+
+
+@numba.njit()
+def render_compute(data, step, gauss_2d, out_img):
+    for x, y, Intensity in data:
+        out_img[y - step : y + step + 1, x - step : x + step + 1] += (
+            Intensity * gauss_2d
+        )
+
+
+@numba.njit()
+def render_compute_projection(data, step_lateral, step_axial, gauss_2d, out_img):
+    for lateral, axial, Intensity in data:
+        out_img[
+            axial - step_axial : axial + step_axial + 1,
+            lateral - step_lateral : lateral + step_lateral + 1,
+        ] += Intensity * gauss_2d
+
+
+@numba.njit()
+def filter_points_in_range(coords, values, center, half_width):
+    '''Filter points within a range along one dimension.'''
+    mask = (coords >= center - half_width) & (coords <= center + half_width)
+    return mask
+
+
+class RenderModes(Enum):
+    '''
+    Enum class for the rendering modes.
+    '''
+
+    HISTOGRAM = 0
+    '''Intensity Histogram'''
+    EVENT_HISTOGRAM = 1
+    '''Event Histogram'''
+    GAUSSIAN = 2
+    '''Gaussian Rendering'''
+
+
+class Projection(Enum):
+    '''
+    Enum class for different projections.
+    '''
+
+    XY = 0
+    '''XY Projection'''
+    XZ = 1
+    '''XZ Projection'''
+    YZ = 2
+    '''YZ Projection'''
+
+
+class BaseRenderer:
+    '''
+    Base class for rendering super resolution images
+    from single molecule localizations.
+    '''
+
+    def __init__(self, pixel_size=10, z_pixel_size=None, mode=RenderModes.HISTOGRAM):
+        '''
+        Initializes the renderer.
+
+        Parameters:
+        -----------
+        pixel_size : float
+            Pixel size of the rendered image in lateral dimensions (XY).
+        z_pixel_size : float, optional
+            Pixel size for axial dimension (Z). If None, uses pixel_size.
+        mode : RenderModes
+            Rendering mode.
+        '''
+        self._pixel_size = pixel_size
+        self._z_pixel_size = z_pixel_size if z_pixel_size is not None else pixel_size
+        self._mode = mode
+        self._image = None
+        self._origin = None
+
+        if self._mode == RenderModes.GAUSSIAN:
+            self.generate_gaussian_kernels()
+
+    def generate_gaussian_kernels(self):
+        '''
+        Generates Gaussian kernels for rendering both lateral and axial projections.
+        '''
+        # Lateral kernel (XY)
+        self._std = self._pixel_size  # nm
+        self._gauss_std = self._std / self._pixel_size
+        self._gauss_len = 1 + np.ceil(self._gauss_std * 6)
+        if self._gauss_len % 2 == 0:
+            self._gauss_len += 1
+        self._gauss_shape = [int(self._gauss_len)] * 2
+
+        # Axial kernel (Z)
+        self._z_std = self._z_pixel_size  # nm
+        self._z_gauss_std = self._z_std / self._z_pixel_size
+        self._z_gauss_len = 1 + np.ceil(self._z_gauss_std * 6)
+        if self._z_gauss_len % 2 == 0:
+            self._z_gauss_len += 1
+
+        # Generate kernels for different projections
+        xy_len = np.arange(0, self._gauss_shape[0])
+        X, Y = np.meshgrid(xy_len, xy_len)
+
+        # Standard XY kernel
+        self._gauss_2d = model(
+            (self._gauss_len - 1) / 2,
+            (self._gauss_len - 1) / 2,
+            self._gauss_std,
+            self._gauss_std,
+            1,
+            0,
+            X,
+            Y,
+        )
+
+        # XZ/YZ projection kernel (asymmetric)
+        xz_len_lateral = np.arange(0, self._gauss_len)
+        xz_len_axial = np.arange(0, self._z_gauss_len)
+        X_proj, Z_proj = np.meshgrid(xz_len_lateral, xz_len_axial)
+
+        self._gauss_2d_projection = model(
+            (self._gauss_len - 1) / 2,
+            (self._z_gauss_len - 1) / 2,
+            self._gauss_std,
+            self._z_gauss_std,
+            1,
+            0,
+            X_proj,
+            Z_proj,
+        )
+
+    def _validate_inputs(self, X, Y, Intensity):
+        '''
+        Validate the inputs for rendering.
+        '''
+        if any([X is None, Y is None, Intensity is None]):
+            raise Exception('One or more of the inputs are None.')
+        if not len(X) == len(Y) == len(Intensity):
+            raise Exception('The supplied arguments are of different lengths.')
+
+    def _zero_origin(self, X, Y):
+        '''
+        Zero the origin of the coordinates.
+        '''
+        x_min = np.min(X)
+        y_min = np.min(Y)
+
+        if x_min < 0:
+            X = X - x_min
+        if y_min < 0:
+            Y = Y - y_min
+
+        return X, Y
+
+    def render(
+        self,
+        projection: Projection,
+        X,
+        Y,
+        Z,
+        Intensity,
+        shape=None,
+    ):
+        '''
+        Renders super resolution image from single
+        molecule localizations.
+
+        Parameters
+        ----------
+        projection : Projection
+            Projection type
+        X, Y, Z : np.ndarray
+            Coordinates of localizations
+        Intensity : np.ndarray
+            Intensity values
+        shape : tuple[int, int], optional
+            Output image shape (height, width)
+
+        Returns
+        -------
+        np.ndarray
+            Rendered image
+        '''
+        if projection == Projection.XY:
+            return self.render_xy(X, Y, Intensity, shape)
+        elif projection == Projection.XZ:
+            return self.render_xz(X, Z, Intensity, shape)
+        elif projection == Projection.YZ:
+            return self.render_yz(Y, Z, Intensity, shape)
+        else:
+            raise ValueError('Invalid projection type.')
+
+    def render_xy(self, X, Y, Intensity, shape=None):
+        '''
+        Renders super resolution image (XY Projection) from single
+        molecule localizations.
+
+
+        Params
+        -------
+        X (np.ndarray)
+            Sub-pixel localized points X coordinates
+        Y (np.ndarray)
+            Sub-pixel localized points Y coordinates
+        Intensity (np.ndarray)
+            Sub-pixel localized points intensity estimate
+        shape (tuple[int, int], optional)
+            Super-res image (height, width), by default None
+
+        Returns
+        -------
+        Image (np.ndarray)
+            the rendered 2D super-res image array
+        '''
+        self._validate_inputs(X, Y, Intensity)
+        X, Y = self._zero_origin(X, Y)
+
+        if self._mode in [RenderModes.HISTOGRAM, RenderModes.EVENT_HISTOGRAM]:
+            if shape is None:
+                x_max = int((np.max(X) / self._pixel_size) + 4)
+                y_max = int((np.max(Y) / self._pixel_size) + 4)
+            else:
+                x_max, y_max = shape[1], shape[0]
+            n_max = max(x_max, y_max)
+
+            self._image = np.zeros([n_max, n_max])
+            X = np.round(X / self._pixel_size) + 2
+            Y = np.round(Y / self._pixel_size) + 2
+
+            if self._mode == RenderModes.EVENT_HISTOGRAM:
+                Intensity = np.ones_like(Intensity)
+            render_compute(np.c_[X, Y, Intensity], 0, 1, self._image)
+        elif self._mode == RenderModes.GAUSSIAN:
+            if shape is None:
+                x_max = int((np.max(X) / self._pixel_size) + 4 * self._gauss_len)
+                y_max = int((np.max(Y) / self._pixel_size) + 4 * self._gauss_len)
+            else:
+                x_max, y_max = shape[1], shape[0]
+            n_max = max(x_max, y_max)
+
+            step = int((self._gauss_len - 1) // 2)
+            self._image = np.zeros([n_max, n_max])
+            X = np.round(X / self._pixel_size) + 4 * step
+            Y = np.round(Y / self._pixel_size) + 4 * step
+
+            render_compute(np.c_[X, Y, Intensity], step, self._gauss_2d, self._image)
+
+        return self._image
+
+    def render_xz(self, X, Z, Intensity, shape=None):
+        '''
+        Renders XZ projection of super resolution image.
+
+        Parameters
+        ----------
+        X : np.ndarray
+            X coordinates
+        Z : np.ndarray
+            Z coordinates
+        Intensity : np.ndarray
+            Intensity values
+        shape : tuple[int, int], optional
+            Output image shape (z_height, x_width)
+
+        Returns
+        -------
+        np.ndarray
+            Rendered XZ projection
+        '''
+        self._validate_inputs(X, Z, Intensity)
+        X, Z = self._zero_origin(X, Z)
+
+        if self._mode in [RenderModes.HISTOGRAM, RenderModes.EVENT_HISTOGRAM]:
+            if shape is None:
+                x_max = int((np.max(X) / self._pixel_size) + 4)
+                z_max = int((np.max(Z) / self._z_pixel_size) + 4)
+            else:
+                x_max, z_max = shape[1], shape[0]
+
+            self._image = np.zeros([z_max, x_max])
+            X = np.round(X / self._pixel_size) + 2
+            Z = np.round(Z / self._z_pixel_size) + 2
+
+            if self._mode == RenderModes.EVENT_HISTOGRAM:
+                Intensity = np.ones_like(Intensity)
+            render_compute(np.c_[X, Z, Intensity], 0, 1, self._image)
+
+        elif self._mode == RenderModes.GAUSSIAN:
+            if shape is None:
+                x_max = int((np.max(X) / self._pixel_size) + 4 * self._gauss_len)
+                z_max = int((np.max(Z) / self._z_pixel_size) + 4 * self._z_gauss_len)
+            else:
+                x_max, z_max = shape[1], shape[0]
+
+            step_lateral = int((self._gauss_len - 1) // 2)
+            step_axial = int((self._z_gauss_len - 1) // 2)
+
+            self._image = np.zeros([z_max, x_max])
+            X = np.round(X / self._pixel_size) + 4 * step_lateral
+            Z = np.round(Z / self._z_pixel_size) + 4 * step_axial
+
+            render_compute_projection(
+                np.c_[X, Z, Intensity],
+                step_lateral,
+                step_axial,
+                self._gauss_2d_projection,
+                self._image,
+            )
+
+        return self._image
+
+    def render_yz(self, Y, Z, Intensity, shape=None):
+        '''
+        Renders YZ projection of super resolution image.
+
+        Parameters
+        ----------
+        Y : np.ndarray
+            Y coordinates
+        Z : np.ndarray
+            Z coordinates
+        Intensity : np.ndarray
+            Intensity values
+        shape : tuple[int, int], optional
+            Output image shape (z_height, y_width)
+
+        Returns
+        -------
+        np.ndarray
+            Rendered YZ projection
+        '''
+        return self.render_xz(Y, Z, Intensity, shape)
+
+    def render_slice(
+        self,
+        projection: Projection,
+        X,
+        Y,
+        Z,
+        Intensity,
+        position,
+        width=None,
+        shape=None,
+    ):
+        '''
+        Renders selected projection image at specific othogonal position
+        with given bin width.
+
+        Parameters
+        ----------
+        projection : Projection
+            Projection type
+        X, Y, Z : np.ndarray
+            Coordinates of localizations
+        Intensity : np.ndarray
+            Intensity values
+        position : float
+            Position of the slice in the orthogonal axis
+        width : float, optional
+            Width of the slice, by default None
+        shape : tuple[int, int], optional
+            Output image shape (height, width)
+
+        Returns
+        -------
+        np.ndarray
+            Rendered XY slice at specified Z position
+        '''
+        # Validate inputs
+        if not len(X) == len(Y) == len(Z) == len(Intensity):
+            raise Exception('The supplied arguments are of different lengths.')
+
+        # Set slice width
+        if width is None:
+            if projection == Projection.XY:
+                width = self._z_pixel_size
+            else:
+                width = self._pixel_size
+
+        # Filter points within Z range
+        half_width = width / 2
+        if projection == Projection.XY:
+            mask = filter_points_in_range(Z, Intensity, position, half_width)
+
+            if not np.any(mask):
+                return None
+
+            # Only render points within the Z range
+            X_filtered = X[mask]
+            Y_filtered = Y[mask]
+            I_filtered = Intensity[mask]
+
+            # Render the filtered points using existing render method
+            return self.render_xy(X_filtered, Y_filtered, I_filtered, shape)
+        elif projection == Projection.XZ:
+            mask = filter_points_in_range(Y, Intensity, position, half_width)
+
+            if not np.any(mask):
+                return None
+
+            # Filter points within Y range
+            half_width = width / 2
+            y_mask = filter_points_in_range(Y, Intensity, position, half_width)
+
+            # Only render points within the Y range
+            X_filtered = X[y_mask]
+            Z_filtered = Z[y_mask]
+            I_filtered = Intensity[y_mask]
+
+            return self.render_xz(X_filtered, Z_filtered, I_filtered, shape)
+        elif projection == Projection.YZ:
+            mask = filter_points_in_range(X, Intensity, position, half_width)
+
+            if not np.any(mask):
+                return None
+
+            # Filter points within X range
+            half_width = width / 2
+            x_mask = filter_points_in_range(X, Intensity, position, half_width)
+
+            # Only render points within the X range
+            Y_filtered = Y[x_mask]
+            Z_filtered = Z[x_mask]
+            I_filtered = Intensity[x_mask]
+
+            return self.render_yz(Y_filtered, Z_filtered, I_filtered, shape)
+        else:
+            raise ValueError('Invalid projection type.')
+
+    def from_array(self, data: np.ndarray, shape=None):
+        '''Renders as super resolution image from
+        single molecule localizations.
+
+        Params
+        -------
+        data (np.ndarray)
+            Array with sub-pixel localization data columns (X, Y, Intensity)
+        shape (tuple[int, int], optional)
+            Super-res image (height, width), by default None
+
+        Returns
+        -------
+        Image (np.ndarray)
+            the rendered 2D super-res image array
+        '''
+        return self.render_xy(data[:, 0], data[:, 1], data[:, 2], shape)

microEye/analysis/rendering/cloud.py

@@ -0,0 +1,215 @@
+import numba
+import numpy as np
+
+
+@numba.jit(nopython=True)
+def compute_point_cloud_histogram(data, bin_edges_x, bin_edges_y, bin_edges_z):
+    '''
+    Compute the 3D histogram using numba for acceleration.
+    Returns coordinates and intensities of non-zero bins.
+    '''
+    # Initialize arrays to store results
+    max_points = len(data)  # Maximum possible number of points
+    points = np.zeros((max_points, 3), dtype=np.float64)
+    intensities = np.zeros(max_points, dtype=np.float64)
+    point_count = 0
+
+    # Create temporary volume for binning
+    hist = np.zeros((len(bin_edges_z) - 1, len(bin_edges_y) - 1, len(bin_edges_x) - 1))
+
+    # Accumulate points into bins
+    for x, y, z, intensity in data:
+        # Find bin indices
+        x_idx = np.searchsorted(bin_edges_x, x) - 1
+        y_idx = np.searchsorted(bin_edges_y, y) - 1
+        z_idx = np.searchsorted(bin_edges_z, z) - 1
+
+        # Check if point is within bounds
+        if (
+            0 <= x_idx < len(bin_edges_x) - 1
+            and 0 <= y_idx < len(bin_edges_y) - 1
+            and 0 <= z_idx < len(bin_edges_z) - 1
+        ):
+            hist[z_idx, y_idx, x_idx] += intensity
+
+    # Extract non-zero bins
+    for z_idx in range(len(bin_edges_z) - 1):
+        for y_idx in range(len(bin_edges_y) - 1):
+            for x_idx in range(len(bin_edges_x) - 1):
+                if hist[z_idx, y_idx, x_idx] > 0:
+                    # Calculate center coordinates of the bin
+                    x_center = (bin_edges_x[x_idx] + bin_edges_x[x_idx + 1]) / 2
+                    y_center = (bin_edges_y[y_idx] + bin_edges_y[y_idx + 1]) / 2
+                    z_center = (bin_edges_z[z_idx] + bin_edges_z[z_idx + 1]) / 2
+
+                    points[point_count] = np.array([x_center, y_center, z_center])
+                    intensities[point_count] = hist[z_idx, y_idx, x_idx]
+                    point_count += 1
+
+    return points[:point_count], intensities[:point_count]
+
+
+class PointCloudRenderer:
+    '''
+    Point cloud renderer for rendering 3D super resolution images as binned point clouds
+    '''
+
+    def __init__(self, xy_bin_size=10, z_bin_size=50):
+        '''
+        Initialize the point cloud renderer.
+
+        Parameters:
+        -----------
+        xy_bin_size : float
+            Size of each bin in the lateral (XY) dimensions
+        z_bin_size : float
+            Size of each bin in the axial (Z) dimension
+        '''
+        self._xy_bin_size = xy_bin_size
+        self._z_bin_size = z_bin_size
+        self._points = None
+        self._intensities = None
+
+    def _validate_inputs(self, X, Y, Z, Intensity):
+        '''
+        Validate the inputs for rendering.
+        '''
+        if not len(X) == len(Y) == len(Z) == len(Intensity):
+            raise ValueError('The supplied coordinate arrays are of different lengths.')
+
+    def _normalize_xy(self, X, Y):
+        '''
+        Normalize XY coordinates to start from zero.
+        '''
+        x_min, y_min = np.min(X), np.min(Y)
+
+        if x_min < 0:
+            X = X - x_min
+        if y_min < 0:
+            Y = Y - y_min
+
+        return X, Y
+
+    def render(self, X, Y, Z, Intensity, shape=None):
+        '''
+        Generates a point cloud from 3D single-molecule localizations using binning.
+
+        Parameters:
+        -----------
+        X : np.ndarray
+            Array of X coordinates for the localizations.
+        Y : np.ndarray
+            Array of Y coordinates for the localizations.
+        Z : np.ndarray
+            Array of Z coordinates for the localizations (preserving the zero reference)
+        Intensity : np.ndarray
+            Array of intensity values corresponding to each localization.
+        shape : tuple[int, int, int], optional
+            Number of bins in each dimension as (depth, height, width).
+            Defaults to None.
+
+        Returns:
+        --------
+        points : np.ndarray
+            Nx3 array of point coordinates representing non-zero bins
+        intensities : np.ndarray
+            N array of intensity values for each point
+        metadata : dict
+            Dictionary containing bin sizes and coordinate ranges
+        '''
+        self._validate_inputs(X, Y, Z, Intensity)
+        X, Y = self._normalize_xy(X, Y)
+
+        # Calculate bin edges
+        if shape is None:
+            x_max = np.max(X) + 2 * self._xy_bin_size
+            y_max = np.max(Y) + 2 * self._xy_bin_size
+
+            # For Z, calculate number of bins needed on each side of zero
+            z_min, z_max = np.min(Z), np.max(Z)
+
+            # Handle cases where all values fall within one bin centered at zero
+            if -self._z_bin_size / 2 <= z_min and z_max <= self._z_bin_size / 2:
+                n_bins_below = 1
+                n_bins_above = (
+                    1  # Create one bin centered at zero [-bin_size/2, +bin_size/2]
+                )
+            else:
+                # Calculate bins needed on each side, accounting for half bins
+                n_bins_below = int(
+                    np.ceil((-z_min + self._z_bin_size / 2) / self._z_bin_size)
+                )
+                n_bins_above = int(
+                    np.ceil((z_max + self._z_bin_size / 2) / self._z_bin_size)
+                )
+
+            n_bins_x = int(np.ceil(x_max / self._xy_bin_size))
+            n_bins_y = int(np.ceil(y_max / self._xy_bin_size))
+            n_bins_z = n_bins_below + n_bins_above
+            shape = (n_bins_z, n_bins_y, n_bins_x)
+
+        # Create bin edges
+        bin_edges_x = np.linspace(0, shape[2] * self._xy_bin_size, shape[2] + 1)
+        bin_edges_y = np.linspace(0, shape[1] * self._xy_bin_size, shape[1] + 1)
+        bin_edges_z = np.arange(
+            -n_bins_below * self._z_bin_size
+            - self._z_bin_size / 2,  # start at first bin edge
+            (n_bins_above + 1) * self._z_bin_size
+            - self._z_bin_size / 2,  # end at last bin edge
+            self._z_bin_size,
+        )
+
+        # Compute point cloud histogram
+        points, intensities = compute_point_cloud_histogram(
+            np.c_[X, Y, Z, Intensity], bin_edges_x, bin_edges_y, bin_edges_z
+        )
+
+        self._points = points
+        self._intensities = intensities
+
+        metadata = {
+            'bin_size': {
+                'x': self._xy_bin_size,
+                'y': self._xy_bin_size,
+                'z': self._z_bin_size,
+            },
+            'coordinates': {
+                'z_min': bin_edges_z[0],
+                'z_max': bin_edges_z[-1],
+            },
+            'point_count': len(points),
+        }
+
+        return points, intensities, metadata
+
+    def from_array(self, data: np.ndarray, shape=None):
+        '''
+        Renders a point cloud from an array of localizations.
+
+        Parameters:
+        -----------
+        data : np.ndarray
+            Array with columns (X, Y, Z, Intensity)
+        shape : tuple[int, int, int], optional
+            Number of bins in each dimension (depth, height, width), by default None
+
+        Returns:
+        --------
+        points : np.ndarray
+            Nx3 array of point coordinates
+        intensities : np.ndarray
+            N array of intensity values
+        metadata : dict
+            Dictionary containing bin sizes and coordinate ranges
+        '''
+        return self.render(data[:, 0], data[:, 1], data[:, 2], data[:, 3], shape)
+
+
+@numba.jit(nopython=True)
+def normalize_intensities(intensities):
+    '''
+    Normalize intensity values to range [0,1] using Numba acceleration.
+    '''
+    min_val = np.min(intensities)
+    max_val = np.max(intensities)
+    return (intensities - min_val) / (max_val - min_val)

microEye/analysis/rendering/core.py

@@ -0,0 +1,47 @@
+import numba
+import numpy as np
+
+
+def model(xc, yc, sigma_x, sigma_y, flux, offset, X, Y):
+    '''
+    2D Gaussian model function.
+
+    Parameters
+    ----------
+    xc : float
+        x-coordinate of the center
+    yc : float
+        y-coordinate of the center
+    sigma_x : float
+        Standard deviation in x-direction
+    sigma_y : float
+        Standard deviation in y-direction
+    flux : float
+        Total flux
+    offset : float
+        Offset
+    X : np.ndarray
+        X-coordinate grid
+    Y : np.ndarray
+        Y-coordinate grid
+    '''
+    y_gauss = gauss_1d(Y[:, 0], yc, sigma_y)
+    x_gauss = gauss_1d(X[0, :], xc, sigma_x)
+    return flux * np.einsum('i,j->ij', y_gauss, x_gauss) + offset
+
+@numba.njit(cache=True)
+def gauss_1d(x: np.ndarray, mu: np.ndarray, sigma: np.ndarray):
+    '''
+    1D Gaussian function.
+
+    Parameters
+    ----------
+    x : np.ndarray
+        x-coordinate
+    mu : float
+        Mean
+    sigma : float
+        Standard deviation
+    '''
+    return 1 / (np.sqrt(2 * np.pi) * sigma) * \
+           np.exp(-0.5 * (x - mu)**2 / sigma**2)