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

sigima/objects/base.py

@@ -0,0 +1,937 @@
+# Copyright (c) DataLab Platform Developers, BSD 3-Clause license, see LICENSE file.
+
+"""
+Base model classes for signals and images.
+"""
+
+# pylint: disable=invalid-name  # Allows short reference names like x, y, ...
+
+from __future__ import annotations
+
+import abc
+import re
+import sys
+from collections.abc import Generator
+from copy import deepcopy
+from typing import Any, Generic, Iterator, Type, TypeVar
+
+import guidata.dataset as gds
+import numpy as np
+from numpy import ma
+
+from sigima.config import _
+
+if sys.version_info >= (3, 11):
+    # Use Self from typing module in Python 3.11+
+    from typing import Self
+else:
+    # Use Self from typing_extensions module in Python < 3.11
+    from typing_extensions import Self
+
+ROI_KEY = "_roi_"
+
+
+def deepcopy_metadata(
+    metadata: dict[str, Any],
+    special_keys: set[str] | None = None,
+    all_metadata: bool = False,
+) -> dict[str, Any]:
+    """Deepcopy metadata, except keys starting with "_" (private keys)
+    with the exception of "_roi_" and "_ann_" keys.
+
+    Args:
+        metadata: Metadata dictionary to deepcopy.
+        special_keys: Set of keys that should not be removed even if they
+         start with "_".
+        all_metadata: if True, copy all metadata, including private keys
+
+    Returns:
+        A new dictionary with deepcopied metadata, excluding private keys
+        except those in `special_keys`.
+    """
+    if special_keys is None:
+        special_keys = set([ROI_KEY])
+    mdcopy = {}
+    for key, value in metadata.items():
+        if not key.startswith("_") or key in special_keys or all_metadata:
+            mdcopy[key] = deepcopy(value)
+    return mdcopy
+
+
+class BaseProcParam(gds.DataSet):
+    """Base class for processing parameters."""
+
+    def apply_integer_range(self, vmin, vmax):  # pylint: disable=unused-argument
+        """Do something in case of integer min-max range."""
+
+    def apply_float_range(self, vmin, vmax):  # pylint: disable=unused-argument
+        """Do something in case of float min-max range."""
+
+    def set_from_datatype(self, dtype):
+        """Set min/max range from NumPy datatype."""
+        if np.issubdtype(dtype, np.integer):
+            info = np.iinfo(dtype)
+            self.apply_integer_range(info.min, info.max)
+        else:
+            info = np.finfo(dtype)
+            self.apply_float_range(info.min, info.max)
+
+
+class BaseRandomParam(BaseProcParam):
+    """Random signal/image parameters."""
+
+    seed = gds.IntItem(_("Seed"), default=1)
+
+
+class UniformDistributionParam(BaseRandomParam):
+    """Uniform-distribution signal/image parameters."""
+
+    def apply_integer_range(self, vmin, vmax):
+        """Do something in case of integer min-max range."""
+        self.vmin, self.vmax = float(vmin), float(vmax)
+
+    vmin = gds.FloatItem(
+        "V<sub>min</sub>", default=-0.5, help=_("Uniform distribution lower bound")
+    )
+    vmax = gds.FloatItem(
+        "V<sub>max</sub>", default=0.5, help=_("Uniform distribution higher bound")
+    ).set_pos(col=1)
+
+    def generate_title(self) -> str:
+        """Generate a title based on current parameters."""
+        return f"UniformRandom(vmin={self.vmin:g},vmax={self.vmax:g},seed={self.seed})"
+
+
+class NormalDistributionParam(BaseRandomParam):
+    """Normal-distribution signal/image parameters."""
+
+    DEFAULT_RELATIVE_MU = 0.1
+    DEFAULT_RELATIVE_SIGMA = 0.02
+
+    def apply_integer_range(self, vmin, vmax):
+        """Do something in case of integer min-max range."""
+        delta = vmax - vmin
+        self.mu = float(vmin + self.DEFAULT_RELATIVE_MU * delta)
+        self.sigma = float(self.DEFAULT_RELATIVE_SIGMA * delta)
+
+    mu = gds.FloatItem(
+        "μ", default=DEFAULT_RELATIVE_MU, help=_("Normal distribution mean")
+    )
+    sigma = gds.FloatItem(
+        "σ",
+        default=DEFAULT_RELATIVE_SIGMA,
+        min=0.0,
+        help=_("Normal distribution standard deviation"),
+    ).set_pos(col=1)
+
+    def generate_title(self) -> str:
+        """Generate a title based on current parameters."""
+        return f"NormalRandom(μ={self.mu:g},σ={self.sigma:g},seed={self.seed})"
+
+
+class PoissonDistributionParam(BaseRandomParam):
+    """Base Poisson-distribution signal/image parameters."""
+
+    DEFAULT_RELATIVE_LAMBDA = 0.1
+
+    def apply_integer_range(self, vmin, vmax):
+        """Adjust default λ based on integer min-max range."""
+        positive_span = max(0.0, float(vmax) - max(0.0, float(vmin)))
+        self.lam = float(max(self.DEFAULT_RELATIVE_LAMBDA * positive_span, 1.0))
+
+    lam = gds.FloatItem(
+        "λ",
+        default=DEFAULT_RELATIVE_LAMBDA,
+        min=0.0,
+        help=_("Poisson distribution mean"),
+    )
+
+    def generate_title(self) -> str:
+        """Generate a title based on current parameters."""
+        return f"PoissonRandom(λ={self.lam:g},seed={self.seed})"
+
+
+TypeObj = TypeVar("TypeObj", bound="BaseObj")
+TypeROIParam = TypeVar("TypeROIParam", bound="BaseROIParam")
+TypeSingleROI = TypeVar("TypeSingleROI", bound="BaseSingleROI")
+TypeROI = TypeVar("TypeROI", bound="BaseROI")
+
+
+class BaseObjMeta(abc.ABCMeta, gds.DataSetMeta):
+    """Mixed metaclass to avoid conflicts"""
+
+
+class NoDefaultOption:
+    """Marker class for metadata option without default value"""
+
+
+class BaseObj(Generic[TypeROI], metaclass=BaseObjMeta):
+    """Object (signal/image) interface"""
+
+    #: Class attribute that defines a string prefix used to uniquely identify instances
+    #: of this class in metadata serialization. Each subclass should override this with
+    #: a unique identifier (e.g., "s" for signals, "i" for images).
+    #: This prefix is used as part of the key for storing and retrieving object-specific
+    #: metadata, supporting type-based serialization and deserialization.
+    PREFIX = ""  # This is overriden in children classes
+
+    # This is overriden in children classes with a gds.DictItem instance:
+    metadata: dict[str, Any] = {}
+    annotations: str = ""
+
+    #: Class attribute that defines a tuple of valid NumPy data types supported by this
+    #: class. This is used to validate the data type of the object when it is set or
+    #: modified and to ensure that the object can handle the data correctly.
+    #: Subclasses should override this with a specific set of valid data types.
+    VALID_DTYPES = (np.float64,)  # To be overriden in children classes
+
+    def __init__(self):
+        self.__roi_changed: bool | None = None
+        self._maskdata_cache: np.ndarray | None = None
+        self.__metadata_options_defaults: dict[str, Any] = {}
+        self.__roi_cache: TypeROI | None = None
+
+    @staticmethod
+    @abc.abstractmethod
+    def get_roi_class() -> Type[TypeROI]:
+        """Return ROI class"""
+
+    @property
+    @abc.abstractmethod
+    def data(self) -> np.ndarray | None:
+        """Data"""
+
+    @classmethod
+    def get_valid_dtypenames(cls) -> list[str]:
+        """Get valid data type names
+
+        Returns:
+            Valid data type names supported by this class
+        """
+        return [
+            dtname
+            for dtname in np.sctypeDict
+            if isinstance(dtname, str)
+            and dtname in (dtype.__name__ for dtype in cls.VALID_DTYPES)
+        ]
+
+    def check_data(self):
+        """Check if data is valid, raise an exception if that's not the case
+
+        Raises:
+            TypeError: if data type is not supported
+        """
+        if self.data is not None:
+            if self.data.dtype not in self.VALID_DTYPES:
+                raise TypeError(f"Unsupported data type: {self.data.dtype}")
+
+    def iterate_roi_indices(self) -> Generator[int | None, None, None]:
+        """Iterate over object ROI indices (if there is no ROI, yield None)"""
+        if self.roi is None:
+            yield None
+        else:
+            yield from range(len(self.roi))
+
+    @abc.abstractmethod
+    def get_data(self, roi_index: int | None = None) -> np.ndarray:
+        """
+        Return original data (if ROI is not defined or `roi_index` is None),
+        or ROI data (if both ROI and `roi_index` are defined).
+
+        Args:
+            roi_index: ROI index
+
+        Returns:
+            Data
+        """
+
+    @abc.abstractmethod
+    def copy(
+        self,
+        title: str | None = None,
+        dtype: np.dtype | None = None,
+        all_metadata: bool = False,
+    ) -> Self:
+        """Copy object.
+
+        Args:
+            title: title
+            dtype: data type
+            all_metadata: if True, copy all metadata, otherwise only basic metadata
+
+        Returns:
+            Copied object
+        """
+
+    @abc.abstractmethod
+    def set_data_type(self, dtype):
+        """Change data type.
+
+        Args:
+            dtype: data type
+        """
+
+    @abc.abstractmethod
+    def physical_to_indices(self, coords: list[float]) -> list[int]:
+        """Convert coordinates from physical (real world) to indices
+
+        Args:
+            coords: coordinates
+
+        Returns:
+            Indices
+        """
+
+    @abc.abstractmethod
+    def indices_to_physical(self, indices: list[int]) -> list[float]:
+        """Convert coordinates from indices to physical (real world)
+
+        Args:
+            indices: indices
+
+        Returns:
+            Coordinates
+        """
+
+    def roi_has_changed(self) -> bool:
+        """Return True if ROI has changed since last call to this method.
+
+        The first call to this method will return True if ROI has not yet been set,
+        or if ROI has been set and has changed since the last call to this method.
+        The next call to this method will always return False if ROI has not changed
+        in the meantime.
+
+        Returns:
+            True if ROI has changed
+        """
+        if self.__roi_changed is None:
+            self.__roi_changed = True
+        returned_value = self.__roi_changed
+        self.__roi_changed = False
+        return returned_value
+
+    @property
+    def roi(self) -> TypeROI | None:
+        """Return object regions of interest object.
+
+        Returns:
+            Regions of interest object
+        """
+        # If we have a cached ROI, return it
+        if self.__roi_cache is not None:
+            return self.__roi_cache
+
+        # Otherwise, try to load from metadata
+        roidata = self.metadata.get(ROI_KEY)
+        if roidata is None:
+            return None
+        if not isinstance(roidata, dict):
+            # Old or unsupported format: remove it
+            self.metadata.pop(ROI_KEY)
+            return None
+
+        # Create ROI from metadata and cache it
+        self.__roi_cache = self.get_roi_class().from_dict(roidata)
+        return self.__roi_cache
+
+    @roi.setter
+    def roi(self, roi: TypeROI | None) -> None:
+        """Set object regions of interest.
+
+        Args:
+            roi: regions of interest object
+        """
+        # Cache the ROI object
+        self.__roi_cache = roi
+
+        # Update metadata
+        if roi is None:
+            if ROI_KEY in self.metadata:
+                self.metadata.pop(ROI_KEY)
+        else:
+            self.metadata[ROI_KEY] = roi.to_dict()
+        self.__roi_changed = True
+
+    @property
+    def maskdata(self) -> np.ndarray | None:
+        """Return masked data (areas outside defined regions of interest)
+
+        Returns:
+            Masked data
+        """
+        roi_changed = self.roi_has_changed()
+        if self.roi is None:
+            if roi_changed:
+                self._maskdata_cache = None
+        elif roi_changed or self._maskdata_cache is None:
+            self._maskdata_cache = self.roi.to_mask(self)
+        return self._maskdata_cache
+
+    def get_masked_view(self) -> ma.MaskedArray:
+        """Return masked view for data
+
+        Returns:
+            Masked view
+        """
+        assert isinstance(self.data, np.ndarray)
+        view = self.data.view(ma.MaskedArray)
+        if self.maskdata is None:
+            view.mask = np.isnan(self.data)
+        else:
+            view.mask = self.maskdata | np.isnan(self.data)
+        return view
+
+    def invalidate_maskdata_cache(self) -> None:
+        """Invalidate mask data cache: force to rebuild it"""
+        self._maskdata_cache = None
+
+    def invalidate_roi_cache(self) -> None:
+        """Invalidate ROI cache: force to reload it from metadata"""
+        self.__roi_cache = None
+        # Also invalidate mask data cache since ROI data might have changed
+        self.invalidate_maskdata_cache()
+
+    def sync_roi_to_metadata(self) -> None:
+        """Synchronize the current ROI cache to metadata.
+
+        This should be called after modifying the ROI object directly
+        to ensure the changes are persisted in metadata.
+        """
+        if self.__roi_cache is not None:
+            self.metadata[ROI_KEY] = self.__roi_cache.to_dict()
+            self.__roi_changed = True
+            # Also invalidate mask data cache since ROI has changed
+            self.invalidate_maskdata_cache()
+
+    def mark_roi_as_changed(self) -> None:
+        """Mark the ROI as changed and invalidate dependent caches.
+
+        This should be called after modifying the ROI object directly
+        to ensure all dependent data (like mask cache) is properly invalidated.
+        """
+        self.__roi_changed = True
+        self.invalidate_maskdata_cache()
+        # Optionally sync to metadata immediately
+        self.sync_roi_to_metadata()
+
+    def update_metadata_from(self, other_metadata: dict[str, Any]) -> None:
+        """Update metadata from another object's metadata (merge result shapes and
+        annotations, and update the rest of the metadata).
+
+        Args:
+            other_metadata: other object metadata
+        """
+        self.metadata.update(other_metadata)
+        # Invalidate ROI cache since metadata might have changed ROI data
+        self.invalidate_roi_cache()
+
+    # Method to set the default values of metadata options:
+    def set_metadata_options_defaults(
+        self, defaults: dict[str, Any], overwrite: bool = False
+    ) -> None:
+        """Set default values for metadata options
+
+        A metadata option is a metadata entry starting with a double underscore.
+        It is a way to store application-specific options in object metadata.
+
+        .. note::
+
+            This will not overwrite existing metadata options
+            (unless `overwrite` is True).
+            It will only set the default values for options that are not already set.*
+            Use `reset_metadata_to_defaults` method to reset all metadata options
+            to their default values.
+
+        Args:
+            defaults: dictionary of default values for metadata options
+            overwrite: whether to overwrite existing metadata options (default: False)
+        """
+        self.__metadata_options_defaults.update(defaults)
+        for key, value in defaults.items():
+            self.set_metadata_option(key, value, overwrite)
+
+    def get_metadata_options_defaults(self) -> dict[str, Any]:
+        """Return default values for metadata options
+
+        A metadata option is a metadata entry starting with a double underscore.
+        It is a way to store application-specific options in object metadata.
+
+        Returns:
+            Dictionary of default values for metadata options
+        """
+        return self.__metadata_options_defaults
+
+    def get_metadata_option(self, name: str, default: Any = NoDefaultOption) -> Any:
+        """Return metadata option value
+
+        A metadata option is a metadata entry starting with a double underscore.
+        It is a way to store application-specific options in object metadata.
+
+        Args:
+            name: option name
+            default: default value if option is not set (optional)
+
+        Returns:
+            Option value
+
+        Raises:
+            ValueError: if option name is invalid
+        """
+        if (
+            default is not NoDefaultOption
+            and name not in self.__metadata_options_defaults
+        ):
+            # If default is provided, store it in defaults
+            # and set it as the option value
+            self.__metadata_options_defaults[name] = default
+            self.set_metadata_option(name, default, overwrite=False)
+        try:
+            value = self.metadata[f"__{name}"]
+        except KeyError as exc:
+            defaults = self.get_metadata_options_defaults()
+            if name in defaults:
+                value = defaults[name]
+            else:
+                raise ValueError(
+                    f"Invalid metadata option name `{name}` "
+                    f"(valid names: {', '.join(defaults.keys())})"
+                ) from exc
+        return value
+
+    def set_metadata_option(
+        self, name: str, value: Any, overwrite: bool = True
+    ) -> None:
+        """Set metadata option value
+
+        A metadata option is a metadata entry starting with a double underscore.
+        It is a way to store application-specific options in object metadata.
+
+        Args:
+            name: option name
+            value: option value
+            overwrite: whether to overwrite existing metadata options (default: True)
+
+        Raises:
+            ValueError: if option name is invalid
+        """
+        if overwrite or f"__{name}" not in self.metadata:
+            self.metadata[f"__{name}"] = value
+
+    def get_metadata_options(self) -> dict[str, Any]:
+        """Return metadata options
+        A metadata option is a metadata entry starting with a double underscore.
+
+        Returns:
+            Dictionary of metadata options (name: value)
+        """
+        options = {}
+        for name, value in self.metadata.items():
+            if name.startswith("__"):
+                options[name[2:]] = value
+        return options
+
+    def reset_metadata_to_defaults(self) -> None:
+        """Reset metadata to default values"""
+        self.metadata = {}
+        self.invalidate_roi_cache()
+        defaults = self.get_metadata_options_defaults()
+        for name, value in defaults.items():
+            self.set_metadata_option(name, value)
+
+    def save_attr_to_metadata(self, attrname: str, new_value: Any) -> None:
+        """Save attribute to metadata
+
+        Args:
+            attrname: attribute name
+            new_value: new value
+        """
+        value = getattr(self, attrname)
+        if value:
+            self.metadata[f"orig_{attrname}"] = value
+        setattr(self, attrname, new_value)
+
+    def restore_attr_from_metadata(self, attrname: str, default: Any) -> None:
+        """Restore attribute from metadata
+
+        Args:
+            attrname: attribute name
+            default: default value
+        """
+        value = self.metadata.pop(f"orig_{attrname}", default)
+        setattr(self, attrname, value)
+
+
+class BaseROIParamMeta(abc.ABCMeta, gds.DataSetMeta):
+    """Mixed metaclass to avoid conflicts"""
+
+
+class BaseROIParam(
+    gds.DataSet,
+    Generic[TypeObj, TypeSingleROI],  # type: ignore
+    metaclass=BaseROIParamMeta,
+):
+    """Base class for ROI parameters"""
+
+    @abc.abstractmethod
+    def to_single_roi(self, obj: TypeObj) -> TypeSingleROI:
+        """Convert parameters to single ROI
+
+        Args:
+            obj: object (signal/image)
+
+        Returns:
+            Single ROI
+        """
+
+
+class BaseSingleROI(Generic[TypeObj, TypeROIParam], abc.ABC):  # type: ignore
+    """Base class for single ROI
+
+    Args:
+        coords: ROI edge (physical or pixel coordinates)
+        indices: if True, coords are indices (pixels) instead of physical coordinates
+        title: ROI title
+    """
+
+    def __init__(
+        self,
+        coords: np.ndarray | list[int] | list[float],
+        indices: bool,
+        title: str = "ROI",
+    ) -> None:
+        self.coords = np.array(coords, int if indices else float)
+        self.indices = indices
+        self.title = title
+        self.check_coords()
+
+    def __eq__(self, other: BaseSingleROI | None) -> bool:
+        """Test equality with another single ROI"""
+        if other is None:
+            return False
+        if not isinstance(other, BaseSingleROI):
+            raise TypeError(f"Cannot compare {type(self)} with {type(other)}")
+        return (
+            np.array_equal(self.coords, other.coords) and self.indices == other.indices
+        )
+
+    def get_physical_coords(self, obj: TypeObj) -> list[float]:
+        """Return physical coords
+
+        Args:
+            obj: object (signal/image)
+
+        Returns:
+            Physical coords
+        """
+        if self.indices:
+            return obj.indices_to_physical(self.coords.tolist())
+        return self.coords.tolist()
+
+    def set_physical_coords(self, obj: TypeObj, coords: np.ndarray) -> None:
+        """Set physical coords
+
+        Args:
+            obj: object (signal/image)
+            coords: physical coords
+        """
+        if self.indices:
+            self.coords = np.array(obj.physical_to_indices(coords.tolist()))
+        else:
+            self.coords = np.array(coords, float)
+
+    def get_indices_coords(self, obj: TypeObj) -> list[int]:
+        """Return indices coords
+
+        Args:
+            obj: object (signal/image)
+
+        Returns:
+            Indices coords
+        """
+        if self.indices:
+            return self.coords.tolist()
+        return obj.physical_to_indices(self.coords.tolist())
+
+    def set_indices_coords(self, obj: TypeObj, coords: np.ndarray) -> None:
+        """Set indices coords
+
+        Args:
+            obj: object (signal/image)
+            coords: indices coords
+        """
+        if self.indices:
+            self.coords = coords
+        else:
+            self.coords = np.array(obj.indices_to_physical(self.coords.tolist()))
+
+    @abc.abstractmethod
+    def check_coords(self) -> None:
+        """Check if coords are valid
+
+        Raises:
+            ValueError: invalid coords
+        """
+
+    @abc.abstractmethod
+    def to_mask(self, obj: TypeObj) -> np.ndarray:
+        """Create mask from ROI
+
+        Args:
+            obj: signal or image object
+
+        Returns:
+            Mask (boolean array where True values are inside the ROI)
+        """
+
+    @abc.abstractmethod
+    def to_param(self, obj: TypeObj, index: int) -> TypeROIParam:
+        """Convert ROI to parameters
+
+        Args:
+            obj: object (signal/image), for physical-indices coordinates conversion
+            index: ROI index
+        """
+
+    def to_dict(self) -> dict:
+        """Convert ROI to dictionary
+
+        Returns:
+            Dictionary
+        """
+        return {
+            "coords": self.coords,
+            "indices": self.indices,
+            "title": self.title,
+            "type": type(self).__name__,
+        }
+
+    @classmethod
+    def from_dict(cls: Type[TypeSingleROI], dictdata: dict) -> TypeSingleROI:
+        """Convert dictionary to ROI
+
+        Args:
+            dictdata: dictionary
+
+        Returns:
+            ROI
+        """
+        return cls(dictdata["coords"], dictdata["indices"], dictdata["title"])
+
+
+class BaseROI(Generic[TypeObj, TypeSingleROI, TypeROIParam], abc.ABC):  # type: ignore
+    """Abstract base class for ROIs (Regions of Interest)
+
+    Args:
+        inverse: if True, ROI is outside the region of interest
+    """
+
+    #: Class attribute that defines a string prefix used for identifying ROI types
+    #: in object metadata. This prefix is used when serializing and deserializing ROIs,
+    #: allowing the system to determine the appropriate ROI class for reconstruction.
+    #: Each ROI subclass should override this with a unique string identifier.
+    PREFIX = ""  # This is overriden in children classes
+
+    def __init__(self) -> None:
+        self.single_rois: list[TypeSingleROI] = []
+
+    @staticmethod
+    @abc.abstractmethod
+    def get_compatible_single_roi_classes() -> list[Type[BaseSingleROI]]:
+        """Return compatible single ROI classes"""
+
+    def __len__(self) -> int:
+        """Return number of ROIs"""
+        return len(self.single_rois)
+
+    def __iter__(self) -> Iterator[TypeSingleROI]:
+        """Iterate over single ROIs"""
+        return iter(self.single_rois)
+
+    def __eq__(self, other: BaseROI | None) -> bool:
+        """Test equality with another ROI"""
+        if other is None:
+            return False
+        if not isinstance(other, BaseROI):
+            raise TypeError(f"Cannot compare {type(self)} with {type(other)}")
+        return self.single_rois == other.single_rois
+
+    def get_single_roi(self, index: int) -> TypeSingleROI:
+        """Return single ROI at index
+
+        Args:
+            index: ROI index
+        """
+        return self.single_rois[index]
+
+    def set_single_roi(self, index: int, roi: TypeSingleROI) -> None:
+        """Set single ROI at index
+
+        Args:
+            index: ROI index
+            roi: ROI to set
+        """
+        self.single_rois[index] = roi
+
+    def get_single_roi_title(self, index: int) -> str:
+        """Generate title for single ROI, based on its index, using either the
+        ROI title or a default generic title as fallback.
+
+        Args:
+            index: ROI index
+        """
+        single_roi = self.get_single_roi(index)
+        title = single_roi.title or get_generic_roi_title(index)
+        return title
+
+    def is_empty(self) -> bool:
+        """Return True if no ROI is defined"""
+        return len(self) == 0
+
+    @classmethod
+    def create(
+        cls: Type[BaseROI], single_roi: TypeSingleROI
+    ) -> BaseROI[TypeObj, TypeSingleROI, TypeROIParam]:
+        """Create Regions of Interest object from a single ROI.
+
+        Args:
+            single_roi: single ROI
+
+        Returns:
+            Regions of Interest object
+        """
+        roi = cls()
+        roi.add_roi(single_roi)
+        return roi
+
+    def copy(self) -> BaseROI[TypeObj, TypeSingleROI, TypeROIParam]:
+        """Return a copy of ROIs"""
+        return deepcopy(self)
+
+    def empty(self) -> None:
+        """Empty ROIs"""
+        self.single_rois.clear()
+
+    def combine_with(
+        self, other: BaseROI[TypeObj, TypeSingleROI, TypeROIParam]
+    ) -> BaseROI[TypeObj, TypeSingleROI, TypeROIParam]:
+        """Combine ROIs with another ROI object, by merging single ROIs (and ignoring
+        duplicate single ROIs) and returning a new combined ROI object.
+
+        Args:
+            other: other ROI object
+
+        Returns:
+            Combined ROIs object
+        """
+        if not isinstance(other, type(self)):
+            raise TypeError(f"Cannot combine {type(self)} with {type(other)}")
+        combined_roi = self.copy()
+        for roi in other.single_rois:
+            if all(s_roi != roi for s_roi in self.single_rois):
+                combined_roi.single_rois.append(roi)
+        return combined_roi
+
+    def add_roi(
+        self, roi: TypeSingleROI | BaseROI[TypeObj, TypeSingleROI, TypeROIParam]
+    ) -> None:
+        """Add ROI.
+
+        Args:
+            roi: ROI
+
+        Raises:
+            TypeError: if roi type is not supported (not a single ROI or a ROI)
+            ValueError: if `inverse` values are incompatible
+        """
+        if isinstance(roi, BaseSingleROI):
+            self.single_rois.append(roi)
+        elif isinstance(roi, BaseROI):
+            self.single_rois.extend(roi.single_rois)
+        else:
+            raise TypeError(f"Unsupported ROI type: {type(roi)}")
+
+    @abc.abstractmethod
+    def to_mask(self, obj: TypeObj) -> np.ndarray:
+        """Create mask from ROI
+
+        Args:
+            obj: signal or image object
+
+        Returns:
+            Mask (boolean array where True values are inside the ROI)
+        """
+
+    def to_params(self, obj: TypeObj) -> list[TypeROIParam]:
+        """Convert ROIs to a list of parameters
+
+        Args:
+            obj: object (signal/image), for physical to pixel conversion
+
+        Returns:
+            ROI parameters
+        """
+        return [iroi.to_param(obj, index=idx) for idx, iroi in enumerate(self)]
+
+    @classmethod
+    def from_params(
+        cls: Type[BaseROI],
+        obj: TypeObj,
+        params: list[TypeROIParam],
+    ) -> BaseROI[TypeObj, TypeSingleROI, TypeROIParam]:
+        """Create ROIs from parameters
+
+        Args:
+            obj: object (signal/image)
+            params: ROI parameters
+
+        Returns:
+            ROIs
+        """
+        roi = cls()
+        for param in params:
+            assert isinstance(param, BaseROIParam), "Invalid ROI parameter type"
+            roi.add_roi(param.to_single_roi(obj))
+        return roi
+
+    def to_dict(self) -> dict:
+        """Convert ROIs to dictionary
+
+        Returns:
+            Dictionary
+        """
+        return {
+            "single_rois": [roi.to_dict() for roi in self.single_rois],
+        }
+
+    @classmethod
+    def from_dict(cls: Type[TypeROI], dictdata: dict) -> TypeROI:
+        """Convert dictionary to ROIs
+
+        Args:
+            dictdata: dictionary
+
+        Returns:
+            ROIs
+        """
+        instance = cls()
+        if not all(key in dictdata for key in ["single_rois"]):
+            raise ValueError("Invalid ROI: dictionary must contain 'single_rois' key")
+        instance.single_rois = []
+        for single_roi in dictdata["single_rois"]:
+            for single_roi_class in instance.get_compatible_single_roi_classes():
+                if single_roi["type"] == single_roi_class.__name__:
+                    instance.single_rois.append(single_roi_class.from_dict(single_roi))
+                    break
+            else:
+                raise ValueError(f"Unsupported single ROI type: {single_roi['type']}")
+        return instance
+
+
+GENERIC_ROI_TITLE_REGEXP = r"ROI(\d+)"
+
+
+def get_generic_roi_title(index: int) -> None:
+    """Return a generic title for the ROI"""
+    title = f"ROI{index:02d}"
+    assert re.match(GENERIC_ROI_TITLE_REGEXP, title)
+    return title