sigima 0.0.1.dev0__py3-none-any.whl → 1.0.0__py3-none-any.whl

sigima/tools/image/fourier.py

@@ -0,0 +1,260 @@
+# Copyright (c) DataLab Platform Developers, BSD 3-Clause license, see LICENSE file.
+
+"""
+Fourier analysis module
+-----------------------
+
+This module provides 2D Fourier transform utilities and frequency domain operations
+for image processing.
+
+Features include:
+
+- 2D FFT/IFFT functions with optional shifting
+- Spectral analysis (magnitude spectrum, phase spectrum, power spectral density)
+- Frequency domain filtering and deconvolution
+- Zero padding utilities for FFT operations
+
+These tools support various frequency domain image processing operations
+including filtering, spectral analysis, and deconvolution.
+"""
+
+from __future__ import annotations
+
+import warnings
+
+import numpy as np
+import scipy.signal as sps
+
+from sigima.tools.checks import check_2d_array, normalize_kernel
+
+# pylint: disable=invalid-name  # Allows short reference names like x, y, ...
+
+
+@check_2d_array
+def fft2d(z: np.ndarray, shift: bool = True) -> np.ndarray:
+    """Compute FFT of complex array `z`
+
+    Args:
+        z: Input data
+        shift: Shift zero frequency to center (default: True)
+
+    Returns:
+        FFT of input data
+    """
+    z1 = np.fft.fft2(z)
+    if shift:
+        z1 = np.fft.fftshift(z1)
+    return z1
+
+
+@check_2d_array
+def ifft2d(z: np.ndarray, shift: bool = True) -> np.ndarray:
+    """Compute inverse FFT of complex array `z`
+
+    Args:
+        z: Input data
+        shift: Shift zero frequency to center (default: True)
+
+    Returns:
+        Inverse FFT of input data
+    """
+    if shift:
+        z = np.fft.ifftshift(z)
+    z1 = np.fft.ifft2(z)
+    return z1
+
+
+@check_2d_array
+def magnitude_spectrum(z: np.ndarray, log_scale: bool = False) -> np.ndarray:
+    """Compute magnitude spectrum of complex array `z`
+
+    Args:
+        z: Input data
+        log_scale: Use log scale (default: False)
+
+    Returns:
+        Magnitude spectrum of input data
+    """
+    z1 = np.abs(fft2d(z))
+    if log_scale:
+        z1 = 20 * np.log10(z1.clip(1e-10))
+    return z1
+
+
+@check_2d_array
+def phase_spectrum(z: np.ndarray) -> np.ndarray:
+    """Compute phase spectrum of complex array `z`
+
+    Args:
+        z: Input data
+
+    Returns:
+        Phase spectrum of input data (in degrees)
+    """
+    return np.rad2deg(np.angle(fft2d(z)))
+
+
+@check_2d_array
+def psd(z: np.ndarray, log_scale: bool = False) -> np.ndarray:
+    """Compute power spectral density of complex array `z`
+
+    Args:
+        z: Input data
+        log_scale: Use log scale (default: False)
+
+    Returns:
+        Power spectral density of input data
+    """
+    z1 = np.abs(fft2d(z)) ** 2
+    if log_scale:
+        z1 = 10 * np.log10(z1.clip(1e-10))
+    return z1
+
+
+@check_2d_array
+def gaussian_freq_filter(
+    data: np.ndarray, f0: float = 0.1, sigma: float = 0.05
+) -> np.ndarray:
+    """
+    Apply a 2D Gaussian bandpass filter in the frequency domain to an image.
+
+    This function performs a 2D Fast Fourier Transform (FFT) on the input image,
+    applies a Gaussian filter centered at frequency `f0` with standard deviation `sigma`
+    (both expressed in cycles per pixel), and then transforms the result back to the
+    spatial domain.
+
+    Args:
+        data: Input image data.
+        f0: Center frequency of the Gaussian filter (cycles/pixel).
+        sigma: Standard deviation of the Gaussian filter (cycles/pixel).
+
+    Returns:
+        The filtered image.
+    """
+    n, m = data.shape
+    fx = np.fft.fftshift(np.fft.fftfreq(m, d=1))
+    fy = np.fft.fftshift(np.fft.fftfreq(n, d=1))
+    fx_grid, fy_grid = np.meshgrid(fx, fy)
+    freq_radius = np.hypot(fx_grid, fy_grid)
+
+    # Create the 2D Gaussian bandpass filter
+    gaussian_filter = np.exp(-0.5 * ((freq_radius - f0) / sigma) ** 2)
+
+    # Apply FFT, filter in frequency domain, and inverse FFT
+    fft_data = fft2d(data, shift=True)
+    filtered_fft = fft_data * gaussian_filter
+    zout = ifft2d(filtered_fft, shift=True)
+    return zout.real
+
+
+@check_2d_array(non_constant=True)
+def convolve(
+    data: np.ndarray,
+    kernel: np.ndarray,
+    normalize_kernel_flag: bool = True,
+) -> np.ndarray:
+    """
+    Perform 2D convolution with a kernel using scipy.signal.convolve.
+
+    This function adds optional kernel normalization to the standard scipy convolution.
+
+    Args:
+        data: Input image (2D array).
+        kernel: Convolution kernel.
+        normalize_kernel_flag: If True, normalize kernel so that ``kernel.sum() == 1``
+            to preserve image brightness.
+
+    Returns:
+        Convolved image (same shape as input).
+
+    Raises:
+        ValueError: If kernel is empty or null.
+    """
+    if kernel.size == 0 or not np.any(kernel):
+        raise ValueError("Convolution kernel cannot be null.")
+
+    # Optionally normalize the kernel
+    if normalize_kernel_flag:
+        kernel = normalize_kernel(kernel)
+
+    # Use scipy.signal.convolve with 'same' mode to preserve image size
+    return sps.convolve(data, kernel, mode="same", method="auto")
+
+
+@check_2d_array(non_constant=True)
+def deconvolve(
+    data: np.ndarray,
+    kernel: np.ndarray,
+    reg: float = 0.0,
+    boundary: str = "edge",
+    normalize_kernel_flag: bool = True,
+) -> np.ndarray:
+    """
+    Perform 2D FFT deconvolution with correct 'same' geometry (no shift).
+
+    The kernel (PSF) must be centered (impulse at center for identity kernel).
+    Odd kernel sizes are recommended.
+
+    Args:
+        data: Input image (2D array).
+        kernel: Point Spread Function (PSF), centered.
+        reg: Regularization parameter (if >0, Wiener/Tikhonov inverse:
+         ``H* / (|H|^2 + reg))``.
+        boundary: Padding mode ('edge' for constant plateau,
+         'reflect' for symmetric mirror).
+        normalize_kernel_flag: If True, normalize kernel so that ``kernel.sum() == 1``
+            to preserve image brightness.
+
+    Returns:
+        Deconvolved image (same shape as input).
+
+    Raises:
+        ValueError: If kernel is empty or null.
+    """
+    if kernel.size == 0 or not np.any(kernel):
+        raise ValueError("Deconvolution kernel cannot be null.")
+
+    # Optionally normalize the kernel
+    if normalize_kernel_flag:
+        kernel = normalize_kernel(kernel)
+
+    H, W = data.shape
+    kh, kw = kernel.shape
+
+    if kh % 2 == 0 or kw % 2 == 0:
+        # Warning for even-sized kernels (off-by-one in centered FFT)
+        warnings.warn(
+            "Deconvolution kernel should have odd dimensions for centered FFT."
+        )
+
+    # Symmetric padding for centered 'same' convolution
+    top = kh // 2
+    bottom = kh - 1 - top
+    left = kw // 2
+    right = kw - 1 - left
+    data_pad = np.pad(data, ((top, bottom), (left, right)), mode=boundary)
+    Hp, Wp = data_pad.shape  # = H+kh-1, W+kw-1
+
+    # Centered PSF to OTF conversion (avoid off-by-one for even sizes)
+    kernel_pad = np.zeros_like(data_pad, dtype=float)
+    r0 = Hp // 2 - kh // 2
+    c0 = Wp // 2 - kw // 2
+    kernel_pad[r0 : r0 + kh, c0 : c0 + kw] = kernel
+    H_otf = np.fft.fft2(np.fft.ifftshift(kernel_pad))  # center → (0,0)
+
+    # FFT of padded image (no shift)
+    Z = np.fft.fft2(data_pad)
+
+    # Frequency domain inversion
+    if reg > 0.0:
+        Hc = np.conj(H_otf)
+        X = Z * Hc / (np.abs(H_otf) ** 2 + float(reg))
+    else:
+        eps = 1e-12
+        X = Z / (H_otf + eps)
+
+    data_true_pad = np.fft.ifft2(X).real
+
+    # Central crop to restore original geometry
+    out = data_true_pad[top : top + H, left : left + W]
+    return out

sigima/tools/image/geometry.py

@@ -0,0 +1,190 @@
+# Copyright (c) DataLab Platform Developers, BSD 3-Clause license, see LICENSE file.
+
+"""
+Geometric analysis module
+-------------------------
+
+This module provides functions for geometric analysis of images, including
+centroid detection, shape fitting, and spatial measurements.
+
+Features include:
+
+- Various centroid detection algorithms (Fourier-based, projected profile,
+  automatic selection)
+- Enclosing circle calculation for thresholded regions
+- Radial profile extraction around specified centers
+- Absolute level calculation from relative thresholds
+
+These tools support precise geometric measurements and shape analysis
+for scientific and technical image analysis applications.
+"""
+
+from __future__ import annotations
+
+from typing import Literal
+
+import numpy as np
+from skimage import measure
+
+from sigima.tools.checks import check_2d_array
+from sigima.tools.image.preprocessing import get_absolute_level
+
+
+@check_2d_array
+def get_centroid_fourier(data: np.ndarray) -> tuple[float, float]:
+    """Return image centroid using Fourier algorithm
+
+    Args:
+        data: Input data
+
+    Returns:
+        Centroid coordinates (row, col)
+    """
+    # Fourier transform method as discussed by Weisshaar et al.
+    # (http://www.mnd-umwelttechnik.fh-wiesbaden.de/pig/weisshaar_u5.pdf)
+    rows, cols = data.shape
+    if rows == 1 or cols == 1:
+        return 0, 0
+
+    i = np.arange(0, rows).reshape(1, rows)
+    sin_a = np.sin((i - 1) * 2 * np.pi / (rows - 1)).T
+    cos_a = np.cos((i - 1) * 2 * np.pi / (rows - 1)).T
+
+    j = np.arange(0, cols).reshape(cols, 1)
+    sin_b = np.sin((j - 1) * 2 * np.pi / (cols - 1)).T
+    cos_b = np.cos((j - 1) * 2 * np.pi / (cols - 1)).T
+
+    a = np.nansum((cos_a * data))
+    b = np.nansum((sin_a * data))
+    c = np.nansum((data * cos_b))
+    d = np.nansum((data * sin_b))
+
+    rphi = (0 if b > 0 else 2 * np.pi) if a > 0 else np.pi
+    cphi = (0 if d > 0 else 2 * np.pi) if c > 0 else np.pi
+
+    if a * c == 0.0:
+        return 0, 0
+
+    row = (np.arctan(b / a) + rphi) * (rows - 1) / (2 * np.pi) + 1
+    col = (np.arctan(d / c) + cphi) * (cols - 1) / (2 * np.pi) + 1
+
+    row = np.nan if row is np.ma.masked else row
+    col = np.nan if col is np.ma.masked else col
+
+    return row, col
+
+
+@check_2d_array
+def get_projected_profile_centroid(
+    data: np.ndarray, smooth_ratio: float = 1 / 40, method: str = "median"
+) -> tuple[float, float]:
+    """
+    Estimate centroid from smoothed 1D projections.
+
+    Args:
+        data: 2D image array
+        smooth_ratio: Ratio of smoothing window size (default: 1/40)
+        method: 'median' (default) or 'barycenter'
+
+    Returns:
+        (y, x) coordinates
+    """
+    x_profile = data.sum(axis=0)
+    y_profile = data.sum(axis=1)
+    window_size = max(1, int(min(data.shape) * smooth_ratio))
+    kernel = np.ones(window_size) / window_size
+    x_profile = np.convolve(x_profile, kernel, mode="same")
+    y_profile = np.convolve(y_profile, kernel, mode="same")
+    x_profile -= np.min(x_profile)
+    y_profile -= np.min(y_profile)
+
+    if method == "median":
+        x_integral = np.cumsum(x_profile)
+        y_integral = np.cumsum(y_profile)
+        x_center = np.interp(
+            0.5 * x_integral[-1], x_integral, np.arange(len(x_integral))
+        )
+        y_center = np.interp(
+            0.5 * y_integral[-1], y_integral, np.arange(len(y_integral))
+        )
+    elif method == "barycenter":  # pragma: no cover
+        #  (ignored for coverage because median gives better results)
+        x_center = np.sum(np.arange(len(x_profile)) * x_profile) / np.sum(x_profile)
+        y_center = np.sum(np.arange(len(y_profile)) * y_profile) / np.sum(y_profile)
+    else:
+        raise ValueError("Unknown method: choose 'median' or 'barycenter'")
+
+    return float(y_center), float(x_center)
+
+
+@check_2d_array
+def get_centroid_auto(
+    data: np.ndarray,
+    return_method: bool = False,
+) -> tuple[float, float] | tuple[float, float, Literal["fourier", "skimage"]]:
+    """
+    Automatically select the most reliable centroid estimation method:
+    - Prefer Fourier if it is more consistent with the projected median.
+    - Fallback to scikit-image centroid if Fourier is less coherent.
+
+    Args:
+        data: 2D image array.
+        return_method: If True, also return the name of the selected method.
+
+    Returns:
+        (row, col): Estimated centroid coordinates (float).
+        Optionally, the selected method as string: "fourier" or "skimage".
+    """
+    try:
+        row_f, col_f = get_centroid_fourier(data)
+    except Exception:  # pylint: disable=broad-except
+        row_f, col_f = float("nan"), float("nan")
+
+    row_m, col_m = get_projected_profile_centroid(data, method="median")
+    row_s, col_s = measure.centroid(data)
+
+    dist_f = np.hypot(row_f - row_m, col_f - col_m)
+    dist_s = np.hypot(row_s - row_m, col_s - col_m)
+
+    if not (np.isnan(row_f) or np.isnan(col_f)) and dist_f < dist_s:
+        result = (row_f, col_f)
+        method = "fourier"
+    else:
+        result = (row_s, col_s)
+        method = "skimage"
+
+    return result + (method,) if return_method else result
+
+
+@check_2d_array(non_constant=True)
+def get_enclosing_circle(
+    data: np.ndarray, level: float = 0.5
+) -> tuple[int, int, float]:
+    """Return (x, y, radius) for the circle contour enclosing image
+    values above threshold relative level (.5 means FWHM)
+
+    Args:
+        data: Input data
+        level: Relative level (default: 0.5)
+
+    Returns:
+        A tuple (x, y, radius)
+
+    Raises:
+        ValueError: No contour was found
+    """
+    data_th = data.copy()
+    data_th[data <= get_absolute_level(data, level)] = 0.0
+    contours = measure.find_contours(data_th)
+    model = measure.CircleModel()
+    result = None
+    max_radius = 1.0
+    for contour in contours:
+        if model.estimate(contour):
+            yc, xc, radius = model.params
+            if radius > max_radius:
+                result = (int(xc), int(yc), radius)
+                max_radius = radius
+    if result is None:
+        raise ValueError("No contour was found")
+    return result

sigima/tools/image/preprocessing.py

@@ -0,0 +1,165 @@
+"""
+Signal/Image Preprocessing
+--------------------------
+
+This module contains utility functions for preprocessing and transforming image data:
+
+- Binning and scaling operations
+- Zero padding for Fourier analysis
+- Utility functions for data transformation
+
+.. note::
+    All functions in this module are also available directly in the parent
+    `sigima.tools.image` package.
+"""
+
+from __future__ import annotations
+
+from typing import Literal
+
+import numpy as np
+import scipy.spatial as spt
+from numpy import ma
+
+from sigima.enums import BinningOperation
+from sigima.tools.checks import check_2d_array
+
+
+def get_absolute_level(data: np.ndarray, level: float) -> float:
+    """Get absolute level from relative level
+
+    Args:
+        data: Input data
+        level: Relative level (0.0 to 1.0)
+
+    Returns:
+        Absolute level
+
+    Raises:
+        ValueError: If level is not a float between 0.0 and 1.0
+    """
+    if not isinstance(level, (int, float)) or level < 0.0 or level > 1.0:
+        raise ValueError("Level must be a number between 0.0 and 1.0")
+    return np.nanmin(data) + level * (np.nanmax(data) - np.nanmin(data))
+
+
+def distance_matrix(coords: list) -> np.ndarray:
+    """Return distance matrix from coords
+
+    Args:
+        coords: List of coordinates
+
+    Returns:
+        Distance matrix
+    """
+    return np.triu(spt.distance.cdist(coords, coords, "euclidean"))
+
+
+@check_2d_array
+def binning(
+    data: np.ndarray,
+    sx: int,
+    sy: int,
+    operation: BinningOperation | str,
+    dtype=None,
+) -> np.ndarray:
+    """Perform image pixel binning
+
+    Args:
+        data: Input data
+        sx: Binning size along x (number of pixels to bin together)
+        sy: Binning size along y (number of pixels to bin together)
+        operation: Binning operation
+        dtype: Output data type (default: None, i.e. same as input)
+
+    Returns:
+        Binned data
+    """
+    # Convert enum to string value if needed
+    if isinstance(operation, BinningOperation):
+        operation = operation.value
+
+    ny, nx = data.shape
+    shape = (ny // sy, sy, nx // sx, sx)
+    try:
+        bdata = data[: ny - ny % sy, : nx - nx % sx].reshape(shape)
+    except ValueError as err:
+        raise ValueError("Binning is not a multiple of image dimensions") from err
+    if operation == "sum":
+        bdata = np.array(bdata, dtype=float).sum(axis=(-1, 1))
+    elif operation == "average":
+        bdata = bdata.mean(axis=(-1, 1))
+    elif operation == "median":
+        bdata = ma.median(bdata, axis=(-1, 1))
+    elif operation == "min":
+        bdata = bdata.min(axis=(-1, 1))
+    elif operation == "max":
+        bdata = bdata.max(axis=(-1, 1))
+    else:
+        valid = ", ".join(op.value for op in BinningOperation)
+        raise ValueError(f"Invalid operation {operation} (valid values: {valid})")
+    return np.array(bdata, dtype=data.dtype if dtype is None else np.dtype(dtype))
+
+
+@check_2d_array(non_constant=True)
+def scale_data_to_min_max(
+    data: np.ndarray, zmin: float | int, zmax: float | int
+) -> np.ndarray:
+    """Scale array `data` to fit [zmin, zmax] dynamic range
+
+    Args:
+        data: Input data
+        zmin: Minimum value of output data
+        zmax: Maximum value of output data
+
+    Returns:
+        Scaled data
+    """
+    dmin, dmax = np.nanmin(data), np.nanmax(data)
+    if dmin == zmin and dmax == zmax:
+        return data
+    fdata = np.array(data, dtype=float)
+    fdata -= dmin
+    fdata *= float(zmax - zmin) / (dmax - dmin)
+    fdata += float(zmin)
+    return np.array(fdata, data.dtype)
+
+
+@check_2d_array
+def zero_padding(
+    data: np.ndarray,
+    rows: int = 0,
+    cols: int = 0,
+    position: Literal["bottom-right", "around"] = "bottom-right",
+) -> np.ndarray:
+    """
+    Zero-pad a 2D image by adding rows and/or columns.
+
+    Args:
+        data: 2D input image (grayscale)
+        rows: Number of rows to add in total (default: 0)
+        cols: Number of columns to add in total (default: 0)
+        position: Padding placement strategy:
+            - "bottom-right": all padding is added to the bottom and right
+            - "around": padding is split equally on top/bottom and left/right
+
+    Returns:
+        The padded 2D image as a NumPy array.
+
+    Raises:
+        ValueError: If the input is not a 2D array or if padding values are negative.
+    """
+    if rows < 0 or cols < 0:
+        raise ValueError("Padding values must be non-negative")
+
+    if position == "bottom-right":
+        pad_width = ((0, rows), (0, cols))
+    elif position == "around":
+        pad_width = (
+            (rows // 2, rows - rows // 2),
+            (cols // 2, cols - cols // 2),
+        )
+    else:
+        raise ValueError(f"Invalid position: {position}")
+
+    return np.pad(data, pad_width, mode="constant", constant_values=0)

sigima/tools/signal/__init__.py

@@ -0,0 +1,86 @@
+"""
+Signal Processing Tools (:mod:`sigima.tools.signal`)
+----------------------------------------------------
+
+This package contains signal processing tools, which are organized into subpackages
+according to their purpose:
+
+- :mod:`sigima.tools.signal.dynamic`: Dynamic parameter extraction
+- :mod:`sigima.tools.signal.features`: Feature extraction algorithms
+- :mod:`sigima.tools.signal.pulse`: Curve fitting models
+- :mod:`sigima.tools.signal.fourier`: Fourier analysis algorithms
+- :mod:`sigima.tools.signal.interpolation`: Interpolation algorithms
+- :mod:`sigima.tools.signal.peakdetection`: Peak detection algorithms
+- :mod:`sigima.tools.signal.pulse`: Pulse analysis algorithms
+- :mod:`sigima.tools.signal.scaling`: Scaling algorithms
+- :mod:`sigima.tools.signal.stability`: Stability analysis algorithms
+- :mod:`sigima.tools.signal.windowing`: Windowing algorithms
+
+
+Dynamic Parameter Extraction
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. automodule:: sigima.tools.signal.dynamic
+   :members:
+
+Feature Extraction Algorithms
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. automodule:: sigima.tools.signal.features
+   :members:
+
+Filtering Functions
+^^^^^^^^^^^^^^^^^^^
+
+.. automodule:: sigima.tools.signal.filtering
+   :members:
+
+Curve Fitting Models
+^^^^^^^^^^^^^^^^^^^^
+
+.. automodule:: sigima.tools.signal.fitting
+   :members:
+
+Fourier Analysis Algorithms
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. automodule:: sigima.tools.signal.fourier
+   :members:
+
+Interpolation Algorithms
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. automodule:: sigima.tools.signal.interpolation
+   :members:
+
+Peak Detection Algorithms
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. automodule:: sigima.tools.signal.peakdetection
+   :members:
+
+Pulse Analysis Algorithms
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. automodule:: sigima.tools.signal.pulse
+   :members:
+
+Scaling Algorithms
+^^^^^^^^^^^^^^^^^^
+
+.. automodule:: sigima.tools.signal.scaling
+   :members:
+
+Stability Analysis Algorithms
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. automodule:: sigima.tools.signal.stability
+   :members:
+
+Windowing Algorithms
+^^^^^^^^^^^^^^^^^^^^
+
+.. automodule:: sigima.tools.signal.windowing
+   :members:
+
+"""