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

sigima/proc/image/arithmetic.py

@@ -0,0 +1,335 @@
+# Copyright (c) DataLab Platform Developers, BSD 3-Clause license, see LICENSE file.
+
+"""
+Arithmetic computation module
+-----------------------------
+
+This module provides arithmetic operations for images, such as pixel-wise addition,
+subtraction, multiplication, division, as well as operations with constants
+and combined arithmetic formulas.
+
+Main features include:
+
+- Pixel-wise addition, subtraction, multiplication, and division between images
+- Application of arithmetic operations with constants to images
+- Support for quadratic difference and general arithmetic expressions
+
+These functions are typically used for basic algebraic processing and normalization
+of image data.
+"""
+
+# pylint: disable=invalid-name  # Allows short reference names like x, y, ...
+
+# Note:
+# ----
+# - All `guidata.dataset.DataSet` parameter classes must also be imported
+#   in the `sigima.params` module.
+# - All functions decorated by `computation_function` must be imported in the upper
+#   level `sigima.proc.image` module.
+
+from __future__ import annotations
+
+import warnings
+
+import numpy as np
+
+from sigima.enums import MathOperator
+from sigima.objects.image import ImageObj
+from sigima.proc.base import (
+    ArithmeticParam,
+    ConstantParam,
+    dst_1_to_1,
+    dst_2_to_1,
+    dst_n_to_1,
+)
+from sigima.proc.decorator import computation_function
+from sigima.proc.image.base import restore_data_outside_roi
+from sigima.tools.datatypes import clip_astype
+
+# NOTE: Only parameter classes DEFINED in this module should be included in __all__.
+# Parameter classes imported from other modules (like sigima.proc.base) should NOT
+# be re-exported to avoid Sphinx cross-reference conflicts. The sigima.params module
+# serves as the central API point that imports and re-exports all parameter classes.
+__all__ = [
+    "addition",
+    "addition_constant",
+    "arithmetic",
+    "average",
+    "difference",
+    "difference_constant",
+    "division",
+    "division",
+    "division_constant",
+    "product",
+    "product_constant",
+    "quadratic_difference",
+    "standard_deviation",
+]
+
+# MARK: compute_n_to_1 functions -------------------------------------------------------
+# Functions with N input images and 1 output image
+# --------------------------------------------------------------------------------------
+# Those functions are perfoming a computation on N input images and return a single
+# output image. If we were only executing these functions locally, we would not need
+# to define them here, but since we are using the multiprocessing module, we need to
+# define them here so that they can be pickled and sent to the worker processes.
+# Also, we need to systematically return the output image object, even if it is already
+# modified in place, because the multiprocessing module will not be able to retrieve
+# the modified object from the worker processes.
+
+
+@computation_function()
+def addition(src_list: list[ImageObj]) -> ImageObj:
+    """Add images in the list and return the result image object
+
+    Args:
+        src_list: list of input image objects
+
+    Returns:
+        Output image object (modified in place)
+    """
+    dst = dst_n_to_1(src_list, "Σ")  # `dst` data is initialized to `src_list[0]` data
+    for src in src_list[1:]:
+        dst.data = np.add(dst.data, src.data, dtype=float)
+    restore_data_outside_roi(dst, src_list[0])
+    return dst
+
+
+@computation_function()
+def average(src_list: list[ImageObj]) -> ImageObj:
+    """Compute the average of images in the list and return the result image object
+
+    Args:
+        src_list: list of input image objects
+
+    Returns:
+        Output image object (modified in place)
+    """
+    dst = dst_n_to_1(src_list, "µ")  # `dst` data is initialized to `src_list[0]` data
+    for src in src_list[1:]:
+        dst.data = np.add(dst.data, src.data, dtype=float)
+    dst.data /= len(src_list)
+    restore_data_outside_roi(dst, src_list[0])
+    return dst
+
+
+@computation_function()
+def standard_deviation(src_list: list[ImageObj]) -> ImageObj:
+    """Compute the element-wise standard deviation of multiple images.
+
+    The first image in the list defines the "base" image. All other images are
+    used to compute the element-wise standard deviation with the base image.
+
+    .. note::
+
+        If all images share the same region of interest (ROI), the standard deviation
+        is computed only within the ROI.
+
+    .. warning::
+
+        It is assumed that all images have the same size and x-coordinates.
+
+    Args:
+        src_list: List of source images.
+
+    Returns:
+        Image object representing the standard deviation of the source images.
+    """
+    dst = dst_n_to_1(src_list, "𝜎")  # `dst` data is initialized to `src_list[0]` data
+    assert dst.data is not None
+    y_array = np.array([src.data for src in src_list], dtype=dst.data.dtype)
+    dst.data = np.std(y_array, axis=0, ddof=0)
+    restore_data_outside_roi(dst, src_list[0])
+    return dst
+
+
+@computation_function()
+def product(src_list: list[ImageObj]) -> ImageObj:
+    """Multiply images in the list and return the result image object
+
+    Args:
+        src_list: list of input image objects
+
+    Returns:
+        Output image object (modified in place)
+    """
+    dst = dst_n_to_1(src_list, "Π")  # `dst` data is initialized to `src_list[0]` data
+    for src in src_list[1:]:
+        dst.data = np.multiply(dst.data, src.data, dtype=float)
+    restore_data_outside_roi(dst, src_list[0])
+    return dst
+
+
+@computation_function()
+def addition_constant(src: ImageObj, p: ConstantParam) -> ImageObj:
+    """Add **dst** and a constant value and return the new result image object
+
+    Args:
+        src: input image object
+        p: constant value
+
+    Returns:
+        Result image object **src** + **p.value** (new object)
+    """
+    # For the addition of a constant value, we convert the constant value to the same
+    # data type as the input image, for consistency.
+    value = np.array(p.value).astype(dtype=src.data.dtype)
+    dst = dst_1_to_1(src, "+", str(value))
+    dst.data = np.add(src.data, value, dtype=float)
+    restore_data_outside_roi(dst, src)
+    return dst
+
+
+@computation_function()
+def difference_constant(src: ImageObj, p: ConstantParam) -> ImageObj:
+    """Subtract a constant value from an image and return the new result image object
+
+    Args:
+        src: input image object
+        p: constant value
+
+    Returns:
+        Result image object **src** - **p.value** (new object)
+    """
+    # For the subtraction of a constant value, we convert the constant value to the same
+    # data type as the input image, for consistency.
+    value = np.array(p.value).astype(dtype=src.data.dtype)
+    dst = dst_1_to_1(src, "-", str(value))
+    dst.data = np.subtract(src.data, value, dtype=float)
+    restore_data_outside_roi(dst, src)
+    return dst
+
+
+@computation_function()
+def product_constant(src: ImageObj, p: ConstantParam) -> ImageObj:
+    """Multiply **dst** by a constant value and return the new result image object
+
+    Args:
+        src: input image object
+        p: constant value
+
+    Returns:
+        Result image object **src** * **p.value** (new object)
+    """
+    # For the multiplication by a constant value, we do not convert the constant value
+    # to the same data type as the input image, because we want to allow the user to
+    # multiply an image by a constant value of a different data type. The final data
+    # type conversion ensures that the output image has the same data type as the input
+    # image.
+    dst = dst_1_to_1(src, "×", str(p.value))
+    dst.data = np.multiply(src.data, p.value, dtype=float)
+    restore_data_outside_roi(dst, src)
+    return dst
+
+
+@computation_function()
+def division_constant(src: ImageObj, p: ConstantParam) -> ImageObj:
+    """Divide an image by a constant value and return the new result image object
+
+    Args:
+        src: input image object
+        p: constant value
+
+    Returns:
+        Result image object **src** / **p.value** (new object)
+    """
+    # For the division by a constant value, we do not convert the constant value to the
+    # same data type as the input image, because we want to allow the user to divide an
+    # image by a constant value of a different data type. The final data type conversion
+    # ensures that the output image has the same data type as the input image.
+    dst = dst_1_to_1(src, "/", str(p.value))
+    dst.data = np.divide(src.data, p.value, dtype=float)
+    restore_data_outside_roi(dst, src)
+    return dst
+
+
+# MARK: compute_2_to_1 functions -------------------------------------------------------
+# Functions with N input images + 1 input image and N output images
+# --------------------------------------------------------------------------------------
+
+
+@computation_function()
+def arithmetic(src1: ImageObj, src2: ImageObj, p: ArithmeticParam) -> ImageObj:
+    """Compute arithmetic operation on two images
+
+    Args:
+        src1: input image object
+        src2: input image object
+        p: arithmetic parameters
+
+    Returns:
+        Result image object
+    """
+    initial_dtype = src1.data.dtype
+    title = p.operation.replace("obj1", "{0}").replace("obj2", "{1}")
+    dst = src1.copy(title=title)
+    o, a, b = p.operator, p.factor, p.constant
+    # Apply operator
+    if o in (MathOperator.MULTIPLY, MathOperator.DIVIDE) and a == 0.0:
+        dst.data = np.ones_like(src1.data) * b
+    elif o == MathOperator.ADD:
+        dst.data = np.add(src1.data, src2.data, dtype=float) * a + b
+    elif o == MathOperator.SUBTRACT:
+        dst.data = np.subtract(src1.data, src2.data, dtype=float) * a + b
+    elif o == MathOperator.MULTIPLY:
+        dst.data = np.multiply(src1.data, src2.data, dtype=float) * a + b
+    elif o == MathOperator.DIVIDE:
+        dst.data = np.divide(src1.data, src2.data, dtype=float) * a + b
+    # Eventually convert to initial data type
+    if p.restore_dtype:
+        dst.data = clip_astype(dst.data, initial_dtype)
+    restore_data_outside_roi(dst, src1)
+    return dst
+
+
+@computation_function()
+def difference(src1: ImageObj, src2: ImageObj) -> ImageObj:
+    """Compute difference between two images
+
+    Args:
+        src1: input image object
+        src2: input image object
+
+    Returns:
+        Result image object **src1** - **src2** (new object)
+    """
+    dst = dst_2_to_1(src1, src2, "-")
+    dst.data = np.subtract(src1.data, src2.data, dtype=float)
+    restore_data_outside_roi(dst, src1)
+    return dst
+
+
+@computation_function()
+def quadratic_difference(src1: ImageObj, src2: ImageObj) -> ImageObj:
+    """Compute quadratic difference between two images
+
+    Args:
+        src1: input image object
+        src2: input image object
+
+    Returns:
+        Result image object (**src1** - **src2**) / sqrt(2.0) (new object)
+    """
+    dst = dst_2_to_1(src1, src2, "quadratic_difference")
+    dst.data = np.subtract(src1.data, src2.data, dtype=float) / np.sqrt(2.0)
+    restore_data_outside_roi(dst, src1)
+    return dst
+
+
+@computation_function()
+def division(src1: ImageObj, src2: ImageObj) -> ImageObj:
+    """Compute division between two images
+
+    Args:
+        src1: input image object
+        src2: input image object
+
+    Returns:
+        Result image object **src1** / **src2** (new object)
+    """
+    dst = dst_2_to_1(src1, src2, "/")
+    with warnings.catch_warnings():
+        warnings.simplefilter("ignore", category=RuntimeWarning)
+        dst.data = np.divide(src1.data, src2.data, dtype=float)
+    restore_data_outside_roi(dst, src1)
+    return dst

sigima/proc/image/base.py

@@ -0,0 +1,260 @@
+# Copyright (c) DataLab Platform Developers, BSD 3-Clause license, see LICENSE file.
+
+"""
+Base computation module
+-----------------------
+
+This module provides core classes and utility functions that serve as building blocks
+for the other computation modules.
+
+Main features include:
+
+- Generic helper functions used across image processing modules
+- Core wrappers and infrastructure for computation functions
+
+Intended primarily for internal use, these tools support consistent API design
+and code reuse.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import Any
+
+import numpy as np
+
+from sigima.objects import NO_ROI, GeometryResult, ImageObj, KindShape, SignalObj
+from sigima.proc.base import dst_1_to_1, new_signal_result
+
+# NOTE: Only parameter classes DEFINED in this module should be included in __all__.
+# Parameter classes imported from other modules (like sigima.proc.base) should NOT
+# be re-exported to avoid Sphinx cross-reference conflicts. The sigima.params module
+# serves as the central API point that imports and re-exports all parameter classes.
+__all__ = [
+    "Wrap1to1Func",
+    "compute_geometry_from_obj",
+    "dst_1_to_1_signal",
+    "restore_data_outside_roi",
+]
+
+
+def restore_data_outside_roi(dst: ImageObj, src: ImageObj) -> None:
+    """Restore data outside the Region Of Interest (ROI) of the input image
+    after a computation, only if the input image has a ROI,
+    and if the output image has the same ROI as the input image,
+    and if the data types are compatible,
+    and if the shapes are the same.
+    Otherwise, do nothing.
+
+    Args:
+        dst: output image object
+        src: input image object
+    """
+    if src.maskdata is not None and dst.maskdata is not None:
+        if (
+            np.array_equal(src.maskdata, dst.maskdata)
+            and (
+                dst.data.dtype == src.data.dtype
+                or not np.issubdtype(dst.data.dtype, np.integer)
+            )
+            and dst.data.shape == src.data.shape
+        ):
+            dst.data[src.maskdata] = src.data[src.maskdata]
+
+
+class Wrap1to1Func:
+    """Wrap a 1 array → 1 array function to produce a 1 image → 1 image function,
+    which can be used as a Sigima computation function and inside DataLab's
+    infrastructure to perform computations with the Image Processor object.
+
+    This wrapping mechanism using a class is necessary for the resulted function to be
+    pickable by the ``multiprocessing`` module.
+
+    The instance of this wrapper is callable and returns a
+    :class:`sigima.objects.ImageObj` object.
+
+    Example:
+
+        >>> import numpy as np
+        >>> from sigima.proc.image import Wrap1to1Func
+        >>> import sigima.objects
+        >>> def add_noise(data):
+        ...     return data + np.random.random(data.shape)
+        >>> compute_add_noise = Wrap1to1Func(add_noise)
+        >>> data= np.ones((100, 100))
+        >>> ima0 = sigima.objects.create_image("Example", data)
+        >>> ima1 = compute_add_noise(ima0)
+
+    Args:
+        func: 1 array → 1 array function
+        *args: Additional positional arguments to pass to the function
+        **kwargs: Additional keyword arguments to pass to the function
+
+    .. note::
+
+        If `func_name` is provided in the keyword arguments, it will be used as the
+        function name instead of the default name derived from the function itself.
+    """
+
+    def __init__(self, func: Callable, *args: Any, **kwargs: Any) -> None:
+        self.func = func
+        self.args = args
+        self.kwargs = kwargs
+        self.__name__ = self.kwargs.pop("func_name", func.__name__)
+        self.__doc__ = func.__doc__
+        self.__call__.__func__.__doc__ = self.func.__doc__
+
+    def __call__(self, src: ImageObj) -> ImageObj:
+        """Compute the function on the input image and return the result image
+
+        Args:
+            src: input image object
+
+        Returns:
+            Output image object
+        """
+        suffix = ", ".join(
+            [str(arg) for arg in self.args]
+            + [f"{k}={v}" for k, v in self.kwargs.items() if v is not None]
+        )
+        dst = dst_1_to_1(src, self.__name__, suffix)
+        dst.data = self.func(src.data, *self.args, **self.kwargs)
+        restore_data_outside_roi(dst, src)
+        return dst
+
+
+def dst_1_to_1_signal(src: ImageObj, name: str, suffix: str | None = None) -> SignalObj:
+    """Create a result signal object, for processing functions that take a single
+    image object as input and return a single signal object (1-to-1-signal).
+
+    Args:
+        src: input image object
+        name: name of the processing function
+
+    Returns:
+        Output signal object
+    """
+    return new_signal_result(
+        src, name, suffix, (src.xunit, src.zunit), (src.xlabel, src.zlabel)
+    )
+
+
+def compute_geometry_from_obj(
+    title: str,
+    shape: KindShape,
+    obj: ImageObj,
+    func: Callable,
+    *args: Any,
+) -> GeometryResult | None:
+    """Compute a geometry shape from an image object by executing a computation function
+    on the data of the image object, for each ROI (Region Of Interest) in the image.
+
+    Args:
+        title: result title
+        shape: result shape kind
+        obj: input image object
+        func: computation function
+        *args: computation function arguments
+
+    Returns:
+        A geometry result object or None if no result is found.
+
+    .. important::
+        **Coordinate Conversion**: This function automatically converts coordinates
+        from pixel units (image indices) to physical units using the image object's
+        calibration information.
+
+        - **Input**: Computation function returns coordinates in pixel units
+        - **Output**: GeometryResult with coordinates in physical units (e.g., mm, µm)
+
+        The conversion is performed using the image's calibration parameters:
+        ``physical_x = obj.dx * pixel_x + obj.x0`` and
+        ``physical_y = obj.dy * pixel_y + obj.y0``
+
+    .. warning::
+
+        The computation function must take either a single argument (the data) or
+        multiple arguments (the data followed by the computation parameters).
+
+        Moreover, the computation function must return a single value or a NumPy array
+        containing the result of the computation. This array contains the coordinates
+        of points, polygons, circles or ellipses in the form [[x, y], ...], or
+        [[x0, y0, x1, y1, ...], ...], or [[x0, y0, r], ...], or
+        [[x0, y0, a, b, theta], ...].
+
+    Example:
+        >>> # func returns pixel coordinates like [[10, 20], [30, 40]]
+        >>> result = compute_geometry_from_obj(
+        ...     "Points", KindShape.POINT, image_obj, func
+        ... )
+        >>> # result.coords now contains physical coordinates like [[0.5, 1.0],
+        >>> # [1.5, 2.0]]
+
+    See Also:
+        :class:`~sigima.objects.scalar.GeometryResult`: The result object that stores
+        physical coordinates.
+    """
+    rows: list[np.ndarray] = []
+    num_cols: list[int] = []
+    roi_idx: list[int] = []
+    for i_roi in obj.iterate_roi_indices():
+        data_roi = obj.get_data(i_roi)
+        if args is None:
+            coords: np.ndarray = func(data_roi)
+        else:
+            coords: np.ndarray = func(data_roi, *args)
+
+        # This is a very long condition, but it's still quite readable, so we keep it
+        # as is and disable the pylint warning.
+        #
+        # pylint: disable=too-many-boolean-expressions
+        if not isinstance(coords, np.ndarray) or (
+            (
+                coords.ndim != 2
+                or coords.shape[1] < 2
+                or (coords.shape[1] > 5 and coords.shape[1] % 2 != 0)
+            )
+            and coords.size > 0
+        ):
+            raise ValueError(
+                f"Computation function {func.__name__} must return a NumPy array "
+                f"containing coordinates of points, polygons, circles or ellipses "
+                f"(in the form [[x, y], ...], or [[x0, y0, x1, y1, ...], ...], or "
+                f"[[x0, y0, r], ...], or [[x0, y0, a, b, theta], ...]), or an empty "
+                f"array."
+            )
+
+        if coords.size:
+            coords = np.array(coords, dtype=float)
+            if coords.shape[1] % 2 == 0:
+                # Coordinates are in the form [x0, y0, x1, y1, ...]
+                colx, coly = slice(None, None, 2), slice(1, None, 2)
+            else:
+                # Circle [x0, y0, r] or ellipse coordinates [x0, y0, a, b, theta]
+                colx, coly = 0, 1
+            coords[:, colx] = obj.dx * coords[:, colx] + obj.x0
+            coords[:, coly] = obj.dy * coords[:, coly] + obj.y0
+            if obj.roi is not None:
+                x0, y0, _x1, _y1 = obj.roi.get_single_roi(i_roi).get_bounding_box(obj)
+                coords[:, colx] += x0 - obj.x0
+                coords[:, coly] += y0 - obj.y0
+
+            rows.append(coords)
+            num_cols.append(coords.shape[1])
+            roi_idx.extend([NO_ROI if i_roi is None else int(i_roi)] * coords.shape[0])
+    if rows:
+        if len(set(num_cols)) != 1:
+            # This happens when the number of columns is not the same for all ROIs.
+            # As of now, this happens only for polygon contours.
+            # We need to pad the arrays with NaNs.
+            max_cols = max(num_cols)
+            num_rows = sum(coords.shape[0] for coords in rows)
+            array = np.full((num_rows, max_cols), np.nan)
+            start = 0
+            for row in rows:
+                array[start : start + row.shape[0], : row.shape[1]] = row
+                start += row.shape[0]
+        else:
+            array = np.vstack(rows)
+        return GeometryResult(title, shape, array, np.asarray(roi_idx, dtype=int))
+    return None