OmeZarrContainer: API Documentation

Open an OME-Zarr Container

ngio.open_ome_zarr_container

open_ome_zarr_container(
    store: StoreOrGroup,
    cache: bool = False,
    mode: AccessModeLiteral = "r+",
    validate_arrays: bool = True,
) -> OmeZarrContainer

Open an OME-Zarr image.

Source code in ngio/images/_ome_zarr_container.py

def open_ome_zarr_container(
    store: StoreOrGroup,
    cache: bool = False,
    mode: AccessModeLiteral = "r+",
    validate_arrays: bool = True,
) -> OmeZarrContainer:
    """Open an OME-Zarr image."""
    handler = ZarrGroupHandler(store=store, cache=cache, mode=mode)
    return OmeZarrContainer(
        group_handler=handler,
        validate_paths=validate_arrays,
    )

Create an OME-Zarr Container

ngio.create_empty_ome_zarr

create_empty_ome_zarr(
    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 = DefaultSpaceUnit,
    time_unit: TimeUnits = DefaultTimeUnit,
    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,
    channel_colors: Collection[str] | None = None,
    channel_active: Collection[bool] | None = None,
    overwrite: bool = False,
    version: NgffVersions = DefaultNgffVersion,
) -> OmeZarrContainer

Create an empty OME-Zarr image with the given shape and metadata.

Parameters:

• 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, default: 1.0 ) –

  The spacing between z slices. Defaults to 1.0.

• time_spacing (float, default: 1.0 ) –

  The spacing between time points. Defaults to 1.0.

• levels (int | list[str], default: 5 ) –

  The number of levels in the pyramid or a list of level names. Defaults to 5.

• xy_scaling_factor (float, default: 2 ) –

  The down-scaling factor in x and y dimensions. Defaults to 2.0.

• z_scaling_factor (float, default: 1.0 ) –

  The down-scaling factor in z dimension. Defaults to 1.0.

• space_unit (SpaceUnits, default: DefaultSpaceUnit ) –

  The unit of space. Defaults to DefaultSpaceUnit.

• time_unit (TimeUnits, default: DefaultTimeUnit ) –

  The unit of time. Defaults to DefaultTimeUnit.

• axes_names (Collection[str] | None, default: None ) –

  The names of the axes. If None the canonical names are used. Defaults to None.

• name (str | None, default: None ) –

  The name of the image. Defaults to None.

• chunks (Collection[int] | None, default: None ) –

  The chunk shape. If None the shape is used. Defaults to None.

• dtype (str, default: 'uint16' ) –

  The data type of the image. Defaults to "uint16".

• channel_labels (list[str] | None, default: None ) –

  The labels of the channels. Defaults to None.

• channel_wavelengths (list[str] | None, default: None ) –

  The wavelengths of the channels. Defaults to None.

• channel_colors (Collection[str] | None, default: None ) –

  The colors of the channels. Defaults to None.

• channel_active (Collection[bool] | None, default: None ) –

  Whether the channels are active. Defaults to None.

• overwrite (bool, default: False ) –

  Whether to overwrite an existing image. Defaults to True.

• version (NgffVersion, default: DefaultNgffVersion ) –

  The version of the OME-Zarr specification. Defaults to DefaultNgffVersion.

Source code in ngio/images/_ome_zarr_container.py

def create_empty_ome_zarr(
    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 = DefaultSpaceUnit,
    time_unit: TimeUnits = DefaultTimeUnit,
    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,
    channel_colors: Collection[str] | None = None,
    channel_active: Collection[bool] | None = None,
    overwrite: bool = False,
    version: NgffVersions = DefaultNgffVersion,
) -> 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, optional): The unit of space. Defaults to
            DefaultSpaceUnit.
        time_unit (TimeUnits, optional): The unit of time. Defaults to
            DefaultTimeUnit.
        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.
        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 (NgffVersion, optional): The version of the OME-Zarr specification.
            Defaults to DefaultNgffVersion.
    """
    handler = create_empty_image_container(
        store=store,
        shape=shape,
        pixelsize=xy_pixelsize,
        z_spacing=z_spacing,
        time_spacing=time_spacing,
        levels=levels,
        yx_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,
    )

    ome_zarr = OmeZarrContainer(group_handler=handler)
    ome_zarr.set_channel_meta(
        labels=channel_labels,
        wavelength_id=channel_wavelengths,
        percentiles=None,
        colors=channel_colors,
        active=channel_active,
    )
    return ome_zarr

ngio.create_ome_zarr_from_array

create_ome_zarr_from_array(
    store: StoreOrGroup,
    array: 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 = DefaultSpaceUnit,
    time_unit: TimeUnits = DefaultTimeUnit,
    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: NgffVersions = DefaultNgffVersion,
) -> OmeZarrContainer

Create an OME-Zarr image from a numpy array.

Parameters:

• store (StoreOrGroup) –

  The Zarr store or group to create the image in.

• array (ndarray) –

  The image data.

• xy_pixelsize (float) –

  The pixel size in x and y dimensions.

• z_spacing (float, default: 1.0 ) –

  The spacing between z slices. Defaults to 1.0.

• time_spacing (float, default: 1.0 ) –

  The spacing between time points. Defaults to 1.0.

• levels (int | list[str], default: 5 ) –

  The number of levels in the pyramid or a list of level names. Defaults to 5.

• xy_scaling_factor (float, default: 2.0 ) –

  The down-scaling factor in x and y dimensions. Defaults to 2.0.

• z_scaling_factor (float, default: 1.0 ) –

  The down-scaling factor in z dimension. Defaults to 1.0.

• space_unit (SpaceUnits, default: DefaultSpaceUnit ) –

  The unit of space. Defaults to DefaultSpaceUnit.

• time_unit (TimeUnits, default: DefaultTimeUnit ) –

  The unit of time. Defaults to DefaultTimeUnit.

• axes_names (Collection[str] | None, default: None ) –

  The names of the axes. If None the canonical names are used. Defaults to None.

• name (str | None, default: None ) –

  The name of the image. Defaults to None.

• chunks (Collection[int] | None, default: None ) –

  The chunk shape. If None the shape is used. Defaults to None.

• channel_labels (list[str] | None, default: None ) –

  The labels of the channels. Defaults to None.

• channel_wavelengths (list[str] | None, default: None ) –

  The wavelengths of the channels. Defaults to None.

• percentiles (tuple[float, float] | None, default: (0.1, 99.9) ) –

  The percentiles of the channels. Defaults to None.

• channel_colors (Collection[str] | None, default: None ) –

  The colors of the channels. Defaults to None.

• channel_active (Collection[bool] | None, default: None ) –

  Whether the channels are active. Defaults to None.

• overwrite (bool, default: False ) –

  Whether to overwrite an existing image. Defaults to True.

• version (str, default: DefaultNgffVersion ) –

  The version of the OME-Zarr specification. Defaults to DefaultNgffVersion.

Source code in ngio/images/_ome_zarr_container.py

def create_ome_zarr_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 = DefaultSpaceUnit,
    time_unit: TimeUnits = DefaultTimeUnit,
    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: NgffVersions = DefaultNgffVersion,
) -> 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, optional): The unit of space. Defaults to
            DefaultSpaceUnit.
        time_unit (TimeUnits, optional): The unit of time. Defaults to
            DefaultTimeUnit.
        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 DefaultNgffVersion.
    """
    handler = create_empty_image_container(
        store=store,
        shape=array.shape,
        pixelsize=xy_pixelsize,
        z_spacing=z_spacing,
        time_spacing=time_spacing,
        levels=levels,
        yx_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=str(array.dtype),
        overwrite=overwrite,
        version=version,
    )

    ome_zarr = OmeZarrContainer(group_handler=handler)
    image = ome_zarr.get_image()
    image.set_array(array)
    image.consolidate()
    ome_zarr.set_channel_meta(
        labels=channel_labels,
        wavelength_id=channel_wavelengths,
        percentiles=percentiles,
        colors=channel_colors,
        active=channel_active,
    )
    return ome_zarr

OmeZarrContainer Class

ngio.OmeZarrContainer

OmeZarrContainer(
    group_handler: ZarrGroupHandler,
    table_container: TablesContainer | None = None,
    label_container: LabelsContainer | None = None,
    validate_paths: bool = False,
)

This class is an object representation of an OME-Zarr image.

It provides methods to access

• The multiscale image metadata
• To open images at different levels of resolution
• To access labels and tables associated with the image.
• To derive new images, labels, and add tables to the image.
• To modify the image metadata, such as axes units and channel metadata.

Attributes:

• images_container (ImagesContainer) –

  The container for the images.

• labels_container (LabelsContainer) –

  The container for the labels.

• tables_container (TablesContainer) –

  The container for the tables.

Initialize the OmeZarrContainer.

Parameters:

• group_handler (ZarrGroupHandler) –

  The Zarr group handler.

• table_container (TablesContainer | None, default: None ) –

  The tables container.

• label_container (LabelsContainer | None, default: None ) –

  The labels container.

• validate_paths (bool, default: False ) –

  Whether to validate the paths of the image multiscale

Source code in ngio/images/_ome_zarr_container.py

def __init__(
    self,
    group_handler: ZarrGroupHandler,
    table_container: TablesContainer | None = None,
    label_container: LabelsContainer | None = None,
    validate_paths: bool = False,
) -> None:
    """Initialize the OmeZarrContainer.

    Args:
        group_handler (ZarrGroupHandler): The Zarr group handler.
        table_container (TablesContainer | None): The tables container.
        label_container (LabelsContainer | None): The labels container.
        validate_paths (bool): Whether to validate the paths of the image multiscale
    """
    self._group_handler = group_handler
    self._images_container = ImagesContainer(self._group_handler)

    self._labels_container = label_container
    self._tables_container = table_container

    if validate_paths:
        for level_path in self._images_container.levels_paths:
            self.get_image(path=level_path)

images_container property

images_container: ImagesContainer

Return the images container.

Returns:

• ImagesContainer ( ImagesContainer ) –

  The images container.

labels_container property

labels_container: LabelsContainer

Return the labels container.

tables_container property

tables_container: TablesContainer

Return the tables container.

image_meta property

image_meta: NgioImageMeta

Return the image metadata.

levels property

levels: int

Return the number of levels in the image.

levels_paths property

levels_paths: list[str]

Return the paths of the levels in the image.

is_3d property

is_3d: bool

Return True if the image is 3D.

is_2d property

is_2d: bool

Return True if the image is 2D.

is_time_series property

is_time_series: bool

Return True if the image is a time series.

is_2d_time_series property

is_2d_time_series: bool

Return True if the image is a 2D time series.

is_3d_time_series property

is_3d_time_series: bool

Return True if the image is a 3D time series.

is_multi_channels property

is_multi_channels: bool

Return True if the image is multichannel.

space_unit property

space_unit: str | None

Return the space unit of the image.

time_unit property

time_unit: str | None

Return the time unit of the image.

channel_labels property

channel_labels: list[str]

Return the channels of the image.

wavelength_ids property

wavelength_ids: list[str | None]

Return the list of wavelength of the image.

num_channels property

num_channels: int

Return the number of channels.

get_channel_idx

get_channel_idx(
    channel_label: str | None = None,
    wavelength_id: str | None = None,
) -> int

Get the index of a channel by its label or wavelength ID.

Source code in ngio/images/_ome_zarr_container.py

def get_channel_idx(
    self, channel_label: str | None = None, wavelength_id: str | None = None
) -> int:
    """Get the index of a channel by its label or wavelength ID."""
    image = self.get_image()
    return image.channels_meta.get_channel_idx(
        channel_label=channel_label, wavelength_id=wavelength_id
    )

set_channel_meta

set_channel_meta(
    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.

Source code in ngio/images/_ome_zarr_container.py

def set_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.set_channel_meta(
        labels=labels,
        wavelength_id=wavelength_id,
        percentiles=percentiles,
        colors=colors,
        active=active,
        **omero_kwargs,
    )

set_channel_percentiles

set_channel_percentiles(
    start_percentile: float = 0.1,
    end_percentile: float = 99.9,
) -> None

Update the percentiles of the image.

Source code in ngio/images/_ome_zarr_container.py

def set_channel_percentiles(
    self,
    start_percentile: float = 0.1,
    end_percentile: float = 99.9,
) -> None:
    """Update the percentiles of the image."""
    self._images_container.set_channel_percentiles(
        start_percentile=start_percentile, end_percentile=end_percentile
    )

set_axes_units

set_axes_units(
    space_unit: SpaceUnits = DefaultSpaceUnit,
    time_unit: TimeUnits = DefaultTimeUnit,
    set_labels: bool = True,
) -> None

Set the units of the image.

Parameters:

• space_unit (SpaceUnits, default: DefaultSpaceUnit ) –

  The unit of space.

• time_unit (TimeUnits, default: DefaultTimeUnit ) –

  The unit of time.

• set_labels (bool, default: True ) –

  Whether to set the units for the labels as well.

Source code in ngio/images/_ome_zarr_container.py

def set_axes_units(
    self,
    space_unit: SpaceUnits = DefaultSpaceUnit,
    time_unit: TimeUnits = DefaultTimeUnit,
    set_labels: bool = True,
) -> None:
    """Set the units of the image.

    Args:
        space_unit (SpaceUnits): The unit of space.
        time_unit (TimeUnits): The unit of time.
        set_labels (bool): Whether to set the units for the labels as well.
    """
    self._images_container.set_axes_unit(space_unit=space_unit, time_unit=time_unit)
    if not set_labels:
        return
    for label_name in self.list_labels():
        label = self.get_label(label_name)
        label.set_axes_unit(space_unit=space_unit, time_unit=time_unit)

get_image

get_image(
    path: str | None = None,
    pixel_size: PixelSize | None = None,
    strict: bool = False,
) -> Image

Get an image at a specific level.

Parameters:

• path (str | None, default: None ) –

  The path to the image in the ome_zarr file.

• pixel_size (PixelSize | None, default: None ) –

  The pixel size of the image.

• strict (bool, default: False ) –

  Only used if the pixel size is provided. If True, the pixel size must match the image pixel size exactly. If False, the closest pixel size level will be returned.

Source code in ngio/images/_ome_zarr_container.py

def get_image(
    self,
    path: str | None = None,
    pixel_size: PixelSize | None = None,
    strict: bool = False,
) -> Image:
    """Get an image at a specific level.

    Args:
        path (str | None): The path to the image in the ome_zarr file.
        pixel_size (PixelSize | None): The pixel size of the image.
        strict (bool): Only used if the pixel size is provided. If True, the
            pixel size must match the image pixel size exactly. If False, the
            closest pixel size level will be returned.

    """
    return self._images_container.get(
        path=path, pixel_size=pixel_size, strict=strict
    )

get_masked_image

get_masked_image(
    masking_label_name: str,
    masking_table_name: str | None = None,
    path: str | None = None,
    pixel_size: PixelSize | None = None,
    strict: bool = False,
) -> MaskedImage

Get a masked image at a specific level.

Parameters:

• masking_label_name (str) –

  The name of the label.

• masking_table_name (str | None, default: None ) –

  The name of the masking table.

• path (str | None, default: None ) –

  The path to the image in the ome_zarr file.

• pixel_size (PixelSize | None, default: None ) –

  The pixel size of the image.

• strict (bool, default: False ) –

  Only used if the pixel size is provided. If True, the pixel size must match the image pixel size exactly. If False, the closest pixel size level will be returned.

Source code in ngio/images/_ome_zarr_container.py

def get_masked_image(
    self,
    masking_label_name: str,
    masking_table_name: str | None = None,
    path: str | None = None,
    pixel_size: PixelSize | None = None,
    strict: bool = False,
) -> MaskedImage:
    """Get a masked image at a specific level.

    Args:
        masking_label_name (str): The name of the label.
        masking_table_name (str | None): The name of the masking table.
        path (str | None): The path to the image in the ome_zarr file.
        pixel_size (PixelSize | None): The pixel size of the image.
        strict (bool): Only used if the pixel size is provided. If True, the
            pixel size must match the image pixel size exactly. If False, the
            closest pixel size level will be returned.
    """
    image = self.get_image(path=path, pixel_size=pixel_size, strict=strict)
    masking_label = self.get_label(
        name=masking_label_name, path=path, pixel_size=pixel_size, strict=strict
    )
    if masking_table_name is None:
        masking_table = masking_label.build_masking_roi_table()
    else:
        masking_table = self.get_masking_roi_table(name=masking_table_name)

    return MaskedImage(
        group_handler=image._group_handler,
        path=masking_label.path,
        meta_handler=image.meta_handler,
        label=masking_label,
        masking_roi_table=masking_table,
    )

derive_image

derive_image(
    store: StoreOrGroup,
    ref_path: str | None = None,
    shape: Collection[int] | None = None,
    labels: Collection[str] | None = None,
    pixel_size: PixelSize | None = None,
    axes_names: Collection[str] | None = None,
    name: str | None = None,
    chunks: Collection[int] | None = None,
    dtype: str | None = None,
    copy_labels: bool = False,
    copy_tables: bool = False,
    overwrite: bool = False,
) -> OmeZarrContainer

Create an empty OME-Zarr container from an existing image.

Parameters:

• store (StoreOrGroup) –

  The Zarr store or group to create the image in.

• ref_path (str | None, default: None ) –

  The path to the reference image in the image container.

• shape (Collection[int] | None, default: None ) –

  The shape of the new image.

• labels (Collection[str] | None, default: None ) –

  The labels of the new image.

• pixel_size (PixelSize | None, default: None ) –

  The pixel size of the new image.

• axes_names (Collection[str] | None, default: None ) –

  The axes names of the new image.

• chunks (Collection[int] | None, default: None ) –

  The chunk shape of the new image.

• dtype (str | None, default: None ) –

  The data type of the new image.

• name (str | None, default: None ) –

  The name of the new image.

• copy_labels (bool, default: False ) –

  Whether to copy the labels from the reference image.

• copy_tables (bool, default: False ) –

  Whether to copy the tables from the reference image.

• overwrite (bool, default: False ) –

  Whether to overwrite an existing image.

Returns:

• OmeZarrContainer ( OmeZarrContainer ) –

  The new image container.

Source code in ngio/images/_ome_zarr_container.py

def derive_image(
    self,
    store: StoreOrGroup,
    ref_path: str | None = None,
    shape: Collection[int] | None = None,
    labels: Collection[str] | None = None,
    pixel_size: PixelSize | None = None,
    axes_names: Collection[str] | None = None,
    name: str | None = None,
    chunks: Collection[int] | None = None,
    dtype: str | None = None,
    copy_labels: bool = False,
    copy_tables: bool = False,
    overwrite: bool = False,
) -> "OmeZarrContainer":
    """Create an empty OME-Zarr container from an existing image.

    Args:
        store (StoreOrGroup): The Zarr store or group to create the image in.
        ref_path (str | None): The path to the reference image in
            the image container.
        shape (Collection[int] | None): The shape of the new image.
        labels (Collection[str] | None): The labels of the new image.
        pixel_size (PixelSize | None): The pixel size of the new image.
        axes_names (Collection[str] | None): The axes names of the new image.
        chunks (Collection[int] | None): The chunk shape of the new image.
        dtype (str | None): The data type of the new image.
        name (str | None): The name of the new image.
        copy_labels (bool): Whether to copy the labels from the reference image.
        copy_tables (bool): Whether to copy the tables from the reference image.
        overwrite (bool): Whether to overwrite an existing image.

    Returns:
        OmeZarrContainer: The new image container.

    """
    _ = self._images_container.derive(
        store=store,
        ref_path=ref_path,
        shape=shape,
        labels=labels,
        pixel_size=pixel_size,
        axes_names=axes_names,
        name=name,
        chunks=chunks,
        dtype=dtype,
        overwrite=overwrite,
    )

    handler = ZarrGroupHandler(
        store, cache=self._group_handler.use_cache, mode=self._group_handler.mode
    )

    new_ome_zarr = OmeZarrContainer(
        group_handler=handler,
        validate_paths=False,
    )

    if copy_labels:
        self.labels_container._group_handler.copy_handler(
            new_ome_zarr.labels_container._group_handler
        )

    if copy_tables:
        self.tables_container._group_handler.copy_handler(
            new_ome_zarr.tables_container._group_handler
        )
    return new_ome_zarr

list_tables

list_tables(
    filter_types: TypedTable | str | None = None,
) -> list[str]

List all tables in the image.

Source code in ngio/images/_ome_zarr_container.py

def list_tables(self, filter_types: TypedTable | str | None = None) -> list[str]:
    """List all tables in the image."""
    table_container = self._get_tables_container()
    if table_container is None:
        return []

    return table_container.list(
        filter_types=filter_types,
    )

list_roi_tables

list_roi_tables() -> list[str]

List all ROI tables in the image.

Source code in ngio/images/_ome_zarr_container.py

def list_roi_tables(self) -> list[str]:
    """List all ROI tables in the image."""
    masking_roi = self.tables_container.list(
        filter_types="masking_roi_table",
    )
    roi = self.tables_container.list(
        filter_types="roi_table",
    )
    return masking_roi + roi

get_roi_table

get_roi_table(name: str) -> RoiTable

Get a ROI table from the image.

Parameters:

• name (str) –

  The name of the table.

Source code in ngio/images/_ome_zarr_container.py

def get_roi_table(self, name: str) -> RoiTable:
    """Get a ROI table from the image.

    Args:
        name (str): The name of the table.
    """
    table = self.tables_container.get(name=name, strict=True)
    if not isinstance(table, RoiTable):
        raise NgioValueError(f"Table {name} is not a ROI table. Got {type(table)}")
    return table

get_masking_roi_table

get_masking_roi_table(name: str) -> MaskingRoiTable

Get a masking ROI table from the image.

Parameters:

• name (str) –

  The name of the table.

Source code in ngio/images/_ome_zarr_container.py

def get_masking_roi_table(self, name: str) -> MaskingRoiTable:
    """Get a masking ROI table from the image.

    Args:
        name (str): The name of the table.
    """
    table = self.tables_container.get(name=name, strict=True)
    if not isinstance(table, MaskingRoiTable):
        raise NgioValueError(
            f"Table {name} is not a masking ROI table. Got {type(table)}"
        )
    return table

get_feature_table

get_feature_table(name: str) -> FeatureTable

Get a feature table from the image.

Parameters:

• name (str) –

  The name of the table.

Source code in ngio/images/_ome_zarr_container.py

def get_feature_table(self, name: str) -> FeatureTable:
    """Get a feature table from the image.

    Args:
        name (str): The name of the table.
    """
    table = self.tables_container.get(name=name, strict=True)
    if not isinstance(table, FeatureTable):
        raise NgioValueError(
            f"Table {name} is not a feature table. Got {type(table)}"
        )
    return table

get_generic_roi_table

get_generic_roi_table(name: str) -> GenericRoiTable

Get a generic ROI table from the image.

Parameters:

• name (str) –

  The name of the table.

Source code in ngio/images/_ome_zarr_container.py

def get_generic_roi_table(self, name: str) -> GenericRoiTable:
    """Get a generic ROI table from the image.

    Args:
        name (str): The name of the table.
    """
    table = self.tables_container.get(name=name, strict=True)
    if not isinstance(table, GenericRoiTable):
        raise NgioValueError(
            f"Table {name} is not a generic ROI table. Got {type(table)}"
        )
    return table

get_condition_table

get_condition_table(name: str) -> ConditionTable

Get a condition table from the image.

Parameters:

• name (str) –

  The name of the table.

Source code in ngio/images/_ome_zarr_container.py

def get_condition_table(self, name: str) -> ConditionTable:
    """Get a condition table from the image.

    Args:
        name (str): The name of the table.
    """
    table = self.tables_container.get(name=name, strict=True)
    if not isinstance(table, ConditionTable):
        raise NgioValueError(
            f"Table {name} is not a condition table. Got {type(table)}"
        )
    return table

get_table

get_table(
    name: str, check_type: TypedTable | None = None
) -> Table

Get a table from the image.

Parameters:

• name (str) –

  The name of the table.

• check_type (TypedTable | None, default: None ) –

  Deprecated. Please use 'get_table_as' instead, or one of the type specific get_*table() methods.

Source code in ngio/images/_ome_zarr_container.py

def get_table(self, name: str, check_type: TypedTable | None = None) -> Table:
    """Get a table from the image.

    Args:
        name (str): The name of the table.
        check_type (TypedTable | None): Deprecated. Please use
            'get_table_as' instead, or one of the type specific
            get_*table() methods.

    """
    if check_type is not None:
        warnings.warn(
            "The 'check_type' argument is deprecated, and will be removed in "
            "ngio=0.3. Use 'get_table_as' instead or one of the "
            "type specific get_*table() methods.",
            DeprecationWarning,
            stacklevel=2,
        )
    return self.tables_container.get(name=name, strict=False)

get_table_as

get_table_as(
    name: str,
    table_cls: type[TableType],
    backend: TableBackend | None = None,
) -> TableType

Get a table from the image as a specific type.

Parameters:

• name (str) –

  The name of the table.

• table_cls (type[TableType]) –

  The type of the table.

• backend (TableBackend | None, default: None ) –

  The backend to use. If None, the default backend is used.

Source code in ngio/images/_ome_zarr_container.py

def get_table_as(
    self,
    name: str,
    table_cls: type[TableType],
    backend: TableBackend | None = None,
) -> TableType:
    """Get a table from the image as a specific type.

    Args:
        name (str): The name of the table.
        table_cls (type[TableType]): The type of the table.
        backend (TableBackend | None): The backend to use. If None,
            the default backend is used.
    """
    return self.tables_container.get_as(
        name=name,
        table_cls=table_cls,
        backend=backend,
    )

build_image_roi_table

build_image_roi_table(name: str = 'image') -> RoiTable

Compute the ROI table for an image.

Source code in ngio/images/_ome_zarr_container.py

def build_image_roi_table(self, name: str = "image") -> RoiTable:
    """Compute the ROI table for an image."""
    return self.get_image().build_image_roi_table(name=name)

build_masking_roi_table

build_masking_roi_table(label: str) -> MaskingRoiTable

Compute the masking ROI table for a label.

Source code in ngio/images/_ome_zarr_container.py

def build_masking_roi_table(self, label: str) -> MaskingRoiTable:
    """Compute the masking ROI table for a label."""
    return self.get_label(label).build_masking_roi_table()

add_table

add_table(
    name: str,
    table: Table,
    backend: TableBackend = DefaultTableBackend,
    overwrite: bool = False,
) -> None

Add a table to the image.

Source code in ngio/images/_ome_zarr_container.py

def add_table(
    self,
    name: str,
    table: Table,
    backend: TableBackend = DefaultTableBackend,
    overwrite: bool = False,
) -> None:
    """Add a table to the image."""
    self.tables_container.add(
        name=name, table=table, backend=backend, overwrite=overwrite
    )

list_labels

list_labels() -> list[str]

List all labels in the image.

Source code in ngio/images/_ome_zarr_container.py

def list_labels(self) -> list[str]:
    """List all labels in the image."""
    label_container = self._get_labels_container()
    if label_container is None:
        return []
    return label_container.list()

get_label

get_label(
    name: str,
    path: str | None = None,
    pixel_size: PixelSize | None = None,
    strict: bool = False,
) -> Label

Get a label from the group.

Parameters:

• name (str) –

  The name of the label.

• path (str | None, default: None ) –

  The path to the image in the ome_zarr file.

• pixel_size (PixelSize | None, default: None ) –

  The pixel size of the image.

• strict (bool, default: False ) –

  Only used if the pixel size is provided. If True, the pixel size must match the image pixel size exactly. If False, the closest pixel size level will be returned.

Source code in ngio/images/_ome_zarr_container.py

def get_label(
    self,
    name: str,
    path: str | None = None,
    pixel_size: PixelSize | None = None,
    strict: bool = False,
) -> Label:
    """Get a label from the group.

    Args:
        name (str): The name of the label.
        path (str | None): The path to the image in the ome_zarr file.
        pixel_size (PixelSize | None): The pixel size of the image.
        strict (bool): Only used if the pixel size is provided. If True, the
            pixel size must match the image pixel size exactly. If False, the
            closest pixel size level will be returned.
    """
    return self.labels_container.get(
        name=name, path=path, pixel_size=pixel_size, strict=strict
    )

get_masked_label

get_masked_label(
    label_name: str,
    masking_label_name: str,
    masking_table_name: str | None = None,
    path: str | None = None,
    pixel_size: PixelSize | None = None,
    strict: bool = False,
) -> MaskedLabel

Get a masked image at a specific level.

Parameters:

• label_name (str) –

  The name of the label.

• masking_label_name (str) –

  The name of the masking label.

• masking_table_name (str | None, default: None ) –

  The name of the masking table.

• path (str | None, default: None ) –

  The path to the image in the ome_zarr file.

• pixel_size (PixelSize | None, default: None ) –

  The pixel size of the image.

• strict (bool, default: False ) –

  Only used if the pixel size is provided. If True, the pixel size must match the image pixel size exactly. If False, the closest pixel size level will be returned.

Source code in ngio/images/_ome_zarr_container.py

def get_masked_label(
    self,
    label_name: str,
    masking_label_name: str,
    masking_table_name: str | None = None,
    path: str | None = None,
    pixel_size: PixelSize | None = None,
    strict: bool = False,
) -> MaskedLabel:
    """Get a masked image at a specific level.

    Args:
        label_name (str): The name of the label.
        masking_label_name (str): The name of the masking label.
        masking_table_name (str | None): The name of the masking table.
        path (str | None): The path to the image in the ome_zarr file.
        pixel_size (PixelSize | None): The pixel size of the image.
        strict (bool): Only used if the pixel size is provided. If True, the
            pixel size must match the image pixel size exactly. If False, the
            closest pixel size level will be returned.
    """
    label = self.get_label(
        name=label_name, path=path, pixel_size=pixel_size, strict=strict
    )
    masking_label = self.get_label(
        name=masking_label_name, path=path, pixel_size=pixel_size, strict=strict
    )
    if masking_table_name is None:
        masking_table = masking_label.build_masking_roi_table()
    else:
        masking_table = self.get_masking_roi_table(name=masking_table_name)

    return MaskedLabel(
        group_handler=label._group_handler,
        path=label.path,
        meta_handler=label.meta_handler,
        label=masking_label,
        masking_roi_table=masking_table,
    )

derive_label

derive_label(
    name: str,
    ref_image: Image | Label | None = None,
    shape: Collection[int] | None = None,
    pixel_size: PixelSize | None = None,
    axes_names: Collection[str] | None = None,
    chunks: Collection[int] | None = None,
    dtype: str | None = None,
    overwrite: bool = False,
) -> Label

Create an empty OME-Zarr label from a reference image.

And add the label to the /labels group.

Parameters:

• name (str) –

  The name of the new image.

• ref_image (Image | Label | None, default: None ) –

  A reference image that will be used to create the new image.

• shape (Collection[int] | None, default: None ) –

  The shape of the new image.

• pixel_size (PixelSize | None, default: None ) –

  The pixel size of the new image.

• axes_names (Collection[str] | None, default: None ) –

  The axes names of the new image. For labels, the channel axis is not allowed.

• chunks (Collection[int] | None, default: None ) –

  The chunk shape of the new image.

• dtype (str | None, default: None ) –

  The data type of the new image.

• overwrite (bool, default: False ) –

  Whether to overwrite an existing image.

Returns:

• Label ( Label ) –

  The new label.

Source code in ngio/images/_ome_zarr_container.py

def derive_label(
    self,
    name: str,
    ref_image: Image | Label | None = None,
    shape: Collection[int] | None = None,
    pixel_size: PixelSize | None = None,
    axes_names: Collection[str] | None = None,
    chunks: Collection[int] | None = None,
    dtype: str | None = None,
    overwrite: bool = False,
) -> "Label":
    """Create an empty OME-Zarr label from a reference image.

    And add the label to the /labels group.

    Args:
        name (str): The name of the new image.
        ref_image (Image | Label | None): A reference image that will be used
            to create the new image.
        shape (Collection[int] | None): The shape of the new image.
        pixel_size (PixelSize | None): The pixel size of the new image.
        axes_names (Collection[str] | None): The axes names of the new image.
            For labels, the channel axis is not allowed.
        chunks (Collection[int] | None): The chunk shape of the new image.
        dtype (str | None): The data type of the new image.
        overwrite (bool): Whether to overwrite an existing image.

    Returns:
        Label: The new label.

    """
    if ref_image is None:
        ref_image = self.get_image()
    return self.labels_container.derive(
        name=name,
        ref_image=ref_image,
        shape=shape,
        pixel_size=pixel_size,
        axes_names=axes_names,
        chunks=chunks,
        dtype=dtype,
        overwrite=overwrite,
    )