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

sigima/data/tests/image_formats/tiling.txt

@@ -0,0 +1,10 @@
+1,0000000e+000	  2,0000000e+000	  3,0000000e+000	  4,0000000e+000	  5,0000000e+000	  6,0000000e+000	  7,0000000e+000	  8,0000000e+000	  9,0000000e+000	  1,0000000e+001
+2,0000000e+000	  4,0000000e+000	  6,0000000e+000	  8,0000000e+000	  1,0000000e+001	  1,2000000e+001	  1,4000000e+001	  1,6000000e+001	  1,8000000e+001	  2,0000000e+001
+3,0000000e+000	  6,0000000e+000	  9,0000000e+000	  1,2000000e+001	  1,5000000e+001	  1,8000000e+001	  2,1000000e+001	  2,4000000e+001	  2,7000000e+001	  3,0000000e+001
+4,0000000e+000	  8,0000000e+000	  1,2000000e+001	  1,6000000e+001	  2,0000000e+001	  2,4000000e+001	  2,8000000e+001	  3,2000000e+001	  3,6000000e+001	  4,0000000e+001
+5,0000000e+000	  1,0000000e+001	  1,5000000e+001	  2,0000000e+001	  2,5000000e+001	  3,0000000e+001	  3,5000000e+001	  4,0000000e+001	  4,5000000e+001	  5,0000000e+001
+6,0000000e+000	  1,2000000e+001	  1,8000000e+001	  2,4000000e+001	  3,0000000e+001	  3,6000000e+001	  4,2000000e+001	  4,8000000e+001	  5,4000000e+001	  6,0000000e+001
+7,0000000e+000	  1,4000000e+001	  2,1000000e+001	  2,8000000e+001	  3,5000000e+001	  4,2000000e+001	  4,9000000e+001	  5,6000000e+001	  6,3000000e+001	  7,0000000e+001
+8,0000000e+000	  1,6000000e+001	  2,4000000e+001	  3,2000000e+001	  4,0000000e+001	  4,8000000e+001	  5,6000000e+001	  6,4000000e+001	  7,2000000e+001	  8,0000000e+001
+9,0000000e+000	  1,8000000e+001	  2,7000000e+001	  3,6000000e+001	  4,5000000e+001	  5,4000000e+001	  6,3000000e+001	  7,2000000e+001	  8,1000000e+001	  9,0000000e+001
+1,0000000e+001	  2,0000000e+001	  3,0000000e+001	  4,0000000e+001	  5,0000000e+001	  6,0000000e+001	  7,0000000e+001	  8,0000000e+001	  9,0000000e+001	  1,0000000e+002

sigima/enums.py

@@ -0,0 +1,195 @@
+# Copyright (c) DataLab Platform Developers, BSD 3-Clause license, see LICENSE file.
+
+"""Common enum definitions for Sigima processing."""
+
+from __future__ import annotations
+
+import guidata.dataset as gds
+
+from sigima.config import _
+
+
+class AngleUnit(gds.LabeledEnum):
+    """Angle units."""
+
+    RADIAN = "rad"
+    DEGREE = "°"
+
+
+class BinningOperation(gds.LabeledEnum):
+    """Binning operations for image processing."""
+
+    SUM = "sum"
+    AVERAGE = "average"
+    MEDIAN = "median"
+    MIN = "min"
+    MAX = "max"
+
+
+class ContourShape(gds.LabeledEnum):
+    """Contour shapes for image processing."""
+
+    ELLIPSE = "ellipse", _("Ellipse")
+    CIRCLE = "circle", _("Circle")
+    POLYGON = "polygon", _("Polygon")
+
+
+class BorderMode(gds.LabeledEnum):
+    """Border modes for filtering and image processing."""
+
+    CONSTANT = "constant"
+    NEAREST = "nearest"
+    REFLECT = "reflect"
+    WRAP = "wrap"
+    MIRROR = "mirror"
+
+
+class MathOperator(gds.LabeledEnum):
+    """Mathematical operators for data operations."""
+
+    ADD = "+"
+    SUBTRACT = "-"
+    MULTIPLY = "×"
+    DIVIDE = "/"
+
+
+class FilterMode(gds.LabeledEnum):
+    """Filter modes for signal and image processing."""
+
+    REFLECT = "reflect"
+    CONSTANT = "constant"
+    NEAREST = "nearest"
+    MIRROR = "mirror"
+    WRAP = "wrap"
+
+
+class WaveletMode(gds.LabeledEnum):
+    """Wavelet transform modes."""
+
+    CONSTANT = "constant"
+    EDGE = "edge"
+    SYMMETRIC = "symmetric"
+    REFLECT = "reflect"
+    WRAP = "wrap"
+
+
+class ThresholdMethod(gds.LabeledEnum):
+    """Thresholding methods for wavelet denoising."""
+
+    SOFT = "soft"
+    HARD = "hard"
+
+
+class ShrinkageMethod(gds.LabeledEnum):
+    """Shrinkage methods for wavelet denoising."""
+
+    BAYES_SHRINK = "BayesShrink"
+    VISU_SHRINK = "VisuShrink"
+
+
+class PadLocation1D(gds.LabeledEnum):
+    """Padding location for 1D signal processing."""
+
+    APPEND = "append"
+    PREPEND = "prepend"
+    BOTH = "both"
+
+
+class PadLocation2D(gds.LabeledEnum):
+    """Padding location for 2D image processing."""
+
+    BOTTOM_RIGHT = "bottom-right", _("Bottom-right")
+    AROUND = "around", _("Around")
+
+
+class PowerUnit(gds.LabeledEnum):
+    """Power spectral density units."""
+
+    DBC = "dBc"
+    DBFS = "dBFS"
+
+
+class WindowingMethod(gds.LabeledEnum):
+    """Windowing methods enumeration."""
+
+    BARTHANN = "barthann", "Barthann"
+    BARTLETT = "bartlett", "Bartlett"
+    BLACKMAN = "blackman", "Blackman"
+    BLACKMAN_HARRIS = "blackman_harris", "Blackman-Harris"
+    BOHMAN = "bohman", "Bohman"
+    BOXCAR = "boxcar", "Boxcar"
+    COSINE = "cosine", _("Cosine")
+    EXPONENTIAL = "exponential", _("Exponential")
+    FLAT_TOP = "flat_top", _("Flat Top")
+    GAUSSIAN = "gaussian", _("Gaussian")
+    HAMMING = "hamming", "Hamming"
+    HANN = "hann", "Hann"
+    KAISER = "kaiser", "Kaiser"
+    LANCZOS = "lanczos", "Lanczos"
+    NUTTALL = "nuttall", "Nuttall"
+    PARZEN = "parzen", "Parzen"
+    TAYLOR = "taylor", "Taylor"
+    TUKEY = "tukey", "Tukey"
+
+
+class Interpolation1DMethod(gds.LabeledEnum):
+    """Methods for 1D interpolation and resampling."""
+
+    LINEAR = "linear", _("Linear")
+    SPLINE = "spline", _("Spline")
+    QUADRATIC = "quadratic", _("Quadratic")
+    CUBIC = "cubic", _("Cubic")
+    BARYCENTRIC = "barycentric", _("Barycentric")
+    PCHIP = "pchip", _("PCHIP")
+
+
+class Interpolation2DMethod(gds.LabeledEnum):
+    """Methods for 2D interpolation and resampling."""
+
+    NEAREST = "nearest", _("Nearest")
+    LINEAR = "linear", _("Linear")
+    CUBIC = "cubic", _("Cubic")
+
+
+class NormalizationMethod(gds.LabeledEnum):
+    """Normalization methods for signal processing."""
+
+    MAXIMUM = "maximum", _("Maximum")
+    AMPLITUDE = "amplitude", _("Amplitude")
+    AREA = "area", _("Area")
+    ENERGY = "energy", _("Energy")
+    RMS = "rms", _("RMS")
+
+
+class FilterType(gds.LabeledEnum):
+    """Filter types"""
+
+    LOWPASS = "lowpass", "lowpass"
+    HIGHPASS = "highpass", "highpass"
+    BANDPASS = "bandpass", "bandpass"
+    BANDSTOP = "bandstop", "bandstop"
+
+
+class FrequencyFilterMethod(gds.LabeledEnum):
+    """Frequency filter methods for signal processing."""
+
+    BESSEL = "bessel", "Bessel"
+    BRICKWALL = "brickwall", _("Brickwall")
+    BUTTERWORTH = "butterworth", "Butterworth"
+    CHEBYSHEV1 = "chebyshev1", "Chebyshev I"
+    CHEBYSHEV2 = "chebyshev2", "Chebyshev II"
+    ELLIPTIC = "elliptic", _("Elliptic")
+
+
+class SignalShape(gds.LabeledEnum):
+    """Signal shapes."""
+
+    STEP = "step"
+    SQUARE = "square"
+
+
+class SignalsToImageOrientation(gds.LabeledEnum):
+    """Orientation for combining signals into an image."""
+
+    ROWS = "rows", _("As rows")
+    COLUMNS = "columns", _("As columns")

sigima/io/__init__.py

@@ -0,0 +1,123 @@
+# Copyright (c) DataLab Platform Developers, BSD 3-Clause license, see LICENSE file.
+
+"""
+I/O (:mod:`sigima.io`)
+-----------------------
+
+This package provides input/output functionality for reading and writing
+signals and images in various formats. It includes a registry for managing
+the available formats and their associated read/write functions.
+
+General purpose I/O functions
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This package provides functions to read and write signals and images, allowing users
+to easily handle different file formats without needing to know the specifics
+of each format.
+
+It includes the following main functions:
+
+- :py:func:`read_signals`: Read a list of signals from a file.
+- :py:func:`read_signal`: Read a single signal from a file.
+- :py:func:`write_signal`: Write a single signal to a file.
+- :py:func:`read_images`: Read a list of images from a file.
+- :py:func:`read_image`: Read a single image from a file.
+- :py:func:`write_image`: Write a single image to a file.
+
+Supported formats
+^^^^^^^^^^^^^^^^^
+
+.. autodata:: SIGNAL_FORMAT_INFO
+
+.. autodata:: IMAGE_FORMAT_INFO
+
+Adding new formats
+^^^^^^^^^^^^^^^^^^
+
+To add new formats, you can create a new class that inherits from
+:py:class:`sigima.io.image.base.ImageFormatBase` or
+:py:class:`sigima.io.signal.base.SignalFormatBase` and implement the required methods.
+
+.. note::
+
+    Thanks to the plugin system, you can add new formats simply by defining a new class
+    in a separate module, and it will be automatically discovered and registered, as
+    long as it is imported in your application or library.
+
+Example of a new image format plugin:
+
+.. code-block:: python
+
+    from sigima.io.image.base import ImageFormatBase
+    from sigima.io.base import FormatInfo
+
+    class MyImageFormat(ImageFormatBase):
+        \"\"\"Object representing MyImageFormat image file type\"\"\"
+
+        FORMAT_INFO = FormatInfo(
+            name="MyImageFormat",
+            extensions="*.myimg",
+            readable=True,
+            writeable=False,
+        )
+
+        @staticmethod
+        def read_data(filename: str) -> np.ndarray:
+            \"\"\"Read data and return it
+
+            Args:
+                filename (str): path to MyImageFormat file
+
+            Returns:
+                np.ndarray: image data
+            \"\"\"
+            # Implement reading logic here
+            pass
+"""
+
+from __future__ import annotations
+
+from sigima.io.common.objmeta import (
+    read_metadata,
+    read_roi,
+    read_roi_grid,
+    write_metadata,
+    write_roi,
+    write_roi_grid,
+)
+from sigima.io.convenience import (
+    read_image,
+    read_images,
+    read_signal,
+    read_signals,
+    write_image,
+    write_images,
+    write_signal,
+    write_signals,
+)
+from sigima.io.image.base import ImageIORegistry
+from sigima.io.signal.base import SignalIORegistry
+
+__all__ = [
+    "IMAGE_FORMAT_INFO",
+    "SIGNAL_FORMAT_INFO",
+    "ImageIORegistry",
+    "SignalIORegistry",
+    "read_image",
+    "read_images",
+    "read_metadata",
+    "read_roi",
+    "read_roi_grid",
+    "read_signal",
+    "read_signals",
+    "write_image",
+    "write_images",
+    "write_metadata",
+    "write_roi",
+    "write_roi_grid",
+    "write_signal",
+    "write_signals",
+]
+
+SIGNAL_FORMAT_INFO = SignalIORegistry.get_format_info(mode="rst")
+IMAGE_FORMAT_INFO = ImageIORegistry.get_format_info(mode="rst")

sigima/io/base.py

@@ -0,0 +1,311 @@
+# Copyright (c) DataLab Platform Developers, BSD 3-Clause license, see LICENSE file.
+
+"""
+Sigima Common tools for signal and image io support
+"""
+
+# pylint: disable=invalid-name  # Allows short reference names like x, y, ...
+
+from __future__ import annotations
+
+import dataclasses
+import enum
+import os
+import os.path as osp
+import re
+from typing import Generic, Literal, Sequence
+
+from sigima.config import _
+from sigima.objects.base import BaseObj, TypeObj
+from sigima.worker import CallbackWorkerProtocol
+
+
+class IOAction(enum.Enum):
+    """I/O action type"""
+
+    LOAD = enum.auto()
+    SAVE = enum.auto()
+
+
+@dataclasses.dataclass
+class FormatInfo:
+    """Format info"""
+
+    name: str = None  # e.g. "Foobar camera image files"
+    extensions: str = None  # e.g. "*.foobar *.fb"
+    readable: bool = False  # True if format can be read
+    writeable: bool = False  # True if format can be written
+    requires: list[str] = None  # e.g. ["foobar"] if format requires foobar package
+
+    def __str__(self) -> str:
+        """Return string representation of format info"""
+        return f"""{self.name}:
+    Extensions: {self.extensions}
+    Readable:   {"Yes" if self.readable else "No"}
+    Writeable:  {"Yes" if self.writeable else "No"}
+    Requires:   {", ".join(self.requires) if self.requires else "None"}"""
+
+    def to_rst_table_row(self) -> str:
+        """Return reStructuredText table row for format info
+        (table `.. list-table::` format, with 5 columns)"""
+        return f"""    * - {self.name}
+      - {self.extensions}
+      - {"•" if self.readable else ""}
+      - {"•" if self.writeable else ""}
+      - {", ".join(self.requires) if self.requires else "-"}"""
+
+
+class FormatBase(Generic[TypeObj]):
+    """Object representing a data file io"""
+
+    FORMAT_INFO: FormatInfo = None
+
+    def __init__(self):
+        self.info = self.FORMAT_INFO
+        if self.info is None:
+            raise ValueError(f"Format info not set for {self.__class__.__name__}")
+        if self.info.name is None:
+            raise ValueError(f"Format name not set for {self.__class__.__name__}")
+        if self.info.extensions is None:
+            raise ValueError(f"Format extensions not set for {self.__class__.__name__}")
+        if not self.info.readable and not self.info.writeable:
+            raise ValueError(f"Format {self.info.name} is not readable nor writeable")
+        self.extlist = get_file_extensions(self.info.extensions)
+        if not self.extlist:
+            raise ValueError(f"Invalid format extensions for {self.__class__.__name__}")
+        if self.info.requires:
+            for package in self.info.requires:
+                try:
+                    __import__(package)
+                except ImportError as exc:
+                    raise ImportError(
+                        f"Format {self.info.name} requires {package} package"
+                    ) from exc
+
+    def get_filter(self, action: IOAction) -> str | None:
+        """Return file filter for Qt file dialog
+
+        Args:
+            action: I/O action type
+
+        Returns:
+            File filter string
+        """
+        assert action in (IOAction.LOAD, IOAction.SAVE)
+        if action == IOAction.LOAD and not self.info.readable:
+            return None
+        if action == IOAction.SAVE and not self.info.writeable:
+            return None
+        return f"{self.info.name} ({self.info.extensions})"
+
+    def read(
+        self, filename: str, worker: CallbackWorkerProtocol | None = None
+    ) -> Sequence[TypeObj]:
+        """Read list of native objects (signal or image) from file.
+        For single object, return a list with one object.
+
+        Args:
+            filename: file name
+            worker: Callback worker object
+
+        Raises:
+            NotImplementedError: if format is not supported
+
+        Returns:
+            List of native objects (signal or image)
+        """
+        raise NotImplementedError(f"Reading from {self.info.name} is not supported")
+
+    def write(self, filename: str, obj: BaseObj) -> None:
+        """Write data to file
+
+        Args:
+            filename: file name
+            obj: native object (signal or image)
+
+        Raises:
+            NotImplementedError: if format is not supported
+        """
+        raise NotImplementedError(f"Writing to {self.info.name} is not supported")
+
+
+#  pylint: disable=bad-mcs-classmethod-argument
+class BaseIORegistry(Generic[TypeObj], type):
+    """Metaclass for registering I/O handler classes"""
+
+    REGISTRY_INFO: str = ""  # Registry info, override in subclasses
+
+    _io_format_instances: list[FormatBase] = []
+
+    def __init__(cls, name, bases, attrs):
+        super().__init__(name, bases, attrs)
+        if not name.endswith("FormatBase"):
+            try:
+                #  pylint: disable=no-value-for-parameter
+                cls._io_format_instances.append(cls())
+            except ImportError:
+                # This format is not supported
+                pass
+
+    @classmethod
+    def get_formats(cls) -> list[FormatBase]:
+        """Return I/O format handlers
+
+        Returns:
+            List of I/O format handlers
+        """
+        return cls._io_format_instances
+
+    @classmethod
+    def get_format_info(cls, mode: Literal["rst", "text"] = "rst") -> str:
+        """Return I/O format info
+
+        Args:
+            mode: Output format, either 'rst' (reStructuredText) or 'text'
+
+        Returns:
+            Text description for all I/O formats
+        """
+        if mode == "rst":
+            txt = f"{cls.REGISTRY_INFO}:\n\n.. list-table::\n    :header-rows: 1\n\n"
+            txt += "    * - Name\n      - Extensions\n      "
+            txt += "- Readable\n      - Writeable\n      - Requires\n"
+            txt += "\n".join([fmt.info.to_rst_table_row() for fmt in cls.get_formats()])
+        else:
+            txt = f"{cls.REGISTRY_INFO}:{os.linesep}"
+            indent = " " * 4
+            finfo = "\n".join([str(fmt.info) for fmt in cls.get_formats()])
+            txt += "\n".join([indent + line for line in finfo.splitlines()])
+        return txt
+
+    @classmethod
+    def __get_all_supported_filter(cls, action: IOAction) -> str:
+        """Return all supported file filter for Qt file dialog
+
+        Args:
+            action: I/O action type
+
+        Returns:
+            File filter
+        """
+        extlist = []  # file extension list
+        for fmt in cls.get_formats():
+            fmt: FormatBase
+            if not fmt.info.readable and action == IOAction.LOAD:
+                continue
+            if not fmt.info.writeable and action == IOAction.SAVE:
+                continue
+            extlist.extend(fmt.extlist)
+        allsupported = _("All supported files")
+        return f"{allsupported} ({'*.' + ' *.'.join(extlist)})"
+
+    @classmethod
+    def get_filters(cls, action: IOAction) -> str:
+        """Return file filters for Qt file dialog
+
+        Args:
+            action: I/O action type
+
+        Returns:
+            File filters
+        """
+        flist = []  # file filter list
+        flist.append(cls.__get_all_supported_filter(action))
+        for fmt in cls.get_formats():
+            fmt: FormatBase
+            flt = fmt.get_filter(action)
+            if flt is not None:
+                flist.append(flt)
+        return "\n".join(flist)
+
+    @classmethod
+    def get_read_filters(cls) -> str:
+        """Return file filters for Qt open file dialog
+
+        Returns:
+            File filters
+        """
+        return cls.get_filters(IOAction.LOAD)
+
+    @classmethod
+    def get_write_filters(cls) -> str:
+        """Return file filters for Qt save file dialog
+
+        Returns:
+            File filters
+        """
+        return cls.get_filters(IOAction.SAVE)
+
+    @classmethod
+    def get_format(cls, filename: str, action: IOAction) -> FormatBase:
+        """Return format handler for filename
+
+        Args:
+            filename: file name
+            action: I/O action type
+
+        Raises:
+            NotImplementedError: if file data type is not supported
+
+        Returns:
+            Format handler
+        """
+        for fmt in cls.get_formats():
+            fmt: FormatBase
+            if osp.splitext(filename)[1][1:].lower() in fmt.extlist:
+                if not fmt.info.readable and action == IOAction.LOAD:
+                    continue
+                if not fmt.info.writeable and action == IOAction.SAVE:
+                    continue
+                return fmt
+        raise NotImplementedError(
+            f"{filename} is not supported for {action.name.lower()}"
+        )
+
+    @classmethod
+    def read(
+        cls, filename: str, worker: CallbackWorkerProtocol | None = None
+    ) -> Sequence[TypeObj]:
+        """Read data from file, return native object (signal or image) list.
+        For single object, return a list with one object.
+
+        Args:
+            filename: file name
+            worker: Callback worker object
+
+        Raises:
+            NotImplementedError: if file data type is not supported
+
+        Returns:
+            List of native objects (signal or image)
+        """
+        fmt = cls.get_format(filename, IOAction.LOAD)
+        return fmt.read(filename, worker)
+
+    @classmethod
+    def write(cls, filename: str, obj: BaseObj) -> None:
+        """Write data to file from native object (signal or image).
+
+        Args:
+            filename: file name
+            obj: native object (signal or image)
+
+        Raises:
+            NotImplementedError: if file data type is not supported
+        """
+        fmt = cls.get_format(filename, IOAction.SAVE)
+        fmt.write(filename, obj)
+
+
+def get_file_extensions(string: str) -> list[str]:
+    """Return a sorted list of unique file extensions contained in `string`.
+
+    Args:
+        string: String containing file extensions.
+
+    Returns:
+        List of file extensions.
+    """
+    pattern = r"\S+\.[\w-]+"
+    matches = re.findall(pattern, string)
+    return sorted({match.split(".")[-1].lower() for match in matches})