OME-Zarr container API reference¶

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."""
    return self.images_container.get_channel_idx(
        channel_label=channel_label, wavelength_id=wavelength_id
    )

def set_channel_meta(
    self,
    channel_meta: ChannelsMeta | None = None,
) -> None:
    """Set the channels metadata.

    Args:
        channel_meta: The channels metadata to set. If `None`, a default
            metadata is created from the number of channels in the image.
    """
    self._images_container.set_channel_meta(channel_meta=channel_meta)

def set_channel_labels(
    self,
    labels: Sequence[str],
) -> None:
    """Update the labels of the channels.

    Args:
        labels (Sequence[str]): The new labels for the channels.
    """
    self._images_container.set_channel_labels(labels=labels)

def set_channel_colors(
    self,
    colors: Sequence[str],
) -> None:
    """Update the colors of the channels.

    Args:
        colors (Sequence[str]): The new colors for the channels.
    """
    self._images_container.set_channel_colors(colors=colors)

def set_channel_windows(
    self,
    starts_ends: Sequence[tuple[float, float]],
    min_max: Sequence[tuple[float, float]] | None = None,
) -> None:
    """Update the channel windows.

    These values are used by viewers to set the display
    range of each channel.

    Args:
        starts_ends (Sequence[tuple[float, float]]): The start and end values
            for each channel.
        min_max (Sequence[tuple[float, float]] | None): The min and max values
            for each channel. If None, the min and max values will not be updated.
    """
    self._images_container.set_channel_windows(
        starts_ends=starts_ends,
        min_max=min_max,
    )

def set_channel_windows_with_percentiles(
    self,
    percentiles: tuple[float, float] | list[tuple[float, float]] = (0.1, 99.9),
) -> None:
    """Update the channel windows using percentiles.

    Args:
        percentiles (tuple[float, float] | list[tuple[float, float]]):
            The start and end percentiles for each channel.
            If a single tuple is provided,
            the same percentiles will be used for all channels.
    """
    self._images_container.set_channel_windows_with_percentiles(
        percentiles=percentiles
    )

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

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

def set_axes_names(
    self,
    axes_names: Sequence[str],
) -> None:
    """Set the axes names of the image.

    Args:
        axes_names (Sequence[str]): The axes names of the image.
    """
    self._images_container.set_axes_names(axes_names=axes_names)

def set_name(
    self,
    name: str,
) -> None:
    """Set the name of the image in the metadata.

    This does not change the group name or any paths.

    Args:
        name (str): The name of the image.
    """
    self._images_container.set_name(name=name)

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: Select the pyramid level whose pixel size matches this one.
            A lookup key, not a value to write; to set a pixel size see
            `pixelsize` on the create/derive entry points.
        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
    )

def get_masked_image(
    self,
    masking_label_name: str | None = None,
    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 | None): The name of the masking label to use.
            If None, the masking table must be provided.
        masking_table_name (str | None): The name of the masking table to use.
            If None, the masking label must be provided.
        path (str | None): The path to the image in the ome_zarr file.
            If None, the first level will be used.
        pixel_size: Select the pyramid level whose pixel size matches this one.
            A lookup key, not a value to write; to set a pixel size see
            `pixelsize` on the create/derive entry points.
            This is only used if path is None.
        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, masking_table = self._find_matching_masking_label(
        masking_label_name=masking_label_name,
        masking_table_name=masking_table_name,
        pixel_size=image.pixel_size,
    )
    return MaskedImage(
        group_handler=image._group_handler,
        path=image.path,
        meta_handler=image.meta_handler,
        label=masking_label,
        masking_roi_table=masking_table,
    )

def derive_image(
    self,
    store: StoreOrGroup,
    ref_path: str | None = None,
    # Metadata parameters
    shape: Sequence[int] | None = None,
    pixelsize: float | tuple[float, float] | None = None,
    z_spacing: float | None = None,
    time_spacing: float | None = None,
    name: str | None = None,
    translation: Sequence[float] | None = None,
    channels_policy: Literal["squeeze", "same", "singleton"] | int = "same",
    channels_meta: Sequence[str | Channel] | None = None,
    ngff_version: NgffVersions | None = None,
    # Zarr Array parameters
    chunks: ChunksLike | None = None,
    shards: ShardsLike | None = None,
    dtype: str | None = None,
    dimension_separator: Literal[".", "/"] | None = None,
    compressors: CompressorLike | None = None,
    extra_array_kwargs: Mapping[str, Any] | None = None,
    overwrite: bool = False,
    # Copy from current image
    copy_labels: bool = False,
    copy_tables: bool = False,
) -> "OmeZarrContainer":
    """Derive a new OME-Zarr container from the current image.

    If a kwarg is not provided, the value from the reference image will be used.

    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 (Sequence[int] | None): The shape of the new image.
        pixelsize (float | tuple[float, float] | None): The pixel size of the new
            image.
            A value to write, not a lookup key; to select an existing
            level see `pixel_size` on the getters.
        z_spacing (float | None): The z spacing of the new image.
        time_spacing (float | None): The time spacing of the new image.
        name (str | None): The name of the new image.
        translation (Sequence[float] | None): The translation for each axis
            at the highest resolution level. Defaults to None.
        channels_policy (Literal["squeeze", "same", "singleton"] | int): Possible
            policies:
            - If "squeeze", the channels axis will be removed (no matter its size).
            - If "same", the channels axis will be kept as is (if it exists).
            - If "singleton", the channels axis will be set to size 1.
            - If an integer is provided, the channels axis will be changed to have
                that size.
        channels_meta (Sequence[str | Channel] | None): The channels metadata
            of the new image.
        ngff_version (NgffVersions | None): The NGFF version to use.
        chunks (ChunksLike | None): The chunk shape of the new image.
        shards (ShardsLike | None): The shard shape of the new image.
        dtype (str | None): The data type of the new image.
        dimension_separator (Literal[".", "/"] | None): The separator to use for
            dimensions.
        compressors (CompressorLike | None): The compressors to use.
        extra_array_kwargs (Mapping[str, Any] | None): Extra arguments to pass to
            the zarr array creation.
        overwrite (bool): Whether to overwrite an existing image. Defaults to False.
        copy_labels (bool): Whether to copy the labels from the current image.
            Defaults to False.
        copy_tables (bool): Whether to copy the tables from the current image.
            Defaults to False.

    Returns:
        OmeZarrContainer: The new derived OME-Zarr container.

    """
    new_container = self._images_container.derive(
        store=store,
        ref_path=ref_path,
        shape=shape,
        pixelsize=pixelsize,
        z_spacing=z_spacing,
        time_spacing=time_spacing,
        name=name,
        translation=translation,
        channels_meta=channels_meta,
        channels_policy=channels_policy,
        ngff_version=ngff_version,
        chunks=chunks,
        shards=shards,
        dtype=dtype,
        dimension_separator=dimension_separator,
        compressors=compressors,
        extra_array_kwargs=extra_array_kwargs,
        overwrite=overwrite,
    )
    new_ome_zarr = OmeZarrContainer(
        group_handler=new_container._group_handler,
        validate_arrays=False,
        axes_setup=new_container.meta.axes_handler.axes_setup,
    )

    if copy_labels:
        self.labels_container._group_handler.copy_group(
            new_ome_zarr.labels_container._group_handler.group
        )

    if copy_tables:
        self.tables_container._group_handler.copy_group(
            new_ome_zarr.tables_container._group_handler.group
        )
    return new_ome_zarr

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

    return table_container.list(
        filter_types=filter_types,
    )

def list_roi_tables(self) -> list[str]:
    """List all ROI tables in the image.

    Returns `[]` when the image has no tables, matching `list_tables`.
    """
    table_container = self._get_tables_container(create_mode=False)
    if table_container is None:
        return []

    roi = table_container.list(filter_types="roi_table")
    masking_roi = table_container.list(filter_types="masking_roi_table")
    return roi + masking_roi

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

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

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

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

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