ngio 0.1.6__py3-none-any.whl → 0.2.0a1__py3-none-any.whl

ngio/images/label.py

@@ -0,0 +1,96 @@
+"""A module for handling label images in OME-NGFF files."""
+
+from typing import Literal
+
+from ngio.images.abstract_image import AbstractImage, consolidate_image
+from ngio.ome_zarr_meta import (
+    ImplementedLabelMetaHandlers,
+    LabelMetaHandler,
+    NgioLabelMeta,
+)
+from ngio.utils import (
+    NgioValidationError,
+    ZarrGroupHandler,
+)
+
+
+class Label(AbstractImage[LabelMetaHandler]):
+    """Placeholder class for a label."""
+
+    def __init__(
+        self,
+        group_handler: ZarrGroupHandler,
+        path: str,
+        meta_handler: LabelMetaHandler | None,
+    ) -> None:
+        """Initialize the Image at a single level.
+
+        Args:
+            group_handler: The Zarr group handler.
+            path: The path to the image in the omezarr file.
+            meta_handler: The image metadata handler.
+
+        """
+        if meta_handler is None:
+            meta_handler = ImplementedLabelMetaHandlers().find_meta_handler(
+                group_handler
+            )
+        super().__init__(
+            group_handler=group_handler, path=path, meta_handler=meta_handler
+        )
+
+    @property
+    def meta(self) -> NgioLabelMeta:
+        """Return the metadata."""
+        return self._meta_handler.meta
+
+    def consolidate(
+        self,
+        mode: Literal["dask", "numpy", "coarsen"] = "dask",
+    ) -> None:
+        """Consolidate the label on disk."""
+        consolidate_image(self, mode=mode, order=0)
+
+
+class LabelsContainer:
+    """A class to handle the /labels group in an OME-NGFF file."""
+
+    def __init__(self, group_handler: ZarrGroupHandler) -> None:
+        """Initialize the LabelGroupHandler."""
+        self._group_handler = group_handler
+
+        # Validate the group
+        # Either contains a labels attribute or is empty
+        attrs = self._group_handler.load_attrs()
+        if len(attrs) == 0:
+            # It's an empty group
+            pass
+        elif "labels" in attrs and isinstance(attrs["labels"], list):
+            # It's a valid group
+            pass
+        else:
+            raise NgioValidationError(
+                f"Invalid /labels group. "
+                f"Expected a single labels attribute with a list of label names. "
+                f"Found: {attrs}"
+            )
+
+    def list(self) -> list[str]:
+        """Create the /labels group if it doesn't exist."""
+        attrs = self._group_handler.load_attrs()
+        return attrs.get("labels", [])
+
+    def get(self, name: str, path: str) -> Label:
+        """Get a label from the group."""
+        group_handler = self._group_handler.derive_handler(name)
+        return Label(group_handler, path, None)
+
+    def derive(
+        self,
+        name: str,
+        reference_image: AbstractImage,
+        overwrite: bool = False,
+        **kwargs,
+    ) -> Label:
+        """Derive a label from an image."""
+        raise NotImplementedError

ngio/images/omezarr_container.py

@@ -0,0 +1,512 @@
+"""Abstract class for handling OME-NGFF images."""
+
+# %%
+from collections.abc import Collection
+from typing import Literal, overload
+
+import numpy as np
+
+from ngio.images.create import _create_empty_image
+from ngio.images.image import Image, ImagesContainer
+from ngio.images.label import Label, LabelsContainer
+from ngio.ome_zarr_meta import (
+    NgioImageMeta,
+    PixelSize,
+)
+from ngio.ome_zarr_meta.ngio_specs import (
+    SpaceUnits,
+    TimeUnits,
+)
+from ngio.tables import (
+    FeatureTable,
+    MaskingROITable,
+    RoiTable,
+    Table,
+    TablesContainer,
+    TypedTable,
+)
+from ngio.utils import (
+    AccessModeLiteral,
+    NgioValidationError,
+    NgioValueError,
+    StoreOrGroup,
+    ZarrGroupHandler,
+)
+
+
+def _default_table_container(handler: ZarrGroupHandler) -> TablesContainer | None:
+    """Return a default table container."""
+    success, table_handler = handler.safe_derive_handler("tables")
+    if success and isinstance(table_handler, ZarrGroupHandler):
+        return TablesContainer(table_handler)
+
+
+def _default_label_container(handler: ZarrGroupHandler) -> LabelsContainer | None:
+    """Return a default label container."""
+    success, label_handler = handler.safe_derive_handler("labels")
+    if success and isinstance(label_handler, ZarrGroupHandler):
+        return LabelsContainer(label_handler)
+
+
+class OmeZarrContainer:
+    """This class contains an OME-Zarr image and its associated tables and labels."""
+
+    _images_container: ImagesContainer
+    _labels_container: LabelsContainer | None
+    _tables_container: TablesContainer | None
+
+    def __init__(
+        self,
+        store: StoreOrGroup,
+        cache: bool = False,
+        mode: AccessModeLiteral = "r+",
+        table_container: TablesContainer | None = None,
+        label_container: LabelsContainer | None = None,
+        validate_arrays: bool = True,
+    ) -> None:
+        """Initialize the OmeZarrContainer."""
+        self._group_handler = ZarrGroupHandler(store, cache, mode)
+        self._images_container = ImagesContainer(self._group_handler)
+
+        if label_container is None:
+            label_container = _default_label_container(self._group_handler)
+        self._labels_container = label_container
+
+        if table_container is None:
+            table_container = _default_table_container(self._group_handler)
+        self._tables_container = table_container
+
+    def __repr__(self) -> str:
+        """Return a string representation of the image."""
+        num_labels = len(self.list_labels())
+        num_tables = len(self.list_tables())
+
+        base_str = f"OmeZarrContainer(levels={self.levels}"
+        if num_labels > 0 and num_labels < 3:
+            base_str += f", labels={self.list_labels()}"
+        elif num_labels >= 3:
+            base_str += f", #labels={num_labels}"
+        if num_tables > 0 and num_tables < 3:
+            base_str += f", tables={self.list_tables()}"
+        elif num_tables >= 3:
+            base_str += f", #tables={num_tables}"
+        base_str += ")"
+        return base_str
+
+    @property
+    def images_container(self) -> ImagesContainer:
+        """Return the image container."""
+        return self._images_container
+
+    @property
+    def labels_container(self) -> LabelsContainer:
+        """Return the labels container."""
+        if self._labels_container is None:
+            raise NgioValidationError("No labels found in the image.")
+        return self._labels_container
+
+    @property
+    def tables_container(self) -> TablesContainer:
+        """Return the tables container."""
+        if self._tables_container is None:
+            raise NgioValidationError("No tables found in the image.")
+        return self._tables_container
+
+    @property
+    def image_meta(self) -> NgioImageMeta:
+        """Return the image metadata."""
+        return self._images_container.meta
+
+    @property
+    def levels(self) -> int:
+        """Return the number of levels in the image."""
+        return self._images_container.levels
+
+    @property
+    def levels_paths(self) -> list[str]:
+        """Return the paths of the levels in the image."""
+        return self._images_container.levels_paths
+
+    def initialize_channel_meta(
+        self,
+        labels: Collection[str] | int | None = None,
+        wavelength_id: Collection[str] | None = None,
+        percentiles: tuple[float, float] | None = None,
+        colors: Collection[str] | None = None,
+        active: Collection[bool] | None = None,
+        **omero_kwargs: dict,
+    ) -> None:
+        """Create a ChannelsMeta object with the default unit."""
+        self._images_container.initialize_channel_meta(
+            labels=labels,
+            wavelength_id=wavelength_id,
+            percentiles=percentiles,
+            colors=colors,
+            active=active,
+            **omero_kwargs,
+        )
+
+    def update_percentiles(
+        self,
+        start_percentile: float = 0.1,
+        end_percentile: float = 99.9,
+    ) -> None:
+        """Update the percentiles of the image."""
+        self._images_container.update_percentiles(
+            start_percentile=start_percentile, end_percentile=end_percentile
+        )
+
+    def get_image(
+        self,
+        path: str | None = None,
+        pixel_size: PixelSize | None = None,
+        highest_resolution: bool = True,
+    ) -> Image:
+        """Get an image at a specific level."""
+        return self._images_container.get(
+            path=path,
+            pixel_size=pixel_size,
+            highest_resolution=highest_resolution,
+        )
+
+    def derive_image(
+        self,
+        store: StoreOrGroup,
+        ref_path: str | None = None,
+        shape: Collection[int] | None = None,
+        chunks: Collection[int] | None = None,
+        copy_tables: bool = False,
+        copy_labels: bool = False,
+        overwrite: bool = False,
+    ) -> "OmeZarrContainer":
+        """Derive a new image from the current image."""
+        if copy_labels:
+            raise NotImplementedError("Copying labels is not yet implemented.")
+
+        if copy_tables:
+            raise NotImplementedError("Copying tables is not yet implemented.")
+
+        _ = self._images_container.derive(
+            store=store,
+            ref_path=ref_path,
+            shape=shape,
+            chunks=chunks,
+            overwrite=overwrite,
+        )
+        return OmeZarrContainer(
+            store=store,
+            cache=False,
+            mode="r+",
+            table_container=None,
+            label_container=None,
+        )
+
+    def list_tables(self) -> list[str]:
+        """List all tables in the image."""
+        if self._tables_container is None:
+            return []
+        return self._tables_container.list()
+
+    @overload
+    def get_table(self, name: str, check_type: None) -> Table: ...
+
+    @overload
+    def get_table(self, name: str, check_type: Literal["roi_table"]) -> RoiTable: ...
+
+    @overload
+    def get_table(
+        self, name: str, check_type: Literal["masking_roi_table"]
+    ) -> MaskingROITable: ...
+
+    @overload
+    def get_table(
+        self, name: str, check_type: Literal["feature_table"]
+    ) -> FeatureTable: ...
+
+    def get_table(self, name: str, check_type: TypedTable | None = None) -> Table:
+        """Get a table from the image."""
+        if self._tables_container is None:
+            raise NgioValidationError("No tables found in the image.")
+
+        table = self._tables_container.get(name)
+        match check_type:
+            case "roi_table":
+                if not isinstance(table, RoiTable):
+                    raise NgioValueError(
+                        f"Table '{name}' is not a ROI table. Found type: {table.type()}"
+                    )
+                return table
+            case "masking_roi_table":
+                if not isinstance(table, MaskingROITable):
+                    raise NgioValueError(
+                        f"Table '{name}' is not a masking ROI table. "
+                        f"Found type: {table.type()}"
+                    )
+                return table
+            case "feature_table":
+                if not isinstance(table, FeatureTable):
+                    raise NgioValueError(
+                        f"Table '{name}' is not a feature table. "
+                        f"Found type: {table.type()}"
+                    )
+                return table
+            case None:
+                return table
+            case _:
+                raise NgioValueError(f"Unknown check_type: {check_type}")
+
+    def add_table(
+        self,
+        name: str,
+        table: Table,
+        backend: str | None = None,
+        overwrite: bool = False,
+    ) -> None:
+        """Add a table to the image."""
+        if self._tables_container is None:
+            raise NgioValidationError("No tables found in the image.")
+        self._tables_container.add(
+            name=name, table=table, backend=backend, overwrite=overwrite
+        )
+
+    def list_labels(self) -> list[str]:
+        """List all labels in the image."""
+        if self._labels_container is None:
+            return []
+        return self._labels_container.list()
+
+    def get_label(self, name: str, path: str) -> Label:
+        """Get a label from the image."""
+        if self._labels_container is None:
+            raise NgioValidationError("No labels found in the image.")
+        return self._labels_container.get(name=name, path=path)
+
+    def derive_label(self, name: str, **kwargs) -> Label:
+        """Derive a label from an image."""
+        if self._labels_container is None:
+            raise NgioValidationError("No labels found in the image.")
+
+        ref_image = self.get_image()
+        return self._labels_container.derive(
+            name=name, reference_image=ref_image, **kwargs
+        )
+
+
+def open_omezarr_container(
+    store: StoreOrGroup,
+    cache: bool = False,
+    mode: AccessModeLiteral = "r+",
+    validate_arrays: bool = True,
+) -> OmeZarrContainer:
+    """Open an OME-Zarr image."""
+    return OmeZarrContainer(
+        store=store,
+        cache=cache,
+        mode=mode,
+        validate_arrays=validate_arrays,
+    )
+
+
+def open_image(
+    store: StoreOrGroup,
+    path: str | None = None,
+    pixel_size: PixelSize | None = None,
+    highest_resolution: bool = False,
+    cache: bool = False,
+    mode: AccessModeLiteral = "r+",
+) -> Image:
+    """Open a single level image from an OME-Zarr image."""
+    group_handler = ZarrGroupHandler(store, cache, mode)
+    images_container = ImagesContainer(group_handler)
+    return images_container.get(
+        path=path,
+        pixel_size=pixel_size,
+        highest_resolution=highest_resolution,
+    )
+
+
+def create_empty_omezarr(
+    store: StoreOrGroup,
+    shape: Collection[int],
+    xy_pixelsize: float,
+    z_spacing: float = 1.0,
+    time_spacing: float = 1.0,
+    levels: int | list[str] = 5,
+    xy_scaling_factor: float = 2,
+    z_scaling_factor: float = 1.0,
+    space_unit: SpaceUnits | str | None = None,
+    time_unit: TimeUnits | str | None = None,
+    axes_names: Collection[str] | None = None,
+    name: str | None = None,
+    chunks: Collection[int] | None = None,
+    dtype: str = "uint16",
+    channel_labels: list[str] | None = None,
+    channel_wavelengths: list[str] | None = None,
+    percentiles: tuple[float, float] | None = None,
+    channel_colors: Collection[str] | None = None,
+    channel_active: Collection[bool] | None = None,
+    overwrite: bool = False,
+    version: str = "0.4",
+) -> OmeZarrContainer:
+    """Create an empty OME-Zarr image with the given shape and metadata.
+
+    Args:
+        store (StoreOrGroup): The Zarr store or group to create the image in.
+        shape (Collection[int]): The shape of the image.
+        xy_pixelsize (float): The pixel size in x and y dimensions.
+        z_spacing (float, optional): The spacing between z slices. Defaults to 1.0.
+        time_spacing (float, optional): The spacing between time points.
+            Defaults to 1.0.
+        levels (int | list[str], optional): The number of levels in the pyramid or a
+            list of level names. Defaults to 5.
+        xy_scaling_factor (float, optional): The down-scaling factor in x and y
+            dimensions. Defaults to 2.0.
+        z_scaling_factor (float, optional): The down-scaling factor in z dimension.
+            Defaults to 1.0.
+        space_unit (SpaceUnits | str | None, optional): The unit of space. Defaults to
+            None.
+        time_unit (TimeUnits | str | None, optional): The unit of time. Defaults to
+            None.
+        axes_names (Collection[str] | None, optional): The names of the axes.
+            If None the canonical names are used. Defaults to None.
+        name (str | None, optional): The name of the image. Defaults to None.
+        chunks (Collection[int] | None, optional): The chunk shape. If None the shape
+            is used. Defaults to None.
+        dtype (str, optional): The data type of the image. Defaults to "uint16".
+        channel_labels (list[str] | None, optional): The labels of the channels.
+            Defaults to None.
+        channel_wavelengths (list[str] | None, optional): The wavelengths of the
+            channels. Defaults to None.
+        percentiles (tuple[float, float] | None, optional): The percentiles of the
+            channels. Defaults to None.
+        channel_colors (Collection[str] | None, optional): The colors of the channels.
+            Defaults to None.
+        channel_active (Collection[bool] | None, optional): Whether the channels are
+            active. Defaults to None.
+        overwrite (bool, optional): Whether to overwrite an existing image.
+            Defaults to True.
+        version (str, optional): The version of the OME-Zarr specification.
+            Defaults to "0.4".
+    """
+    handler = _create_empty_image(
+        store=store,
+        shape=shape,
+        xy_pixelsize=xy_pixelsize,
+        z_spacing=z_spacing,
+        time_spacing=time_spacing,
+        levels=levels,
+        xy_scaling_factor=xy_scaling_factor,
+        z_scaling_factor=z_scaling_factor,
+        space_unit=space_unit,
+        time_unit=time_unit,
+        axes_names=axes_names,
+        name=name,
+        chunks=chunks,
+        dtype=dtype,
+        overwrite=overwrite,
+        version=version,
+    )
+
+    omezarr = OmeZarrContainer(store=handler.store, mode="r+")
+    omezarr.initialize_channel_meta(
+        labels=channel_labels,
+        wavelength_id=channel_wavelengths,
+        percentiles=percentiles,
+        colors=channel_colors,
+        active=channel_active,
+    )
+    return omezarr
+
+
+def create_omezarr_from_array(
+    store: StoreOrGroup,
+    array: np.ndarray,
+    xy_pixelsize: float,
+    z_spacing: float = 1.0,
+    time_spacing: float = 1.0,
+    levels: int | list[str] = 5,
+    xy_scaling_factor: float = 2.0,
+    z_scaling_factor: float = 1.0,
+    space_unit: SpaceUnits | str | None = None,
+    time_unit: TimeUnits | str | None = None,
+    axes_names: Collection[str] | None = None,
+    channel_labels: list[str] | None = None,
+    channel_wavelengths: list[str] | None = None,
+    percentiles: tuple[float, float] | None = (0.1, 99.9),
+    channel_colors: Collection[str] | None = None,
+    channel_active: Collection[bool] | None = None,
+    name: str | None = None,
+    chunks: Collection[int] | None = None,
+    overwrite: bool = False,
+    version: str = "0.4",
+) -> OmeZarrContainer:
+    """Create an OME-Zarr image from a numpy array.
+
+    Args:
+        store (StoreOrGroup): The Zarr store or group to create the image in.
+        array (np.ndarray): The image data.
+        xy_pixelsize (float): The pixel size in x and y dimensions.
+        z_spacing (float, optional): The spacing between z slices. Defaults to 1.0.
+        time_spacing (float, optional): The spacing between time points.
+            Defaults to 1.0.
+        levels (int | list[str], optional): The number of levels in the pyramid or a
+            list of level names. Defaults to 5.
+        xy_scaling_factor (float, optional): The down-scaling factor in x and y
+            dimensions. Defaults to 2.0.
+        z_scaling_factor (float, optional): The down-scaling factor in z dimension.
+            Defaults to 1.0.
+        space_unit (SpaceUnits | str | None, optional): The unit of space. Defaults to
+            None.
+        time_unit (TimeUnits | str | None, optional): The unit of time. Defaults to
+            None.
+        axes_names (Collection[str] | None, optional): The names of the axes.
+            If None the canonical names are used. Defaults to None.
+        name (str | None, optional): The name of the image. Defaults to None.
+        chunks (Collection[int] | None, optional): The chunk shape. If None the shape
+            is used. Defaults to None.
+        channel_labels (list[str] | None, optional): The labels of the channels.
+            Defaults to None.
+        channel_wavelengths (list[str] | None, optional): The wavelengths of the
+            channels. Defaults to None.
+        percentiles (tuple[float, float] | None, optional): The percentiles of the
+            channels. Defaults to None.
+        channel_colors (Collection[str] | None, optional): The colors of the channels.
+            Defaults to None.
+        channel_active (Collection[bool] | None, optional): Whether the channels are
+            active. Defaults to None.
+        overwrite (bool, optional): Whether to overwrite an existing image.
+            Defaults to True.
+        version (str, optional): The version of the OME-Zarr specification.
+            Defaults to "0.4".
+    """
+    handler = _create_empty_image(
+        store=store,
+        shape=array.shape,
+        xy_pixelsize=xy_pixelsize,
+        z_spacing=z_spacing,
+        time_spacing=time_spacing,
+        levels=levels,
+        xy_scaling_factor=xy_scaling_factor,
+        z_scaling_factor=z_scaling_factor,
+        space_unit=space_unit,
+        time_unit=time_unit,
+        axes_names=axes_names,
+        name=name,
+        chunks=chunks,
+        dtype=array.dtype,
+        overwrite=overwrite,
+        version=version,
+    )
+
+    omezarr = OmeZarrContainer(store=handler.store, mode="r+")
+    image = omezarr.get_image()
+    image.set_array(array)
+    image.consolidate()
+    omezarr.initialize_channel_meta(
+        labels=channel_labels,
+        wavelength_id=channel_wavelengths,
+        percentiles=percentiles,
+        colors=channel_colors,
+        active=channel_active,
+    )
+    return omezarr

ngio/ome_zarr_meta/__init__.py

@@ -0,0 +1,35 @@
+"""Utilities for reading and writing OME-Zarr metadata."""
+
+from ngio.ome_zarr_meta._generic_handlers import (
+    BaseImageMetaHandler,
+    BaseLabelMetaHandler,
+    ImageMetaHandler,
+    LabelMetaHandler,
+)
+from ngio.ome_zarr_meta._meta_handlers import (
+    ImplementedImageMetaHandlers,
+    ImplementedLabelMetaHandlers,
+    open_image_meta_handler,
+)
+from ngio.ome_zarr_meta.ngio_specs import (
+    AxesMapper,
+    Dataset,
+    NgioImageMeta,
+    NgioLabelMeta,
+    PixelSize,
+)
+
+__all__ = [
+    "AxesMapper",
+    "BaseImageMetaHandler",
+    "BaseLabelMetaHandler",
+    "Dataset",
+    "ImageMetaHandler",
+    "ImplementedImageMetaHandlers",
+    "ImplementedLabelMetaHandlers",
+    "LabelMetaHandler",
+    "NgioImageMeta",
+    "NgioLabelMeta",
+    "PixelSize",
+    "open_image_meta_handler",
+]