Images API reference¶

def has_axis(self, axis: str) -> bool:
    """Return True if the image has the given axis."""
    return self.axes_handler.has_axis(axis)

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

    Args:
        space_unit: The space unit of the image.
        time_unit: The time unit of the image.
    """
    meta = self._meta_handler.get_meta()
    meta = meta.to_units(space_unit=space_unit, time_unit=time_unit)
    self._meta_handler.update_meta(meta)

@deprecated(replacement="set_axes_units()")
def set_axes_unit(
    self,
    space_unit: SpaceUnits = DefaultSpaceUnit,
    time_unit: TimeUnits = DefaultTimeUnit,
) -> None:
    """Deprecated alias for `set_axes_units`."""
    self.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 label.

    Args:
        axes_names (Sequence[str]): The axes names to set.
    """
    meta = self._meta_handler.get_meta()
    meta = meta.rename_axes(axes_names=axes_names)
    self._meta_handler._axes_setup = meta.axes_handler.axes_setup
    self._meta_handler.update_meta(meta)

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.
    """
    meta = self._meta_handler.get_meta()
    meta = meta.rename_image(name=name)
    self._meta_handler.update_meta(meta)

def roi(self, name: str | None = "image") -> Roi:
    """Return the ROI covering the entire image."""
    slices = {}
    for ax_name in ["t", "z", "y", "x"]:
        axis_size = self.dimensions.get(ax_name, default=None)
        if axis_size is None:
            continue
        slices[ax_name] = slice(0, axis_size)
    roi_px = Roi.from_values(name=name, slices=slices, space="pixel")
    return roi_px.to_world(pixel_size=self.pixel_size)

def build_image_roi_table(self, name: str | None = "image") -> RoiTable:
    """Build the ROI table containing the ROI covering the entire image."""
    return RoiTable(rois=[self.roi(name=name)])

def require_dimensions_match(
    self,
    other: "AbstractImage",
    allow_singleton: bool = False,
) -> None:
    """Assert that two images have matching spatial dimensions.

    Args:
        other: The other image to compare to.
        allow_singleton: If True, allow singleton dimensions to be
            compatible with non-singleton dimensions.

    Raises:
        NgioValueError: If the images do not have compatible dimensions.
    """
    self.dimensions.require_dimensions_match(
        other.dimensions, allow_singleton=allow_singleton
    )

def check_if_dimensions_match(
    self,
    other: "AbstractImage",
    allow_singleton: bool = False,
) -> bool:
    """Check if two images have matching spatial dimensions.

    Args:
        other: The other image to compare to.
        allow_singleton: If True, allow singleton dimensions to be
            compatible with non-singleton dimensions.

    Returns:
        bool: True if the images have matching dimensions, False otherwise.
    """
    return self.dimensions.check_if_dimensions_match(
        other.dimensions, allow_singleton=allow_singleton
    )

def require_axes_match(
    self,
    other: "AbstractImage",
) -> None:
    """Assert that two images have compatible axes.

    Args:
        other: The other image to compare to.

    Raises:
        NgioValueError: If the images do not have compatible axes.
    """
    self.dimensions.require_axes_match(other.dimensions)

def check_if_axes_match(
    self,
    other: "AbstractImage",
) -> bool:
    """Check if two images have compatible axes.

    Args:
        other: The other image to compare to.

    Returns:
        bool: True if the images have compatible axes, False otherwise.

    """
    return self.dimensions.check_if_axes_match(other.dimensions)

def require_rescalable(
    self,
    other: "AbstractImage",
) -> None:
    """Assert that two images can be rescaled to each other.

    For this to be true, the images must have the same axes, and
    the pixel sizes must be compatible (i.e. one can be scaled to the other).

    Args:
        other: The other image to compare to.

    Raises:
        NgioValueError: If the images cannot be scaled to each other.
    """
    self.dimensions.require_rescalable(other.dimensions)

def check_if_rescalable(
    self,
    other: "AbstractImage",
) -> bool:
    """Check if two images can be rescaled to each other.

    For this to be true, the images must have the same axes, and
    the pixel sizes must be compatible (i.e. one can be scaled to the other).

    Args:
        other: The other image to compare to.

    Returns:
        bool: True if the images can be rescaled to each other, False otherwise.
    """
    return self.dimensions.check_if_rescalable(other.dimensions)

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.channels_meta.get_channel_idx(
        channel_label=channel_label, wavelength_id=wavelength_id
    )

def get_as_numpy(
    self,
    channel_selection: ChannelSlicingInputType = None,
    axes_order: Sequence[str] | None = None,
    transforms: Sequence[TransformProtocol] | None = None,
    **slicing_kwargs: slice | int | Sequence[int] | None,
) -> np.ndarray:
    """Get the image as a numpy array.

    Args:
        channel_selection: Select a specific channel by label.
            If None, all channels are returned.
            Alternatively, you can slice arbitrary channels
            using the slice_kwargs (c=[0, 2]).
        axes_order: The order of the axes to return the array.
        transforms: The transforms to apply to the array.
        **slicing_kwargs: The slices to get the array.

    Returns:
        The array of the region of interest.
    """
    _slicing_kwargs = add_channel_selection_to_slicing_dict(
        image=self, channel_selection=channel_selection, slicing_dict=slicing_kwargs
    )
    return self._get_as_numpy(
        axes_order=axes_order, transforms=transforms, **_slicing_kwargs
    )

def get_roi_as_numpy(
    self,
    roi: Roi,
    channel_selection: ChannelSlicingInputType = None,
    axes_order: Sequence[str] | None = None,
    transforms: Sequence[TransformProtocol] | None = None,
    **slicing_kwargs: SlicingInputType,
) -> np.ndarray:
    """Get the image as a numpy array for a region of interest.

    Args:
        roi: The region of interest to get the array.
        channel_selection: Select a what subset of channels to return.
            If None, all channels are returned.
        axes_order: The order of the axes to return the array.
        transforms: The transforms to apply to the array.
        **slicing_kwargs: The slices to get the array.

    Returns:
        The array of the region of interest.
    """
    _slicing_kwargs = add_channel_selection_to_slicing_dict(
        image=self, channel_selection=channel_selection, slicing_dict=slicing_kwargs
    )
    return self._get_roi_as_numpy(
        roi=roi, axes_order=axes_order, transforms=transforms, **_slicing_kwargs
    )

def get_as_dask(
    self,
    channel_selection: ChannelSlicingInputType = None,
    axes_order: Sequence[str] | None = None,
    transforms: Sequence[TransformProtocol] | None = None,
    **slicing_kwargs: SlicingInputType,
) -> da.Array:
    """Get the image as a dask array.

    Args:
        channel_selection: Select a what subset of channels to return.
            If None, all channels are returned.
        axes_order: The order of the axes to return the array.
        transforms: The transforms to apply to the array.
        **slicing_kwargs: The slices to get the array.

    Returns:
        The dask array of the region of interest.
    """
    _slicing_kwargs = add_channel_selection_to_slicing_dict(
        image=self, channel_selection=channel_selection, slicing_dict=slicing_kwargs
    )
    return self._get_as_dask(
        axes_order=axes_order, transforms=transforms, **_slicing_kwargs
    )

def get_roi_as_dask(
    self,
    roi: Roi,
    channel_selection: ChannelSlicingInputType = None,
    axes_order: Sequence[str] | None = None,
    transforms: Sequence[TransformProtocol] | None = None,
    **slicing_kwargs: SlicingInputType,
) -> da.Array:
    """Get the image as a dask array for a region of interest.

    Args:
        roi: The region of interest to get the array.
        channel_selection: Select a what subset of channels to return.
            If None, all channels are returned.
        axes_order: The order of the axes to return the array.
        transforms: The transforms to apply to the array.
        **slicing_kwargs: The slices to get the array.

    Returns:
        The dask array of the region of interest.
    """
    _slicing_kwargs = add_channel_selection_to_slicing_dict(
        image=self, channel_selection=channel_selection, slicing_dict=slicing_kwargs
    )
    return self._get_roi_as_dask(
        roi=roi, axes_order=axes_order, transforms=transforms, **_slicing_kwargs
    )

def get_array(
    self,
    channel_selection: ChannelSlicingInputType = None,
    axes_order: Sequence[str] | None = None,
    transforms: Sequence[TransformProtocol] | None = None,
    mode: Literal["numpy", "dask"] = "numpy",
    **slicing_kwargs: SlicingInputType,
) -> np.ndarray | da.Array:
    """Get the image as a zarr array.

    Args:
        channel_selection: Select a what subset of channels to return.
            If None, all channels are returned.
        axes_order: The order of the axes to return the array.
        transforms: The transforms to apply to the array.
        mode: The object type to return.
            Can be "dask", "numpy".
        **slicing_kwargs: The slices to get the array.

    Returns:
        The zarr array of the region of interest.
    """
    _slicing_kwargs = add_channel_selection_to_slicing_dict(
        image=self, channel_selection=channel_selection, slicing_dict=slicing_kwargs
    )
    return self._get_array(
        axes_order=axes_order, mode=mode, transforms=transforms, **_slicing_kwargs
    )

def get_roi(
    self,
    roi: Roi,
    channel_selection: ChannelSlicingInputType = None,
    axes_order: Sequence[str] | None = None,
    transforms: Sequence[TransformProtocol] | None = None,
    mode: Literal["numpy", "dask"] = "numpy",
    **slicing_kwargs: SlicingInputType,
) -> np.ndarray | da.Array:
    """Get the image as a zarr array for a region of interest.

    Args:
        roi: The region of interest to get the array.
        channel_selection: Select a what subset of channels to return.
            If None, all channels are returned.
        axes_order: The order of the axes to return the array.
        transforms: The transforms to apply to the array.
        mode: The object type to return.
            Can be "dask", "numpy".
        **slicing_kwargs: The slices to get the array.

    Returns:
        The zarr array of the region of interest.
    """
    _slicing_kwargs = add_channel_selection_to_slicing_dict(
        image=self, channel_selection=channel_selection, slicing_dict=slicing_kwargs
    )
    return self._get_roi(
        roi=roi,
        axes_order=axes_order,
        mode=mode,
        transforms=transforms,
        **_slicing_kwargs,
    )

def set_array(
    self,
    patch: np.ndarray | da.Array,
    channel_selection: ChannelSlicingInputType = None,
    axes_order: Sequence[str] | None = None,
    transforms: Sequence[TransformProtocol] | None = None,
    **slicing_kwargs: SlicingInputType,
) -> None:
    """Set the image array.

    Args:
        patch: The array to set.
        channel_selection: Select a what subset of channels to return.
            If None, all channels are set.
        axes_order: The order of the axes to set the array.
        transforms: The transforms to apply to the array.
        **slicing_kwargs: The slices to set the array.
    """
    _slicing_kwargs = add_channel_selection_to_slicing_dict(
        image=self, channel_selection=channel_selection, slicing_dict=slicing_kwargs
    )
    self._set_array(
        patch=patch, axes_order=axes_order, transforms=transforms, **_slicing_kwargs
    )

def set_roi(
    self,
    roi: Roi,
    patch: np.ndarray | da.Array,
    channel_selection: ChannelSlicingInputType = None,
    axes_order: Sequence[str] | None = None,
    transforms: Sequence[TransformProtocol] | None = None,
    **slicing_kwargs: SlicingInputType,
) -> None:
    """Set the image array for a region of interest.

    Args:
        roi: The region of interest to set the array.
        patch: The array to set.
        channel_selection: Select a what subset of channels to return.
        axes_order: The order of the axes to set the array.
        transforms: The transforms to apply to the array.
        **slicing_kwargs: The slices to set the array.
    """
    _slicing_kwargs = add_channel_selection_to_slicing_dict(
        image=self, channel_selection=channel_selection, slicing_dict=slicing_kwargs
    )
    self._set_roi(
        roi=roi,
        patch=patch,
        axes_order=axes_order,
        transforms=transforms,
        **_slicing_kwargs,
    )

def consolidate(
    self,
    order: InterpolationOrder = "linear",
    mode: Literal["dask", "numpy", "coarsen"] = "dask",
) -> None:
    """Consolidate the label on disk."""
    self._consolidate(order=order, mode=mode)

def has_axis(self, axis: str) -> bool:
    """Return True if the image has the given axis."""
    return self.axes_handler.has_axis(axis)

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

    Args:
        space_unit: The space unit of the image.
        time_unit: The time unit of the image.
    """
    meta = self._meta_handler.get_meta()
    meta = meta.to_units(space_unit=space_unit, time_unit=time_unit)
    self._meta_handler.update_meta(meta)

@deprecated(replacement="set_axes_units()")
def set_axes_unit(
    self,
    space_unit: SpaceUnits = DefaultSpaceUnit,
    time_unit: TimeUnits = DefaultTimeUnit,
) -> None:
    """Deprecated alias for `set_axes_units`."""
    self.set_axes_units(space_unit=space_unit, time_unit=time_unit)