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

sigima/tools/__init__.py

@@ -0,0 +1,59 @@
+"""
+Tools (:mod:`sigima.tools`)
+---------------------------
+
+This package contains functions operating on NumPy arrays that are intended to be
+used in Sigima computation functions. These functions are complementary to the
+algorithms provided by external libraries such as SciPy, NumPy, and scikit-image.
+
+Even though these functions are primarily designed to be used in the Sigima pipeline,
+they can also be used independently. They provide a wide range of features but are
+not exhaustive due to the vast number of algorithms already available in the
+scientific Python ecosystem.
+
+.. seealso::
+
+    The :mod:`sigima.proc` module contains the Sigima computation functions that
+    operate on signal and image objects (i.e. :class:`sigima.objects.SignalObj` and
+    :class:`sigima.objects.ImageObj`, defined in the :mod:`sigima.objects` package).
+
+These tools are organized in subpackages according to their purpose. The following
+subpackages are available:
+
+- :mod:`sigima.tools.checks`: Input data checks for all tools
+- :mod:`sigima.tools.signal`: Signal processing tools
+- :mod:`sigima.tools.image`: Image processing tools
+- :mod:`sigima.tools.datatypes`: Data type conversion tools
+- :mod:`sigima.tools.coordinates`: Coordinate conversion tools
+
+Check functions
+^^^^^^^^^^^^^^^
+
+.. automodule:: sigima.tools.checks
+   :members:
+
+Signal Processing Tools
+^^^^^^^^^^^^^^^^^^^^^^^
+
+.. automodule:: sigima.tools.signal
+   :members:
+
+Image Processing Tools
+^^^^^^^^^^^^^^^^^^^^^^
+
+.. automodule:: sigima.tools.image
+   :members:
+
+Data Type Conversion Tools
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. automodule:: sigima.tools.datatypes
+   :members:
+
+Coordinate Conversion Tools
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. automodule:: sigima.tools.coordinates
+   :members:
+
+"""

sigima/tools/checks.py

@@ -0,0 +1,290 @@
+# Copyright (c) DataLab Platform Developers, BSD 3-Clause license, see LICENSE file.
+
+"""
+.. Checks for 1D and 2D NumPy arrays used in tools (:mod:`sigima.tools.checks`).
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from functools import wraps
+from typing import Any, Callable
+
+import numpy as np
+
+
+@dataclass(frozen=True)
+class ArrayValidationRules:
+    """Hold 1-D array validation rules."""
+
+    #: Label used in error messages (e.g., "x" or "y")
+    label: str
+    #: Whether to enforce 1-D.
+    require_1d: bool = True
+    #: Check minimum size
+    min_size: int | None = None
+    #: Expected dtype (np.issubdtype). Use None to skip.
+    dtype: type | None = None
+    #: Whether to enforce finite values only.
+    finite_only: bool = False
+    #: Whether to enforce non-decreasing order.
+    sorted_: bool = False
+    #: Whether to enforce constant spacing (within rtol).
+    evenly_spaced: bool = False
+    #: Relative tolerance for regular spacing.
+    rtol: float = 1e-5
+
+
+def _validate_array_1d(arr: np.ndarray, *, rules: ArrayValidationRules) -> None:
+    """Validate a single 1D NumPy array according to the provided rules.
+
+    Args:
+        arr: Array to validate.
+        rules: Validation rules to apply.
+
+    Raises:
+        ValueError: If shape constraint is violated.
+        ValueError: If size constraint is violated.
+        ValueError: If finite constraint is violated.
+        ValueError: If order constraint is violated.
+        ValueError: If spacing constraint is violated.
+        TypeError: If dtype does not match.
+    """
+    if rules.require_1d and arr.ndim != 1:
+        raise ValueError(f"{rules.label} must be 1-D.")
+    if rules.min_size is not None and arr.size < rules.min_size:
+        raise ValueError(f"{rules.label} must have at least {rules.min_size} elements.")
+    if rules.dtype is not None and not np.issubdtype(arr.dtype, rules.dtype):
+        raise TypeError(
+            f"{rules.label} must be of type {rules.dtype}, but got {arr.dtype}."
+        )
+    if rules.finite_only and not np.all(np.isfinite(arr)):
+        raise ValueError(f"{rules.label} must contain only finite values.")
+    if rules.sorted_ and arr.size > 1 and not np.all(np.diff(arr) > 0.0):
+        raise ValueError(f"{rules.label} must be sorted in ascending order.")
+    if rules.evenly_spaced and arr.size > 1:
+        dx = np.diff(arr)
+        if not np.allclose(dx, np.mean(dx), rtol=rules.rtol):
+            raise ValueError(f"{rules.label} must be evenly spaced.")
+
+
+def check_1d_array(
+    func: Callable[..., Any] | None = None,
+    *,
+    require_1d: bool = True,
+    min_size: int | None = None,
+    dtype: type | None = np.inexact,
+    finite_only: bool = False,
+    sorted_: bool = False,
+    evenly_spaced: bool = False,
+    rtol: float = 1e-5,
+    label: str = "array",
+) -> Callable:
+    """Decorator to check a single 1D NumPy array.
+
+    Can be used with or without parentheses.
+
+    Args:
+        require_1d: Whether to check if the array is 1-D.
+        min_size: Minimum size of the array.
+        dtype: Expected dtype of the array (np.issubdtype). Use None to skip.
+        finite_only: Whether to check if the array contains only finite values.
+        sorted_: Whether to check if the array is sorted in ascending order.
+        evenly_spaced: Whether to check if the array is evenly spaced.
+        rtol: Relative tolerance for regular spacing.
+        label: Label for error messages (e.g., "x", "y").
+
+    Returns:
+        Decorated function with pre-checks on the single array.
+    """
+
+    def decorator(inner_func: Callable[..., Any]) -> Callable[..., Any]:
+        @wraps(inner_func)
+        def wrapper(arr: np.ndarray, *args: Any, **kwargs: Any) -> Any:
+            _validate_array_1d(
+                arr,
+                rules=ArrayValidationRules(
+                    label=label,
+                    require_1d=require_1d,
+                    min_size=min_size,
+                    dtype=dtype,
+                    finite_only=finite_only,
+                    sorted_=sorted_,
+                    evenly_spaced=evenly_spaced,
+                    rtol=rtol,
+                ),
+            )
+            return inner_func(arr, *args, **kwargs)
+
+        return wrapper
+
+    if func is not None:
+        return decorator(func)
+    return decorator
+
+
+def check_1d_arrays(
+    func: Callable[..., Any] | None = None,
+    *,
+    x_require_1d: bool = True,
+    x_min_size: int | None = None,
+    x_dtype: type | None = np.floating,
+    x_finite_only: bool = False,
+    x_sorted: bool = False,
+    x_evenly_spaced: bool = False,
+    y_require_1d: bool = True,
+    y_min_size: int | None = None,
+    y_dtype: type | None = np.inexact,
+    y_finite_only: bool = False,
+    same_size: bool = True,
+    rtol: float = 1e-5,
+) -> Callable:
+    """Decorator to check paired 1D NumPy arrays (x, y).
+
+    Can be used with or without parentheses.
+
+    Args:
+        func: Function to decorate.
+        x_require_1d: Whether to check if x is 1-D.
+        x_min_size: Minimum size of x.
+        x_dtype: Expected dtype of x (np.issubdtype). Use None to skip.
+        x_finite_only: Whether to check if x contains only finite values.
+        x_sorted: Whether to check if x is sorted in ascending order.
+        x_evenly_spaced: Whether to check if x is evenly spaced.
+        y_require_1d: Whether to check if y is 1-D.
+        y_min_size: Minimum size of y.
+        y_dtype: Expected dtype of y (np.issubdtype). Use None to skip.
+        y_finite_only: Whether to check if y contains only finite values.
+        same_size: Whether to check that x and y have the same size.
+        rtol: Relative tolerance for regular spacing (used for x).
+
+    Returns:
+        Decorated function with pre-checks on x/y.
+    """
+
+    def decorator(inner_func: Callable[..., Any]) -> Callable[..., Any]:
+        @wraps(inner_func)
+        def wrapper(x: np.ndarray, y: np.ndarray, *args: Any, **kwargs: Any) -> Any:
+            _validate_array_1d(
+                x,
+                rules=ArrayValidationRules(
+                    label="x",
+                    require_1d=x_require_1d,
+                    min_size=x_min_size,
+                    dtype=x_dtype,
+                    finite_only=x_finite_only,
+                    sorted_=x_sorted,
+                    evenly_spaced=x_evenly_spaced,
+                    rtol=rtol,
+                ),
+            )
+            _validate_array_1d(
+                y,
+                rules=ArrayValidationRules(
+                    label="y",
+                    require_1d=y_require_1d,
+                    min_size=y_min_size,
+                    dtype=y_dtype,
+                    finite_only=y_finite_only,
+                    sorted_=False,
+                    evenly_spaced=False,
+                    rtol=rtol,
+                ),
+            )
+            if same_size and x.size != y.size:
+                raise ValueError("x and y must have the same size.")
+            return inner_func(x, y, *args, **kwargs)
+
+        return wrapper
+
+    if func is not None:
+        return decorator(func)
+    return decorator
+
+
+def check_2d_array(
+    func: Callable[..., Any] | None = None,
+    *,
+    ndim: int = 2,
+    dtype: type | None = None,
+    non_constant: bool = False,
+    finite_only: bool = False,
+) -> Callable:
+    """
+    Decorator to check input for functions operating on 2D NumPy arrays (e.g. images).
+
+    Can be used with parentheses:
+
+    .. code-block:: python
+
+        @check_2d_array(ndim=3, dtype=np.uint8)
+        def process_image(image: np.ndarray) -> np.ndarray:
+            # Process the image
+            return image
+
+    Or without parentheses (default arguments):
+
+    .. code-block:: python
+
+        @check_2d_array
+        def process_image(image: np.ndarray) -> np.ndarray:
+            # Process the image
+            return image
+
+    Args:
+        ndim: Expected number of dimensions.
+        dtype: Expected dtype.
+        non_constant: Whether to check that the array has dynamic range.
+        finite_only: Whether to check that all values are finite.
+
+    Returns:
+        Decorated function with pre-checks on data.
+    """
+
+    def decorator(inner_func: Callable[..., Any]) -> Callable[..., Any]:
+        @wraps(inner_func)
+        def wrapper(data: np.ndarray, *args: Any, **kwargs: Any) -> Any:
+            # === Check input array
+            if data.ndim != ndim:
+                raise ValueError(f"Input array must be {ndim}D, got {data.ndim}D.")
+            if dtype is not None and not np.issubdtype(data.dtype, dtype):
+                raise TypeError(
+                    f"Input array must be of type {dtype}, got {data.dtype}."
+                )
+            if non_constant:
+                dmin, dmax = np.nanmin(data), np.nanmax(data)
+                if dmin == dmax:
+                    raise ValueError("Input array has no dynamic range.")
+            if finite_only and not np.all(np.isfinite(data)):
+                raise ValueError("Input array contains non-finite values.")
+            # === Call the original function
+            return inner_func(data, *args, **kwargs)
+
+        return wrapper
+
+    if func is not None:
+        # Usage: `@check_2d_array`
+        return decorator(func)
+    # Usage: `@check_2d_array(...)`
+    return decorator
+
+
+def normalize_kernel(kernel: np.ndarray) -> np.ndarray:
+    """Normalize a convolution/deconvolution kernel if needed.
+
+    This utility function can normalize the kernel to sum to 1.0.
+
+    Args:
+        kernel: The kernel array to normalize.
+
+    Returns:
+        The normalized kernel if it's not already normalized and if its sum is not
+        zero, otherwise the original kernel.
+
+    Note:
+        A kernel is considered normalized if ``np.isclose(sum(kernel), 1.0)``.
+    """
+    kernel_sum = np.sum(kernel)
+    if not np.isclose(kernel_sum, 1.0) and kernel_sum != 0.0:
+        return kernel / kernel_sum
+    return kernel

sigima/tools/coordinates.py

@@ -0,0 +1,308 @@
+# Copyright (c) DataLab Platform Developers, BSD 3-Clause license, see LICENSE file.
+
+"""
+.. Coordinates Algorithms (see parent package :mod:`sigima.tools`)
+"""
+
+# pylint: disable=invalid-name  # Allows short reference names like x, y, ...
+
+from __future__ import annotations
+
+from typing import Literal
+
+import numpy as np
+
+from sigima.tools.checks import check_1d_arrays
+
+
+def circle_to_diameter(
+    xc: float, yc: float, r: float
+) -> tuple[float, float, float, float]:
+    """Convert circle center and radius to X diameter coordinates
+
+    Args:
+        xc: Circle center X coordinate
+        yc: Circle center Y coordinate
+        r: Circle radius
+
+    Returns:
+        tuple: Circle X diameter coordinates
+    """
+    return xc - r, yc, xc + r, yc
+
+
+def array_circle_to_diameter(data: np.ndarray) -> np.ndarray:
+    """Convert circle center and radius to X diameter coordinates (array version)
+
+    Args:
+        data: Circle center and radius, in the form of a 2D array (N, 3)
+
+    Returns:
+        Circle X diameter coordinates, in the form of a 2D array (N, 4)
+    """
+    xc, yc, r = data[:, 0], data[:, 1], data[:, 2]
+    x_start = xc - r
+    x_end = xc + r
+    result = np.column_stack((x_start, yc, x_end, yc)).astype(float)
+    return result
+
+
+def circle_to_center_radius(
+    x0: float, y0: float, x1: float, y1: float
+) -> tuple[float, float, float]:
+    """Convert circle X diameter coordinates to center and radius
+
+    Args:
+        x0: Diameter start X coordinate
+        y0: Diameter start Y coordinate
+        x1: Diameter end X coordinate
+        y1: Diameter end Y coordinate
+
+    Returns:
+        tuple: Circle center and radius
+    """
+    xc, yc = (x0 + x1) / 2, (y0 + y1) / 2
+    r = np.sqrt((x1 - x0) ** 2 + (y1 - y0) ** 2) / 2
+    return xc, yc, r
+
+
+def array_circle_to_center_radius(data: np.ndarray) -> np.ndarray:
+    """Convert circle X diameter coordinates to center and radius (array version)
+
+    Args:
+        data: Circle X diameter coordinates, in the form of a 2D array (N, 4)
+
+    Returns:
+        Circle center and radius, in the form of a 2D array (N, 3)
+    """
+    x0, y0, x1, y1 = data[:, 0], data[:, 1], data[:, 2], data[:, 3]
+    xc, yc = (x0 + x1) / 2, (y0 + y1) / 2
+    r = np.sqrt((x1 - x0) ** 2 + (y1 - y0) ** 2) / 2
+    result = np.column_stack((xc, yc, r)).astype(float)
+    return result
+
+
+def ellipse_to_diameters(
+    xc: float, yc: float, a: float, b: float, theta: float
+) -> tuple[float, float, float, float, float, float, float, float]:
+    """Convert ellipse center, axes and angle to X/Y diameters coordinates
+
+    Args:
+        xc: Ellipse center X coordinate
+        yc: Ellipse center Y coordinate
+        a: Ellipse half larger axis
+        b: Ellipse half smaller axis
+        theta: Ellipse angle
+
+    Returns:
+        Ellipse X/Y diameters (major/minor axes) coordinates
+    """
+    dxa, dya = a * np.cos(theta), a * np.sin(theta)
+    dxb, dyb = b * np.sin(theta), b * np.cos(theta)
+    x0, y0, x1, y1 = xc - dxa, yc - dya, xc + dxa, yc + dya
+    x2, y2, x3, y3 = xc - dxb, yc - dyb, xc + dxb, yc + dyb
+    return x0, y0, x1, y1, x2, y2, x3, y3
+
+
+def array_ellipse_to_diameters(data: np.ndarray) -> np.ndarray:
+    """Convert ellipse center, axes and angle to X/Y diameters coordinates
+    (array version)
+
+    Args:
+        data: Ellipse center, axes and angle, in the form of a 2D array (N, 5)
+
+    Returns:
+        Ellipse X/Y diameters (major/minor axes) coordinates,
+         in the form of a 2D array (N, 8)
+    """
+    xc, yc, a, b, theta = data[:, 0], data[:, 1], data[:, 2], data[:, 3], data[:, 4]
+    dxa, dya = a * np.cos(theta), a * np.sin(theta)
+    dxb, dyb = b * np.sin(theta), b * np.cos(theta)
+    x0, y0, x1, y1 = xc - dxa, yc - dya, xc + dxa, yc + dya
+    x2, y2, x3, y3 = xc - dxb, yc - dyb, xc + dxb, yc + dyb
+    result = np.column_stack((x0, y0, x1, y1, x2, y2, x3, y3)).astype(float)
+    return result
+
+
+def ellipse_to_center_axes_angle(
+    x0: float,
+    y0: float,
+    x1: float,
+    y1: float,
+    x2: float,
+    y2: float,
+    x3: float,
+    y3: float,
+) -> tuple[float, float, float, float, float]:
+    """Convert ellipse X/Y diameters coordinates to center, axes and angle
+
+    Args:
+        x0: major axis start X coordinate
+        y0: major axis start Y coordinate
+        x1: major axis end X coordinate
+        y1: major axis end Y coordinate
+        x2: minor axis start X coordinate
+        y2: minor axis start Y coordinate
+        x3: minor axis end X coordinate
+        y3: minor axis end Y coordinate
+
+    Returns:
+        Ellipse center, axes and angle
+    """
+    xc, yc = (x0 + x1) / 2, (y0 + y1) / 2
+    a = np.sqrt((x1 - x0) ** 2 + (y1 - y0) ** 2) / 2
+    b = np.sqrt((x3 - x2) ** 2 + (y3 - y2) ** 2) / 2
+    theta = np.arctan2(y1 - y0, x1 - x0)
+    return xc, yc, a, b, theta
+
+
+def array_ellipse_to_center_axes_angle(data: np.ndarray) -> np.ndarray:
+    """Convert ellipse X/Y diameters coordinates to center, axes and angle
+    (array version)
+
+    Args:
+        data: Ellipse X/Y diameters coordinates, in the form of a 2D array (N, 8)
+
+    Returns:
+        Ellipse center, axes and angle, in the form of a 2D array (N, 5)
+    """
+    x0, y0, x1, y1, x2, y2, x3, y3 = (
+        data[:, 0],
+        data[:, 1],
+        data[:, 2],
+        data[:, 3],
+        data[:, 4],
+        data[:, 5],
+        data[:, 6],
+        data[:, 7],
+    )
+    xc, yc = (x0 + x1) / 2, (y0 + y1) / 2
+    a = np.sqrt((x1 - x0) ** 2 + (y1 - y0) ** 2) / 2
+    b = np.sqrt((x3 - x2) ** 2 + (y3 - y2) ** 2) / 2
+    theta = np.arctan2(y1 - y0, x1 - x0)
+    result = np.column_stack((xc, yc, a, b, theta)).astype(float)
+    return result
+
+
+@check_1d_arrays
+def to_polar(
+    x: np.ndarray, y: np.ndarray, unit: Literal["°", "rad"] = "rad"
+) -> tuple[np.ndarray, np.ndarray]:
+    """Convert Cartesian coordinates to polar coordinates.
+
+    Args:
+        x: Cartesian x-coordinate.
+        y: Cartesian y-coordinate.
+        unit: Unit of the angle ("°" or "rad").
+
+    Returns:
+        Polar coordinates (r, theta) where r is the radius and theta is the angle.
+
+    Raises:
+        ValueError: If the unit is not "°" or "rad".
+    """
+    if unit not in ["rad", "°"]:
+        raise ValueError(f"Unit must be radian ('rad') or degree ('°'), got {unit}.")
+    r = np.sqrt(x**2 + y**2)
+    theta = np.arctan2(y, x)
+    if unit == "°":
+        theta = np.rad2deg(theta)
+    return r, theta
+
+
+@check_1d_arrays
+def to_cartesian(
+    r: np.ndarray, theta: np.ndarray, unit: Literal["°", "rad"] = "rad"
+) -> tuple[np.ndarray, np.ndarray]:
+    """Convert polar coordinates to Cartesian coordinates.
+
+    Args:
+        r: Polar radius.
+        theta: Polar angle.
+        unit: Unit of the angle ("°" or "rad").
+
+    Returns:
+        Cartesian coordinates (x, y) where x is the x-coordinate and y is the
+        y-coordinate.
+
+    Raises:
+        ValueError: If the unit is not "°" or "rad".
+        ValueError: If any value of the radius is negative.
+    """
+    if unit not in ["rad", "°"]:
+        raise ValueError(f"Unit must be radian ('rad') or degree ('°'), got {unit}.")
+    if np.any(r < 0.0):
+        raise ValueError("Negative radius values are not allowed.")
+    if unit == "°":
+        theta = np.deg2rad(theta)
+    x = r * np.cos(theta)
+    y = r * np.sin(theta)
+    return x, y
+
+
+def rotate(angle: float) -> np.ndarray:
+    """Return rotation matrix
+
+    Args:
+        angle: Rotation angle (in radians)
+
+    Returns:
+        Rotation matrix
+    """
+    cos_a = np.cos(angle)
+    sin_a = np.sin(angle)
+    return np.array([[cos_a, -sin_a, 0], [sin_a, cos_a, 0], [0, 0, 1]], dtype=float)
+
+
+def colvector(x: float, y: float) -> np.ndarray:
+    """Return vector from coordinates
+
+    Args:
+        x: x-coordinate
+        y: y-coordinate
+
+    Returns:
+        Vector
+    """
+    return np.array([x, y, 1]).T
+
+
+def vector_rotation(theta: float, dx: float, dy: float) -> tuple[float, float]:
+    """Compute theta-rotation on vector
+
+    Args:
+        theta: Rotation angle
+        dx: x-coordinate of vector
+        dy: y-coordinate of vector
+
+    Returns:
+        Tuple of (x, y) coordinates of rotated vector
+    """
+    return (rotate(theta) @ colvector(dx, dy)).ravel()[:2]
+
+
+@check_1d_arrays(x_require_1d=False, y_require_1d=False)
+def polar_to_complex(
+    r: np.ndarray, theta: np.ndarray, unit: Literal["°", "rad"] = "rad"
+) -> np.ndarray:
+    """Convert polar coordinates to complex number.
+
+    Args:
+        r: Polar radius.
+        theta: Polar angle.
+        unit: Unit of the angle ("°" or "rad").
+
+    Returns:
+        Complex numbers corresponding to the polar coordinates.
+
+    Raises:
+        ValueError: If the unit is not "°" or "rad".
+        ValueError: If any value of the radius is negative.
+    """
+    if unit not in ["rad", "°"]:
+        raise ValueError(f"Unit must be radian ('rad') or degree ('°'), got {unit}.")
+    if np.any(r < 0.0):
+        raise ValueError("Negative radius values are not allowed.")
+    if unit == "°":
+        theta = np.deg2rad(theta)
+    return r * np.exp(1j * theta)

sigima/tools/datatypes.py

@@ -0,0 +1,26 @@
+# Copyright (c) DataLab Platform Developers, BSD 3-Clause license, see LICENSE file.
+
+"""
+.. Data Type Conversion Algorithms (see parent package :mod:`sigima.algorithms`)
+"""
+
+from __future__ import annotations
+
+import numpy as np
+
+
+def clip_astype(data: np.ndarray, dtype: np.dtype) -> np.ndarray:
+    """Convert array to a new data type, after having clipped values to the new
+    data type's range if it is an integer type.
+    If data type is not integer, this is equivalent to ``data.astype(dtype)``.
+
+    Args:
+        data: Array to convert
+        dtype: Data type to convert to
+
+    Returns:
+        Array converted to new data type
+    """
+    if np.issubdtype(dtype, np.integer):
+        return np.clip(data, np.iinfo(dtype).min, np.iinfo(dtype).max).astype(dtype)
+    return data.astype(dtype)