# Copyright (c) DataLab Platform Developers, BSD 3-Clause license, see LICENSE file.
"""
Image ROI classes
=================
This module defines ROI (Region of Interest) classes and utilities for images.
The module provides:
- `ROI2DParam`: Parameter class for 2D image ROIs
- `BaseSingleImageROI`: Base class for single image ROIs
- `RectangularROI`: Rectangular ROI implementation
- `CircularROI`: Circular ROI implementation
- `PolygonalROI`: Polygonal ROI implementation
- `ImageROI`: Container for multiple image ROIs
- `create_image_roi`: Factory function for creating image ROIs
- `create_image_roi_around_points`: Function for creating image ROIs around points
- Utility functions for coordinate handling
These classes handle ROI definitions, parameter conversion, and mask generation
for image processing operations.
"""
# pylint: disable=invalid-name # Allows short reference names like x, y, ...
# pylint: disable=duplicate-code
from __future__ import annotations
import abc
import re
from collections.abc import ByteString, Mapping, Sequence
from typing import TYPE_CHECKING, Literal, Type
import guidata.dataset as gds
import numpy as np
from skimage import draw
import sigima.enums
import sigima.tools.image
from sigima.config import _
from sigima.objects import base
if TYPE_CHECKING:
from sigima.objects.image.object import ImageObj
def to_builtin(obj) -> str | int | float | list | dict | np.ndarray | None:
"""Convert an object implementing a numeric value or collection
into the corresponding builtin/NumPy type.
Return None if conversion fails."""
try:
return int(obj) if int(obj) == float(obj) else float(obj)
except (TypeError, ValueError):
pass
if isinstance(obj, ByteString):
return str(obj)
if isinstance(obj, Sequence):
return str(obj) if len(obj) == len(str(obj)) else list(obj)
if isinstance(obj, Mapping):
return dict(obj)
if isinstance(obj, np.ndarray):
return obj
return None
def check_points(value: np.ndarray, raise_exception: bool = False) -> bool:
"""Check if value is a valid 1D array of coordinates (X, Y) pairs.
Args:
value: value to check
raise_exception: if True, raise an exception on invalid value
Returns:
True if value is valid, False otherwise
"""
if not np.issubdtype(value.dtype, np.floating):
if raise_exception:
raise TypeError("Coordinates must be floats")
return False
if value.ndim != 1:
if raise_exception:
raise ValueError("Coordinates must be a 1D array")
return False
if len(value) % 2 != 0:
if raise_exception:
raise ValueError("Coordinates must contain pairs (X, Y)")
return False
return True
[docs]
class ROI2DParam(base.BaseROIParam["ImageObj", "BaseSingleImageROI"]):
"""Image ROI parameters"""
def get_comment(self) -> str | None:
"""Get comment for ROI parameters"""
return _(
"This is a set of parameters defining a <b>Region of Interest</b> "
"(ROI) in an image. The parameters can be used to create a ROI object "
"or to extract data from an image using the ROI.<br><br>"
"All values are expressed in physical coordinates (floats). "
"The conversion to pixel coordinates is done by taking into account "
"the image pixel size and origin.<br>"
)
title = gds.StringItem(_("ROI title"), default="")
# Note: the ROI coordinates are expressed in pixel coordinates (integers)
# => That is the only way to handle ROI parametrization for image objects.
# Otherwise, we would have to ask the user to systematically provide the
# physical coordinates: that would be cumbersome and error-prone.
_geometry_prop = gds.GetAttrProp("geometry")
_rfp = gds.FuncProp(_geometry_prop, lambda x: x != "rectangle")
_cfp = gds.FuncProp(_geometry_prop, lambda x: x != "circle")
_pfp = gds.FuncProp(_geometry_prop, lambda x: x != "polygon")
# Do not declare it as a static method: not supported by Python 3.9
def _lbl(name: str, index: int): # pylint: disable=no-self-argument
"""Returns name<sub>index</sub>"""
return f"{name}<sub>{index}</sub>"
geometries = ("rectangle", "circle", "polygon")
geometry = gds.ChoiceItem(
_("Geometry"), list(zip(geometries, geometries)), default="rectangle"
).set_prop("display", store=_geometry_prop, hide=True)
# Parameters for rectangular ROI geometry:
_tlcorner = gds.BeginGroup(_("Top left corner")).set_prop("display", hide=_rfp)
x0 = gds.FloatItem(_lbl("X", 0), default=0).set_prop("display", hide=_rfp)
y0 = (
gds.FloatItem(_lbl("Y", 0), default=0).set_pos(1).set_prop("display", hide=_rfp)
)
_e_tlcorner = gds.EndGroup(_("Top left corner"))
dx = gds.FloatItem("ΔX", default=0).set_prop("display", hide=_rfp)
dy = gds.FloatItem("ΔY", default=0).set_pos(1).set_prop("display", hide=_rfp)
# Parameters for circular ROI geometry:
_cgroup = gds.BeginGroup(_("Center coordinates")).set_prop("display", hide=_cfp)
xc = gds.FloatItem(_lbl("X", "C"), default=0).set_prop("display", hide=_cfp)
yc = (
gds.FloatItem(_lbl("Y", "C"), default=0)
.set_pos(1)
.set_prop("display", hide=_cfp)
)
_e_cgroup = gds.EndGroup(_("Center coordinates"))
r = gds.FloatItem(_("Radius"), default=0).set_prop("display", hide=_cfp)
# Parameters for polygonal ROI geometry:
points = gds.FloatArrayItem(_("Coordinates"), check_callback=check_points).set_prop(
"display", hide=_pfp
)
# Parameter for ROI mask behavior:
inverse = gds.BoolItem(
_("Inverse ROI logic"),
default=False,
help=_(
"When disabled (default), the ROI defines an area inside the shape on "
"which to focus (masking data outside).\n"
"When enabled, the ROI logic is inverted to focus on data outside the "
"shape (masking data inside)."
),
)
def to_single_roi(
self, obj: ImageObj
) -> PolygonalROI | RectangularROI | CircularROI:
"""Convert parameters to single ROI
Args:
obj: image object (used for conversion of pixel to physical coordinates)
Returns:
Single ROI
"""
if self.geometry == "rectangle":
return RectangularROI.from_param(obj, self)
if self.geometry == "circle":
return CircularROI.from_param(obj, self)
if self.geometry == "polygon":
return PolygonalROI.from_param(obj, self)
raise ValueError(f"Unknown ROI geometry type: {self.geometry}")
def get_suffix(self) -> str:
"""Get suffix text representation for ROI extraction"""
if re.match(base.GENERIC_ROI_TITLE_REGEXP, self.title) or not self.title:
if self.geometry == "rectangle":
return f"x0={self.x0},y0={self.y0},dx={self.dx},dy={self.dy}"
if self.geometry == "circle":
return f"xc={self.xc},yc={self.yc},r={self.r}"
if self.geometry == "polygon":
return "polygon"
raise ValueError(f"Unknown ROI geometry type: {self.geometry}")
return self.title
def get_extracted_roi(self, obj: ImageObj) -> ImageROI | None:
"""Get extracted ROI, i.e. the remaining ROI after extracting ROI from image.
Args:
obj: image object (used for conversion of pixel to physical coordinates)
When extracting ROIs from an image to multiple images (i.e. one image per ROI),
this method returns the ROI that has to be kept in the destination image. This
is not necessary for a rectangular ROI: the destination image is simply a crop
of the source image according to the ROI coordinates. But for a circular ROI or
a polygonal ROI, the destination image is a crop of the source image according
to the bounding box of the ROI. Thus, to avoid any loss of information, a ROI
has to be defined for the destination image: this is the ROI returned by this
method. It's simply the same as the source ROI, but with coordinates adjusted
to the destination image. One may called this ROI the "extracted ROI".
"""
if self.geometry == "rectangle":
return None
single_roi = self.to_single_roi(obj)
roi = ImageROI()
roi.add_roi(single_roi)
return roi
def get_bounding_box_physical(self) -> tuple[int, int, int, int]:
"""Get bounding box (physical coordinates)"""
if self.geometry == "circle":
x0, y0 = self.xc - self.r, self.yc - self.r
x1, y1 = self.xc + self.r, self.yc + self.r
elif self.geometry == "rectangle":
x0, y0, x1, y1 = self.x0, self.y0, self.x0 + self.dx, self.y0 + self.dy
else:
self.points: np.ndarray
x0, y0 = self.points[::2].min(), self.points[1::2].min()
x1, y1 = self.points[::2].max(), self.points[1::2].max()
return x0, y0, x1, y1
def get_bounding_box_indices(self, obj: ImageObj) -> tuple[int, int, int, int]:
"""Get bounding box (pixel coordinates)"""
x0, y0, x1, y1 = self.get_bounding_box_physical()
ix0, iy0 = obj.physical_to_indices((x0, y0))
ix1, iy1 = obj.physical_to_indices((x1, y1))
return ix0, iy0, ix1, iy1
def get_data(self, obj: ImageObj) -> np.ndarray:
"""Get data in ROI
Args:
obj: image object
Returns:
Data in ROI
"""
ix0, iy0, ix1, iy1 = self.get_bounding_box_indices(obj)
ix0, iy0 = max(0, ix0), max(0, iy0)
ix1, iy1 = min(obj.data.shape[1], ix1), min(obj.data.shape[0], iy1)
return obj.data[iy0:iy1, ix0:ix1]
class BaseSingleImageROI(base.BaseSingleROI["ImageObj", ROI2DParam], abc.ABC):
"""Base class for single image ROI
Args:
coords: ROI edge coordinates (floats)
indices: if True, coordinates are indices, if False, they are physical values
title: ROI title
inverse: inverse ROI logic (default: False)
.. note::
The image ROI coords are expressed in physical coordinates (floats). The
conversion to pixel coordinates is done in :class:`sigima.objects.ImageObj`
(see :meth:`sigima.objects.ImageObj.physical_to_indices`). Most of the time,
the physical coordinates are the same as the pixel coordinates, but this
is not always the case (e.g. after image binning), so it's better to keep the
physical coordinates in the ROI object: this will help reusing the ROI with
different images (e.g. with different pixel sizes).
"""
def __init__(
self,
coords: np.ndarray | list[int] | list[float],
indices: bool,
title: str = "ROI",
inverse: bool = False,
) -> None:
super().__init__(coords, indices, title)
self.inverse = inverse
def to_dict(self) -> dict:
"""Convert ROI to dictionary
Returns:
Dictionary
"""
result = super().to_dict()
result["inverse"] = self.inverse
return result
@classmethod
def from_dict(cls, dictdata: dict):
"""Convert dictionary to ROI
Args:
dictdata: dictionary
Returns:
ROI
"""
# Get inverse parameter
inverse = dictdata.get("inverse", False) # Default: normal ROI behavior
return cls(dictdata["coords"], dictdata["indices"], dictdata["title"], inverse)
@abc.abstractmethod
def get_bounding_box(self, obj: ImageObj) -> tuple[float, float, float, float]:
"""Get bounding box (physical coordinates)
Args:
obj: image object
"""
class PolygonalROI(BaseSingleImageROI):
"""Polygonal ROI
Args:
coords: ROI edge coordinates
title: title
inverse: inverse ROI logic (default: False)
Raises:
ValueError: if number of coordinates is odd
.. note:: The image ROI coords are expressed in physical coordinates (floats)
"""
def check_coords(self) -> None:
"""Check if coords are valid
Raises:
ValueError: invalid coords
"""
if len(self.coords) % 2 != 0:
raise ValueError("Edge indices must be pairs of X, Y values")
def get_coords_html_rows(self) -> list[tuple[str, str]]:
"""Return HTML table rows describing the polygon coordinates."""
n_vertices = len(self.coords) // 2
coord_type = "indices" if self.indices else "physical"
# Show first few vertices if there are many
if n_vertices <= 4:
vertices_str = ", ".join(
f"({self.coords[i * 2]:.4g}, {self.coords[i * 2 + 1]:.4g})"
for i in range(n_vertices)
)
return [(f"Vertices ({coord_type})", vertices_str)]
return [(f"Vertices ({coord_type})", f"{n_vertices} points")]
def get_coords_summary(self) -> str:
"""Return a short summary of the polygon coordinates."""
n_vertices = len(self.coords) // 2
return f"{n_vertices} vertices"
# pylint: disable=unused-argument
@classmethod
def from_param(cls: PolygonalROI, obj: ImageObj, param: ROI2DParam) -> PolygonalROI:
"""Create ROI from parameters
Args:
obj: image object
param: parameters
"""
return cls(
param.points,
indices=False,
title=param.title,
inverse=param.inverse,
)
def get_bounding_box(self, obj: ImageObj) -> tuple[float, float, float, float]:
"""Get bounding box (physical coordinates)
Args:
obj: image object
"""
coords = self.get_physical_coords(obj)
x_edges, y_edges = coords[::2], coords[1::2]
return min(x_edges), min(y_edges), max(x_edges), max(y_edges)
def to_mask(self, obj: ImageObj) -> np.ndarray:
"""Create mask from ROI
Args:
obj: image object
Returns:
Mask (boolean array where True values are inside the ROI)
"""
roi_mask = np.ones_like(obj.data, dtype=bool)
indices = self.get_indices_coords(obj)
rows = np.array(indices[1::2], dtype=float) # y coordinates
cols = np.array(indices[::2], dtype=float) # x coordinates
rr, cc = draw.polygon(rows, cols, shape=obj.data.shape)
if self.inverse:
# Inverse ROI: mask inside the polygon (True inside, False outside)
roi_mask[:] = False
roi_mask[rr, cc] = True
else:
# Normal ROI: mask outside the polygon (False inside, True outside)
roi_mask[rr, cc] = False
return roi_mask
def to_param(self, obj: ImageObj, index: int) -> ROI2DParam:
"""Convert ROI to parameters
Args:
obj: object (image), for physical-indices coordinates conversion
index: ROI index
"""
gtitle = base.get_generic_roi_title(index)
param = ROI2DParam(gtitle)
param.title = self.title or gtitle
param.geometry = "polygon"
param.points = np.array(self.get_physical_coords(obj))
param.inverse = self.inverse
return param
class RectangularROI(BaseSingleImageROI):
"""Rectangular ROI
Args:
coords: ROI edge coordinates (x0, y0, dx, dy)
title: title
inverse: inverse ROI logic (default: False)
.. note:: The image ROI coords are expressed in physical coordinates (floats)
"""
def check_coords(self) -> None:
"""Check if coords are valid
Raises:
ValueError: invalid coords
"""
if len(self.coords) != 4:
raise ValueError("Rectangle ROI requires 4 coordinates")
def get_coords_html_rows(self) -> list[tuple[str, str]]:
"""Return HTML table rows describing the rectangle coordinates."""
x0, y0, dx, dy = self.coords
coord_type = "indices" if self.indices else "physical"
return [
(f"Origin ({coord_type})", f"({x0:.4g}, {y0:.4g})"),
(f"Size ({coord_type})", f"{dx:.4g} × {dy:.4g}"),
]
def get_coords_summary(self) -> str:
"""Return a short summary of the rectangle coordinates."""
x0, y0, dx, dy = self.coords
return f"Origin: ({x0:.4g}, {y0:.4g}), Size: {dx:.4g}×{dy:.4g}"
# pylint: disable=unused-argument
@classmethod
def from_param(
cls: RectangularROI, obj: ImageObj, param: ROI2DParam
) -> RectangularROI:
"""Create ROI from parameters
Args:
obj: image object
param: parameters
"""
x0, y0, x1, y1 = param.get_bounding_box_physical()
return cls(
[x0, y0, x1 - x0, y1 - y0],
indices=False,
title=param.title,
inverse=param.inverse,
)
def get_bounding_box(self, obj: ImageObj) -> tuple[float, float, float, float]:
"""Get bounding box (physical coordinates)
Args:
obj: image object
"""
x0, y0, dx, dy = self.get_physical_coords(obj)
return x0, y0, x0 + dx, y0 + dy
def get_physical_coords(self, obj: ImageObj) -> list[float]:
"""Return physical coords
Args:
obj: image object
Returns:
Physical coords
"""
if self.indices:
ix0, iy0, idx, idy = self.coords
x0, y0, x1, y1 = obj.indices_to_physical([ix0, iy0, ix0 + idx, iy0 + idy])
return [x0, y0, x1 - x0, y1 - y0]
return self.coords
def set_physical_coords(self, obj: ImageObj, coords: np.ndarray) -> None:
"""Set physical coords
Args:
obj: object (signal/image)
coords: physical coords
"""
if self.indices:
x0, y0, dx, dy = coords
ix0, iy0, ix1, iy1 = obj.physical_to_indices([x0, y0, x0 + dx, y0 + dy])
self.coords = np.array([ix0, iy0, ix1 - ix0, iy1 - iy0], dtype=int)
else:
self.coords = np.array(coords, dtype=float)
def get_indices_coords(self, obj: ImageObj) -> list[int]:
"""Return indices coords
Args:
obj: image object
Returns:
Indices coords
"""
if self.indices:
return self.coords.tolist()
ix0, iy0, ix1, iy1 = obj.physical_to_indices(self.get_bounding_box(obj))
return [ix0, iy0, ix1 - ix0, iy1 - iy0]
def set_indices_coords(self, obj: ImageObj, coords: np.ndarray) -> None:
"""Set indices coords
Args:
obj: object (signal/image)
coords: indices coords
"""
if self.indices:
self.coords = coords
else:
ix0, iy0, idx, idy = coords
x0, y0, x1, y1 = obj.indices_to_physical([ix0, iy0, ix0 + idx, iy0 + idy])
self.coords = np.array([x0, y0, x1 - x0, y1 - y0])
def to_mask(self, obj: ImageObj) -> np.ndarray:
"""Create mask from ROI
Args:
obj: image object
Returns:
Mask (boolean array where True values are inside the ROI)
"""
roi_mask = np.ones_like(obj.data, dtype=bool)
ix0, iy0, idx, idy = self.get_indices_coords(obj)
rr, cc = draw.rectangle((iy0, ix0), extent=(idy, idx), shape=obj.data.shape)
if self.inverse:
# Inverse ROI: mask inside the rectangle (True inside, False outside)
roi_mask[:] = False
roi_mask[rr, cc] = True
else:
# Normal ROI: mask outside the rectangle (False inside, True outside)
roi_mask[rr, cc] = False
return roi_mask
def to_param(self, obj: ImageObj, index: int) -> ROI2DParam:
"""Convert ROI to parameters
Args:
obj: object (image), for physical-indices coordinates conversion
index: ROI index
"""
gtitle = base.get_generic_roi_title(index)
param = ROI2DParam(gtitle)
param.title = self.title or gtitle
param.geometry = "rectangle"
param.x0, param.y0, param.dx, param.dy = self.get_physical_coords(obj)
param.inverse = self.inverse
return param
@staticmethod
def rect_to_coords(
x0: int | float, y0: int | float, x1: int | float, y1: int | float
) -> np.ndarray:
"""Convert rectangle to coordinates
Args:
x0: x0 (first corner)
y0: y0 (first corner)
x1: x1 (opposite corner)
y1: y1 (opposite corner)
Returns:
Rectangle coordinates (x0, y0, Δx, Δy) with positive Δx and Δy
Note:
Coordinates are normalized so that Δx and Δy are always positive.
This handles rectangles drawn "backwards" (from bottom-right to top-left).
"""
# Normalize coordinates to ensure Δx and Δy are positive
x_min, x_max = min(x0, x1), max(x0, x1)
y_min, y_max = min(y0, y1), max(y0, y1)
return np.array([x_min, y_min, x_max - x_min, y_max - y_min], dtype=type(x0))
class CircularROI(BaseSingleImageROI):
"""Circular ROI
Args:
coords: ROI edge coordinates (xc, yc, r)
title: title
inverse: inverse ROI logic (default: False)
.. note:: The image ROI coords are expressed in physical coordinates (floats)
"""
# pylint: disable=unused-argument
@classmethod
def from_param(cls: CircularROI, obj: ImageObj, param: ROI2DParam) -> CircularROI:
"""Create ROI from parameters
Args:
obj: image object
param: parameters
"""
x0, y0, x1, y1 = param.get_bounding_box_physical()
ixc, iyc = (x0 + x1) * 0.5, (y0 + y1) * 0.5
ir = (x1 - x0) * 0.5
return cls(
[ixc, iyc, ir],
indices=False,
title=param.title,
inverse=param.inverse,
)
def check_coords(self) -> None:
"""Check if coords are valid
Raises:
ValueError: invalid coords
"""
if len(self.coords) != 3:
raise ValueError("Circle ROI requires 3 coordinates")
def get_coords_html_rows(self) -> list[tuple[str, str]]:
"""Return HTML table rows describing the circle coordinates."""
xc, yc, r = self.coords
coord_type = "indices" if self.indices else "physical"
return [
(f"Center ({coord_type})", f"({xc:.4g}, {yc:.4g})"),
(f"Radius ({coord_type})", f"{r:.4g}"),
]
def get_coords_summary(self) -> str:
"""Return a short summary of the circle coordinates."""
xc, yc, r = self.coords
return f"Center: ({xc:.4g}, {yc:.4g}), R: {r:.4g}"
def get_bounding_box(self, obj: ImageObj) -> tuple[float, float, float, float]:
"""Get bounding box (physical coordinates)
Args:
obj: image object
"""
xc, yc, r = self.get_physical_coords(obj)
return xc - r, yc - r, xc + r, yc + r
def get_physical_coords(self, obj: ImageObj) -> np.ndarray:
"""Return physical coords
Args:
obj: image object
Returns:
Physical coords
"""
if self.indices:
ixc, iyc, ir = self.coords
x0, y0, x1, y1 = obj.indices_to_physical(
[ixc - ir, iyc - ir, ixc + ir, iyc + ir]
)
return [0.5 * (x0 + x1), 0.5 * (y0 + y1), 0.5 * (x1 - x0)]
return self.coords
def set_physical_coords(self, obj: ImageObj, coords: np.ndarray) -> None:
"""Set physical coords
Args:
obj: object (signal/image)
coords: physical coords
"""
if self.indices:
xc, yc, r = coords
ix0, iy0, ix1, iy1 = obj.physical_to_indices(
[xc - r, yc - r, xc + r, yc + r]
)
self.coords = np.array(
[0.5 * (ix0 + ix1), 0.5 * (iy0 + iy1), 0.5 * (ix1 - ix0)]
)
else:
self.coords = np.array(coords, dtype=float)
def get_indices_coords(self, obj: ImageObj) -> list[float]:
"""Return indices coords
Args:
obj: image object
Returns:
Indices coords
"""
if self.indices:
return self.coords
ix0, iy0, ix1, iy1 = obj.physical_to_indices(
self.get_bounding_box(obj), as_float=True
)
ixc, iyc = (ix0 + ix1) * 0.5, (iy0 + iy1) * 0.5
ir = (ix1 - ix0) * 0.5
return [ixc, iyc, ir]
def set_indices_coords(self, obj: ImageObj, coords: np.ndarray) -> None:
"""Set indices coords
Args:
obj: object (signal/image)
coords: indices coords
"""
if self.indices:
self.coords = coords
else:
ixc, iyc, ir = coords
x0, y0, x1, y1 = obj.indices_to_physical(
[ixc - ir, iyc - ir, ixc + ir, iyc + ir]
)
self.coords = np.array([0.5 * (x0 + x1), 0.5 * (y0 + y1), 0.5 * (x1 - x0)])
def to_mask(self, obj: ImageObj) -> np.ndarray:
"""Create mask from ROI
Args:
obj: image object
Returns:
Mask (boolean array where True values are inside the ROI)
"""
roi_mask = np.ones_like(obj.data, dtype=bool)
ixc, iyc, ir = self.get_indices_coords(obj)
yxratio = obj.dy / obj.dx
rr, cc = draw.ellipse(iyc, ixc, ir / yxratio, ir, shape=obj.data.shape)
if self.inverse:
# Inverse ROI: mask inside the circle (True inside, False outside)
roi_mask[:] = False
roi_mask[rr, cc] = True
else:
# Normal ROI: mask outside the circle (False inside, True outside)
roi_mask[rr, cc] = False
return roi_mask
def to_param(self, obj: ImageObj, index: int) -> ROI2DParam:
"""Convert ROI to parameters
Args:
obj: object (image), for physical-indices coordinates conversion
index: ROI index
"""
gtitle = base.get_generic_roi_title(index)
param = ROI2DParam(gtitle)
param.title = self.title or gtitle
param.geometry = "circle"
param.xc, param.yc, param.r = self.get_physical_coords(obj)
param.inverse = self.inverse
return param
@staticmethod
def rect_to_coords(
x0: int | float, y0: int | float, x1: int | float, y1: int | float
) -> np.ndarray:
"""Convert rectangle to circle coordinates
Args:
x0: x0 (top-left corner)
y0: y0 (top-left corner)
x1: x1 (bottom-right corner)
y1: y1 (bottom-right corner)
Returns:
Circle coordinates (xc, yc, r)
"""
xc, yc, r = 0.5 * (x0 + x1), 0.5 * (y0 + y1), 0.5 * (x1 - x0)
return np.array([xc, yc, r], dtype=type(x0))
[docs]
class ImageROI(base.BaseROI["ImageObj", BaseSingleImageROI, ROI2DParam]):
"""Image Regions of Interest
Args:
inverse: if True, ROI is outside the region
"""
PREFIX = "i"
[docs]
@staticmethod
def get_compatible_single_roi_classes() -> list[Type[BaseSingleImageROI]]:
"""Return compatible single ROI classes"""
return [RectangularROI, CircularROI, PolygonalROI]
[docs]
def to_mask(self, obj: ImageObj) -> np.ndarray:
"""Create mask from ROI
Args:
obj: image object
Returns:
Mask (boolean array where True values are inside the ROI)
"""
if not self.single_rois:
# If no single ROIs, the mask is empty (no ROI defined)
mask = np.ones_like(obj.data, dtype=bool)
mask.fill(False)
return mask
# Check inverse values to determine combination strategy
inverse_values = [roi.inverse for roi in self.single_rois]
all_normal = not any(inverse_values) # All inverse=False (normal ROI)
all_inverse = all(inverse_values) # All inverse=True (inverse ROI)
if all_normal:
# All ROIs have inverse=False: AND them together (intersection)
mask = np.ones_like(obj.data, dtype=bool)
for roi in self.single_rois:
mask &= roi.to_mask(obj)
elif all_inverse:
# All ROIs have inverse=True: OR them together (union)
mask = np.zeros_like(obj.data, dtype=bool)
for roi in self.single_rois:
mask |= roi.to_mask(obj)
else:
# Mixed inverse values: complex combination
# Start with all True (full mask)
mask = np.ones_like(obj.data, dtype=bool)
# First apply all inverse=False ROIs (intersections)
for roi in self.single_rois:
if not roi.inverse:
mask &= roi.to_mask(obj)
# Then apply inverse=True ROIs (add their areas)
inside_mask = np.zeros_like(obj.data, dtype=bool)
for roi in self.single_rois:
if roi.inverse:
inside_mask |= roi.to_mask(obj)
# Combine: mask outside regions AND include inside regions
mask = mask | inside_mask
return mask
[docs]
def create_image_roi(
geometry: Literal["rectangle", "circle", "polygon"],
coords: np.ndarray | list[float] | list[list[float]],
indices: bool = False,
title: str = "",
inverse: bool | list[bool] = False,
) -> ImageROI:
"""Create Image Regions of Interest (ROI) object.
More ROIs can be added to the object after creation, using the `add_roi` method.
Args:
geometry: ROI type ('rectangle', 'circle', 'polygon')
coords: ROI coords (physical coordinates), `[x0, y0, dx, dy]` for a rectangle,
`[xc, yc, r]` for a circle, or `[x0, y0, x1, y1, ...]` for a polygon (lists or
NumPy arrays are accepted). For multiple ROIs, nested lists or NumPy arrays are
accepted but with a common geometry type (e.g.
`[[xc1, yc1, r1], [xc2, yc2, r2], ...]` for circles).
indices: if True, coordinates are indices, if False, they are physical values
(default to False)
title: title
inverse: ROI logic behavior. Controls whether the ROI logic is inversed
(default: False, meaning normal ROI that focuses on data inside the shape).
When True, the ROI logic is inversed to focus on data outside the shape.
Can be a single boolean (applied to all ROIs) or a list of booleans
(one per ROI for individual control).
Returns:
Regions of Interest (ROI) object
Raises:
ValueError: if ROI type is unknown, if the number of coordinates is invalid,
or if the number of inverse values doesn't match the number of ROIs
Examples:
Create a single rectangle ROI (defaults to normal behavior):
>>> roi = create_image_roi("rectangle", [10, 20, 30, 40])
Create a single rectangle ROI with inverse logic explicitly:
>>> roi = create_image_roi("rectangle", [10, 20, 30, 40], inverse=True)
Create multiple rectangles with global inverse parameter:
>>> coords = [[10, 20, 30, 40], [50, 60, 70, 80]]
>>> roi = create_image_roi("rectangle", coords, inverse=False)
Create multiple rectangles with individual inverse parameters:
>>> coords = [[10, 20, 30, 40], [50, 60, 70, 80]]
>>> inverse_values = [True, False] # First inside, second outside
>>> roi = create_image_roi(
... "rectangle", coords, inverse=inverse_values
... )
Create polygons with varying vertex counts:
>>> polygon_coords = [[0, 0, 10, 0, 5, 8], [20, 20, 30, 20, 30, 30, 20, 30]]
>>> inverse_values = [False, True] # First outside, second inside
>>> roi = create_image_roi(
... "polygon", polygon_coords, inverse=inverse_values
... )
"""
# Handle coordinates - try to create numpy array, fall back to list for irregular
try:
coords = np.array(coords, float)
if coords.ndim == 1:
coords = coords.reshape(1, -1)
coord_list = coords
coord_count = len(coords)
except ValueError:
# Handle irregular case: polygons with varying vertex counts
coord_list = [np.array(coord, float) for coord in coords]
coord_count = len(coord_list)
# Handle inverse parameter - can be single value or list
if isinstance(inverse, bool):
inverse_values = [inverse] * coord_count
else:
inverse_values = list(inverse)
if len(inverse_values) != coord_count:
raise ValueError(
f"Number of inverse values ({len(inverse_values)}) must "
f"match number of ROIs ({coord_count})"
)
roi = ImageROI()
if geometry == "rectangle":
if isinstance(coord_list, np.ndarray) and coord_list.shape[1] != 4:
raise ValueError("Rectangle ROI requires 4 coordinates")
for coord_row, inverse_val in zip(coord_list, inverse_values):
roi.add_roi(RectangularROI(coord_row, indices, title, inverse_val))
elif geometry == "circle":
if isinstance(coord_list, np.ndarray) and coord_list.shape[1] != 3:
raise ValueError("Circle ROI requires 3 coordinates")
for coord_row, inverse_val in zip(coord_list, inverse_values):
roi.add_roi(CircularROI(coord_row, indices, title, inverse_val))
elif geometry == "polygon":
if isinstance(coord_list, np.ndarray) and coord_list.shape[1] % 2 != 0:
raise ValueError("Polygon ROI requires pairs of X, Y coordinates")
for coord_row, inverse_val in zip(coord_list, inverse_values):
roi.add_roi(PolygonalROI(coord_row, indices, title, inverse_val))
else:
raise ValueError(f"Unknown ROI type: {geometry}")
return roi
def create_image_roi_around_points(
coords: np.ndarray, roi_geometry: sigima.enums.DetectionROIGeometry
) -> ImageROI:
"""Create ROIs around given point coordinates.
Args:
coords: Coordinates of points (shape: (n, 2))
roi_geometry: ROI geometry type (rectangle or circle)
Returns:
ImageROI object containing rectangles or circles around each point
Raises:
ValueError: If less than 2 points are provided (cannot determine ROI size),
or if points are too close together resulting in too small ROI size,
or if an invalid ROI geometry is specified.
"""
assert roi_geometry in ("rectangle", "circle")
if coords.size == 0:
raise ValueError("No coordinates provided to create ROIs")
if coords.ndim != 2 or coords.shape[1] != 2:
raise ValueError(
f"Coordinates array must have shape (n, 2), got {coords.shape}"
)
if coords.shape[0] < 2:
raise ValueError(
"At least two points are required to automatically determine ROI size"
)
# Calculate ROI size based on minimum distance between points
dist = sigima.tools.image.distance_matrix(coords)
dist_min = dist[dist != 0].min()
assert dist_min > 0
if roi_geometry == "rectangle":
# For rectangles, account for diagonal to avoid overlap
radius = int(0.5 * dist_min / np.sqrt(2) - 1)
else: # circle
# For circles, use half the minimum distance directly
radius = int(0.5 * dist_min - 1)
if radius < 1:
raise ValueError(
"Calculated ROI size is too small. Points may be too close together."
)
roi_coords = []
for x, y in coords:
if roi_geometry == "rectangle":
x0, y0 = x - radius, y - radius
dx, dy = 2 * radius, 2 * radius
roi_coords.append([x0, y0, dx, dy])
else: # circle
roi_coords.append([x, y, radius])
return create_image_roi(roi_geometry, roi_coords, indices=True)
