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

sigima/objects/signal/roi.py

@@ -0,0 +1,274 @@
+# Copyright (c) DataLab Platform Developers, BSD 3-Clause license, see LICENSE file.
+
+"""
+Signal ROI utilities
+====================
+
+This module provides Region of Interest (ROI) classes and utilities for signal objects.
+
+The module includes:
+
+- `ROI1DParam`: Parameter class for 1D signal ROIs
+- `SegmentROI`: Single ROI representing a segment of a signal
+- `SignalROI`: Collection of signal ROIs with operations
+- `create_signal_roi`: Factory function for creating signal ROI objects
+
+These classes enable defining and working with regions of interest in 1D signal data,
+supporting operations like data extraction, masking, and parameter conversion.
+"""
+
+# pylint: disable=invalid-name  # Allows short reference names like x, y, ...
+# pylint: disable=duplicate-code
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Type
+
+import guidata.dataset as gds
+import numpy as np
+
+from sigima.config import _
+from sigima.objects import base
+
+if TYPE_CHECKING:
+    from sigima.objects.signal.object import SignalObj
+
+
+class ROI1DParam(base.BaseROIParam["SignalObj", "SegmentROI"]):
+    """Signal ROI parameters"""
+
+    # Note: in this class, the ROI parameters are stored as X coordinates
+
+    title = gds.StringItem(_("ROI title"), default="")
+    xmin = gds.FloatItem(_("First point coordinate"), default=0.0)
+    xmax = gds.FloatItem(_("Last point coordinate"), default=1.0)
+
+    def to_single_roi(self, obj: SignalObj) -> SegmentROI:
+        """Convert parameters to single ROI
+
+        Args:
+            obj: signal object
+
+        Returns:
+            Single ROI
+        """
+        assert isinstance(self.xmin, float) and isinstance(self.xmax, float)
+        return SegmentROI([self.xmin, self.xmax], False, title=self.title)
+
+    def get_data(self, obj: SignalObj) -> np.ndarray:
+        """Get signal data in ROI
+
+        Args:
+            obj: signal object
+
+        Returns:
+            Data in ROI
+        """
+        assert isinstance(self.xmin, float) and isinstance(self.xmax, float)
+        imin, imax = np.searchsorted(obj.x, [self.xmin, self.xmax])
+        return np.array([obj.x[imin:imax], obj.y[imin:imax]])
+
+
+class SegmentROI(base.BaseSingleROI["SignalObj", ROI1DParam]):
+    """Segment ROI
+
+    Args:
+        coords: ROI coordinates (xmin, xmax)
+        title: ROI title
+    """
+
+    # Note: in this class, the ROI parameters are stored as X indices
+
+    def check_coords(self) -> None:
+        """Check if coords are valid
+
+        Raises:
+            ValueError: invalid coords
+        """
+        if len(self.coords) != 2:
+            raise ValueError("Invalid ROI segment coords (2 values expected)")
+        if self.coords[0] >= self.coords[1]:
+            raise ValueError("Invalid ROI segment coords (xmin >= xmax)")
+
+    def get_data(self, obj: SignalObj) -> tuple[np.ndarray, np.ndarray]:
+        """Get signal data in ROI
+
+        Args:
+            obj: signal object
+
+        Returns:
+            Data in ROI
+        """
+        imin, imax = self.get_indices_coords(obj)
+        return obj.x[imin:imax], obj.y[imin:imax]
+
+    def to_mask(self, obj: SignalObj) -> np.ndarray:
+        """Create mask from ROI
+
+        Args:
+            obj: signal object
+
+        Returns:
+            Mask (boolean array where True values are inside the ROI)
+        """
+        mask = np.ones_like(obj.xydata, dtype=bool)
+        imin, imax = self.get_indices_coords(obj)
+        mask[:, imin:imax] = False
+        return mask
+
+    # pylint: disable=unused-argument
+    def to_param(self, obj: SignalObj, index: int) -> ROI1DParam:
+        """Convert ROI to parameters
+
+        Args:
+            obj: object (signal), for physical-indices coordinates conversion
+            index: ROI index
+        """
+        gtitle = base.get_generic_roi_title(index)
+        param = ROI1DParam(gtitle)
+        param.title = self.title or gtitle
+        param.xmin, param.xmax = self.get_physical_coords(obj)
+        return param
+
+
+class SignalROI(base.BaseROI["SignalObj", SegmentROI, ROI1DParam]):
+    """Signal Regions of Interest
+
+    Args:
+        inverse: if True, ROI is outside the region
+    """
+
+    PREFIX = "s"
+
+    def union(self) -> SignalROI:
+        """Return union of ROIs"""
+        if not self.single_rois:
+            return SignalROI()
+        coords = np.array([roi.coords for roi in self.single_rois])
+        # Merge overlapping segments:
+        sorted_coords = coords[coords[:, 0].argsort()]
+        merged_coords = [sorted_coords[0].tolist()]
+        for current in sorted_coords[1:]:
+            last = merged_coords[-1]
+            if current[0] <= last[1]:  # Overlap
+                last[1] = max(last[1], current[1])  # Merge
+            else:
+                merged_coords.append(current.tolist())
+        # Create new SignalROI with merged segments:
+        roi = create_signal_roi(merged_coords)
+        return roi
+
+    def clipped(self, x_min: float, x_max: float) -> SignalROI:
+        """Remove parts of ROIs outside the signal range
+
+        Args:
+            x_min: signal minimum X value
+            x_max: signal maximum X value
+
+        Returns:
+            SignalROI object containing ROIs clipped to the specified signal range.
+        """
+        new_roi = SignalROI()
+        for roi in self.single_rois:
+            roi_min, roi_max = roi.coords
+            if roi_max < x_min or roi_min > x_max:
+                # ROI completely outside signal range: skip it
+                continue
+            # Clip ROI to signal range:
+            new_roi_min = max(roi_min, x_min)
+            new_roi_max = min(roi_max, x_max)
+            new_roi.add_roi(
+                SegmentROI(np.array([new_roi_min, new_roi_max], float), indices=False)
+            )
+        return new_roi
+
+    def inverted(self, x_min: float, x_max: float) -> SignalROI:
+        """Return inverted ROI (inside/outside).
+
+        Args:
+            x_min: signal minimum X value
+            x_max: signal maximum X value
+        Returns:
+            Inverted ROI
+        """
+        clipped_roi = self.clipped(x_min, x_max)
+        union_roi = clipped_roi.union()
+        roi_delimiter_list = np.array(
+            [roi.coords for roi in union_roi.single_rois]
+        ).reshape(-1)
+
+        if len(roi_delimiter_list) == 0:
+            # No ROIs: inverted ROI is the whole signal
+            raise ValueError("No ROIs defined, cannot invert")
+        if len(roi_delimiter_list) % 2 != 0:
+            # Odd number of delimiters: add signal limits
+            raise ValueError("Internal error: odd number of ROI delimiters")
+
+        if roi_delimiter_list[0] == x_min:
+            # First delimiter is signal min: remove it
+            roi_delimiter_list = roi_delimiter_list[1:]
+        else:
+            # Add signal min as first delimiter
+            roi_delimiter_list = np.insert(roi_delimiter_list, 0, x_min)
+
+        if roi_delimiter_list[-1] == x_max:
+            # Last delimiter is signal max: remove it
+            roi_delimiter_list = roi_delimiter_list[:-1]
+        else:
+            # Add signal max as last delimiter
+            roi_delimiter_list = np.append(roi_delimiter_list, x_max)
+
+        return create_signal_roi(np.array(roi_delimiter_list).reshape(-1, 2))
+
+    @staticmethod
+    def get_compatible_single_roi_classes() -> list[Type[SegmentROI]]:
+        """Return compatible single ROI classes"""
+        return [SegmentROI]
+
+    def to_mask(self, obj: SignalObj) -> np.ndarray:
+        """Create mask from ROI
+
+        Args:
+            obj: signal object
+
+        Returns:
+            Mask (boolean array where True values are inside the ROI)
+        """
+        mask = np.ones_like(obj.xydata, dtype=bool)
+        if self.single_rois:
+            for roi in self.single_rois:
+                mask &= roi.to_mask(obj)
+        else:
+            # If no single ROIs, the mask is empty (no ROI defined)
+            mask[:] = False
+        return mask
+
+
+def create_signal_roi(
+    coords: np.ndarray | list[float] | list[list[float]],
+    indices: bool = False,
+    title: str = "",
+) -> SignalROI:
+    """Create Signal Regions of Interest (ROI) object.
+    More ROIs can be added to the object after creation, using the `add_roi` method.
+
+    Args:
+        coords: single ROI coordinates `[xmin, xmax]`, or multiple ROIs coordinates
+         `[[xmin1, xmax1], [xmin2, xmax2], ...]` (lists or NumPy arrays)
+        indices: if True, coordinates are indices, if False, they are physical values
+         (default to False for signals)
+        title: title
+
+    Returns:
+        Regions of Interest (ROI) object
+
+    Raises:
+        ValueError: if the number of coordinates is not even
+    """
+    coords = np.array(coords, float)
+    if coords.ndim == 1:
+        coords = coords.reshape(1, -1)
+    roi = SignalROI()
+    for row in coords:
+        roi.add_roi(SegmentROI(row, indices=indices, title=title))
+    return roi

sigima/params.py

@@ -0,0 +1,405 @@
+# Copyright (c) DataLab Platform Developers, BSD 3-Clause license, see LICENSE file.
+
+"""
+Parameters (:mod:`sigima.params`)
+---------------------------------
+
+The :mod:`sigima.params` module aims at providing all the dataset parameters that are
+used by the :mod:`sigima.proc` and DataLab's processors.
+
+Those datasets are defined in other modules:
+
+    - :mod:`sigima.proc.base`
+    - :mod:`sigima.proc.image`
+    - :mod:`sigima.proc.signal`
+
+The :mod:`sigima.params` module is thus a convenient way to import all the sets of
+parameters at once.
+
+As a matter of fact, the following import statement is equivalent to the previous one:
+
+.. code-block:: python
+
+    # Original import statement
+    from sigima.proc.base import MovingAverageParam
+    from sigima.proc.signal import PolynomialFitParam
+    from sigima.proc.image.exposure import EqualizeHistParam
+
+    # Equivalent import statement
+    from sigima.params import MovingAverageParam, PolynomialFitParam, EqualizeHistParam
+
+Introduction to `DataSet` parameters
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The datasets listed in the following sections are used to define the parameters
+necessary for the various computations and processing operations available in Sigima.
+
+Each dataset is a subclass of :py:class:`guidata.dataset.datatypes.DataSet` and thus
+needs to be instantiated before being used.
+
+Here is a complete example of how to instantiate a dataset and access its parameters
+with the :py:class:`sigima.params.BinningParam` dataset:
+
+    .. autodataset:: sigima.params.BinningParam
+        :no-index:
+        :shownote:
+
+I/O parameters
+^^^^^^^^^^^^^^
+
+.. autodataset:: sigima.io.convenience.SaveToDirectoryParam
+    :no-index:
+
+Common parameters
+^^^^^^^^^^^^^^^^^
+
+.. autodataset:: sigima.params.ArithmeticParam
+    :no-index:
+.. autodataset:: sigima.params.ClipParam
+    :no-index:
+.. autodataset:: sigima.params.ConstantParam
+    :no-index:
+.. autodataset:: sigima.params.FFTParam
+    :no-index:
+.. autodataset:: sigima.params.GaussianParam
+    :no-index:
+.. autodataset:: sigima.params.HistogramParam
+    :no-index:
+.. autodataset:: sigima.params.MovingAverageParam
+    :no-index:
+.. autodataset:: sigima.params.MovingMedianParam
+    :no-index:
+.. autodataset:: sigima.params.NormalizeParam
+    :no-index:
+.. autodataset:: sigima.params.SpectrumParam
+    :no-index:
+
+Signal parameters
+^^^^^^^^^^^^^^^^^
+
+.. autodataset:: sigima.params.AllanVarianceParam
+    :no-index:
+.. autodataset:: sigima.params.AngleUnitParam
+    :no-index:
+.. autodataset:: sigima.params.BandPassFilterParam
+    :no-index:
+.. autodataset:: sigima.params.BandStopFilterParam
+    :no-index:
+.. autodataset:: sigima.params.DataTypeSParam
+    :no-index:
+.. autodataset:: sigima.params.DetrendingParam
+    :no-index:
+.. autodataset:: sigima.params.DynamicParam
+    :no-index:
+.. autodataset:: sigima.params.AbscissaParam
+    :no-index:
+.. autodataset:: sigima.params.OrdinateParam
+    :no-index:
+.. autodataset:: sigima.params.FWHMParam
+    :no-index:
+.. autodataset:: sigima.params.HighPassFilterParam
+    :no-index:
+.. autodataset:: sigima.params.InterpolationParam
+    :no-index:
+.. autodataset:: sigima.params.LowPassFilterParam
+    :no-index:
+.. autodataset:: sigima.params.PeakDetectionParam
+    :no-index:
+.. autodataset:: sigima.params.PolynomialFitParam
+    :no-index:
+.. autodataset:: sigima.params.PowerParam
+    :no-index:
+.. autodataset:: sigima.params.PulseFeaturesParam
+    :no-index:
+.. autodataset:: sigima.params.Resampling1DParam
+    :no-index:
+.. autodataset:: sigima.params.Resampling2DParam
+    :no-index:
+.. autodataset:: sigima.params.WindowingParam
+    :no-index:
+.. autodataset:: sigima.params.XYCalibrateParam
+    :no-index:
+.. autodataset:: sigima.params.ZeroPadding1DParam
+    :no-index:
+
+Image parameters
+^^^^^^^^^^^^^^^^
+
+Base image parameters
+~~~~~~~~~~~~~~~~~~~~~
+
+.. autodataset:: sigima.params.GridParam
+    :no-index:
+
+Detection parameters
+~~~~~~~~~~~~~~~~~~~~
+
+.. autodataset:: sigima.params.BlobDOGParam
+    :no-index:
+.. autodataset:: sigima.params.BlobDOHParam
+    :no-index:
+.. autodataset:: sigima.params.BlobLOGParam
+    :no-index:
+.. autodataset:: sigima.params.BlobOpenCVParam
+    :no-index:
+.. autodataset:: sigima.params.ContourShapeParam
+    :no-index:
+.. autodataset:: sigima.params.Peak2DDetectionParam
+    :no-index:
+.. autodataset:: sigima.params.HoughCircleParam
+    :no-index:
+
+Edge detection parameters
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. autodataset:: sigima.params.CannyParam
+    :no-index:
+
+Exposure correction parameters
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. autodataset:: sigima.params.AdjustGammaParam
+    :no-index:
+.. autodataset:: sigima.params.AdjustLogParam
+    :no-index:
+.. autodataset:: sigima.params.AdjustSigmoidParam
+    :no-index:
+.. autodataset:: sigima.params.EqualizeAdaptHistParam
+    :no-index:
+.. autodataset:: sigima.params.EqualizeHistParam
+    :no-index:
+.. autodataset:: sigima.params.RescaleIntensityParam
+    :no-index:
+.. autodataset:: sigima.params.FlatFieldParam
+    :no-index:
+.. autodataset:: sigima.params.XYZCalibrateParam
+    :no-index:
+
+Extraction parameters
+~~~~~~~~~~~~~~~~~~~~~~
+
+.. autodataset:: sigima.params.AverageProfileParam
+    :no-index:
+.. autodataset:: sigima.params.LineProfileParam
+    :no-index:
+.. autodataset:: sigima.params.RadialProfileParam
+    :no-index:
+.. autodataset:: sigima.params.SegmentProfileParam
+    :no-index:
+.. autoclass:: sigima.params.Direction
+    :no-index:
+.. autodataset:: sigima.params.ROIGridParam
+    :no-index:
+
+Filtering parameters
+~~~~~~~~~~~~~~~~~~~~
+
+.. autodataset:: sigima.params.ButterworthParam
+    :no-index:
+.. autofunction:: sigima.params.GaussianFreqFilterParam
+    :no-index:
+
+Fourier analysis parameters
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. autodataset:: sigima.params.ZeroPadding2DParam
+    :no-index:
+
+Geometry parameters
+~~~~~~~~~~~~~~~~~~~
+
+.. autodataset:: sigima.params.BinningParam
+    :no-index:
+.. autodataset:: sigima.params.ResizeParam
+    :no-index:
+.. autodataset:: sigima.params.RotateParam
+    :no-index:
+.. autodataset:: sigima.params.TranslateParam
+    :no-index:
+
+Mathematical operation parameters
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. autodataset:: sigima.params.DataTypeIParam
+    :no-index:
+.. autodataset:: sigima.params.Log10ZPlusNParam
+    :no-index:
+
+Morphological parameters
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. autodataset:: sigima.params.MorphologyParam
+    :no-index:
+
+Restoration parameters
+~~~~~~~~~~~~~~~~~~~~~~
+
+.. autodataset:: sigima.params.DenoiseBilateralParam
+    :no-index:
+.. autodataset:: sigima.params.DenoiseTVParam
+    :no-index:
+.. autodataset:: sigima.params.DenoiseWaveletParam
+    :no-index:
+
+Threshold parameters
+~~~~~~~~~~~~~~~~~~~~
+
+.. autodataset:: sigima.params.ThresholdParam
+    :no-index:
+"""
+
+__all__ = [
+    "AbscissaParam",
+    "AdjustGammaParam",
+    "AdjustLogParam",
+    "AdjustSigmoidParam",
+    "AllanVarianceParam",
+    "AngleUnitParam",
+    "ArithmeticParam",
+    "AverageProfileParam",
+    "BandPassFilterParam",
+    "BandStopFilterParam",
+    "BinningParam",
+    "BlobDOGParam",
+    "BlobDOHParam",
+    "BlobLOGParam",
+    "BlobOpenCVParam",
+    "ButterworthParam",
+    "CannyParam",
+    "ClipParam",
+    "ConstantParam",
+    "ContourShapeParam",
+    "DataTypeIParam",
+    "DataTypeSParam",
+    "DenoiseBilateralParam",
+    "DenoiseTVParam",
+    "DenoiseWaveletParam",
+    "DetrendingParam",
+    "Direction",
+    "DynamicParam",
+    "EqualizeAdaptHistParam",
+    "EqualizeHistParam",
+    "FFTParam",
+    "FWHMParam",
+    "FlatFieldParam",
+    "GaussianFreqFilterParam",
+    "GaussianParam",
+    "GridParam",
+    "HighPassFilterParam",
+    "HistogramParam",
+    "HoughCircleParam",
+    "InterpolationParam",
+    "LineProfileParam",
+    "Log10ZPlusNParam",
+    "LowPassFilterParam",
+    "MorphologyParam",
+    "MovingAverageParam",
+    "MovingMedianParam",
+    "NormalizeParam",
+    "OrdinateParam",
+    "Peak2DDetectionParam",
+    "PeakDetectionParam",
+    "PhaseParam",
+    "PolynomialFitParam",
+    "PowerParam",
+    "PulseFeaturesParam",
+    "ROIGridParam",
+    "RadialProfileParam",
+    "Resampling1DParam",
+    "Resampling2DParam",
+    "RescaleIntensityParam",
+    "ResizeParam",
+    "RotateParam",
+    "SaveToDirectoryParam",
+    "SegmentProfileParam",
+    "SignalsToImageParam",
+    "SpectrumParam",
+    "ThresholdParam",
+    "TranslateParam",
+    "UniformCoordsParam",
+    "WindowingParam",
+    "XYCalibrateParam",
+    "XYZCalibrateParam",
+    "ZeroPadding1DParam",
+    "ZeroPadding2DParam",
+]
+
+from sigima.io.convenience import SaveToDirectoryParam
+from sigima.proc.base import (
+    AngleUnitParam,
+    ArithmeticParam,
+    ClipParam,
+    ConstantParam,
+    FFTParam,
+    GaussianParam,
+    HistogramParam,
+    MovingAverageParam,
+    MovingMedianParam,
+    NormalizeParam,
+    PhaseParam,
+    SignalsToImageParam,
+    SpectrumParam,
+)
+from sigima.proc.image import (
+    AdjustGammaParam,
+    AdjustLogParam,
+    AdjustSigmoidParam,
+    AverageProfileParam,
+    BinningParam,
+    BlobDOGParam,
+    BlobDOHParam,
+    BlobLOGParam,
+    BlobOpenCVParam,
+    ButterworthParam,
+    CannyParam,
+    ContourShapeParam,
+    DataTypeIParam,
+    DenoiseBilateralParam,
+    DenoiseTVParam,
+    DenoiseWaveletParam,
+    Direction,
+    EqualizeAdaptHistParam,
+    EqualizeHistParam,
+    FlatFieldParam,
+    GaussianFreqFilterParam,
+    GridParam,
+    HoughCircleParam,
+    LineProfileParam,
+    Log10ZPlusNParam,
+    MorphologyParam,
+    Peak2DDetectionParam,
+    RadialProfileParam,
+    Resampling2DParam,
+    RescaleIntensityParam,
+    ResizeParam,
+    ROIGridParam,
+    RotateParam,
+    SegmentProfileParam,
+    ThresholdParam,
+    TranslateParam,
+    UniformCoordsParam,
+    XYZCalibrateParam,
+    ZeroPadding2DParam,
+)
+from sigima.proc.signal import (
+    AbscissaParam,
+    AllanVarianceParam,
+    BandPassFilterParam,
+    BandStopFilterParam,
+    DataTypeSParam,
+    DetrendingParam,
+    DynamicParam,
+    FWHMParam,
+    HighPassFilterParam,
+    InterpolationParam,
+    LowPassFilterParam,
+    OrdinateParam,
+    PeakDetectionParam,
+    PolynomialFitParam,
+    PowerParam,
+    PulseFeaturesParam,
+    Resampling1DParam,
+    WindowingParam,
+    XYCalibrateParam,
+    ZeroPadding1DParam,
+)