Skip to content

ngio.core

ngio.core

Core classes for the ngio library.

NGFFImage

ngio.core.NgffImage

A class to handle OME-NGFF images.

Source code in ngio/core/ngff_image.py 
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
class NgffImage:
    """A class to handle OME-NGFF images."""

    def __init__(self, store: StoreLike) -> None:
        """Initialize the NGFFImage in read mode."""
        self.store = store
        self.group = open_group_wrapper(store=store, mode="r+")
        self._image_meta = get_ngff_image_meta_handler(
            self.group, meta_mode="image", cache=False
        )

        self.table = TableGroup(self.group)
        self.label = LabelGroup(self.group, image_ref=self.get_image())

    @property
    def image_meta(self) -> ImageMeta:
        """Get the image metadata."""
        return self._image_meta.load_meta()

    @property
    def num_levels(self) -> int:
        """Get the number of levels in the image."""
        return self.image_meta.num_levels

    @property
    def levels_paths(self) -> list[str]:
        """Get the paths of the levels in the image."""
        return self.image_meta.levels_paths

    def get_image(
        self,
        *,
        path: str | None = None,
        pixel_size: PixelSize | None = None,
        highest_resolution: bool = True,
    ) -> Image:
        """Get an image handler for the given level.

        Args:
            path (str | None, optional): The path to the level.
            pixel_size (tuple[float, ...] | list[float] | None, optional): The pixel
                size of the level.
            highest_resolution (bool, optional): Whether to get the highest
                resolution level

        Returns:
            ImageHandler: The image handler.
        """
        if path is not None or pixel_size is not None:
            highest_resolution = False

        return Image(
            store=self.group,
            path=path,
            pixel_size=pixel_size,
            highest_resolution=highest_resolution,
            label_group=LabelGroup(self.group, image_ref=None),
        )

    def _update_omero_window(self) -> None:
        """Update the OMERO window."""
        meta = self.image_meta
        image = self.get_image(highest_resolution=True)
        max_dtype = np.iinfo(image.on_disk_array.dtype).max
        start, end = (
            image.on_disk_dask_array.min().compute(),
            image.on_disk_dask_array.max().compute(),
        )

        channel_list = meta.omero.channels

        new_channel_list = []
        for channel in channel_list:
            channel.extra_fields["window"] = {
                "start": start,
                "end": end,
                "min": 0,
                "max": max_dtype,
            }
            new_channel_list.append(channel)

        meta.omero.channels = new_channel_list
        self._image_meta.write_meta(meta)

    def derive_new_image(
        self,
        store: StoreLike,
        name: str,
        overwrite: bool = True,
        **kwargs,
    ) -> "NgffImage":
        """Derive a new image from the current image.

        Args:
            store (StoreLike): The store to create the new image in.
            name (str): The name of the new image.
            overwrite (bool): Whether to overwrite the image if it exists
            **kwargs: Additional keyword arguments.
                Follow the same signature as `create_empty_ome_zarr_image`.

        Returns:
            NgffImage: The new image.
        """
        image_0 = self.get_image(highest_resolution=True)

        default_kwargs = {
            "store": store,
            "shape": image_0.on_disk_shape,
            "chunks": image_0.on_disk_array.chunks,
            "dtype": image_0.on_disk_array.dtype,
            "on_disk_axis": image_0.dataset.on_disk_axes_names,
            "pixel_sizes": image_0.pixel_size,
            "xy_scaling_factor": self.image_meta.xy_scaling_factor,
            "z_scaling_factor": self.image_meta.z_scaling_factor,
            "time_spacing": image_0.dataset.time_spacing,
            "time_units": image_0.dataset.time_axis_unit,
            "num_levels": self.num_levels,
            "name": name,
            "channel_labels": image_0.channel_labels,
            "channel_wavelengths": None,
            "channel_kwargs": None,
            "omero_kwargs": None,
            "overwrite": overwrite,
            "version": self.image_meta.version,
        }

        default_kwargs.update(kwargs)

        create_empty_ome_zarr_image(
            **default_kwargs,
        )
        return NgffImage(store=store)

image_meta: ImageMeta property

Get the image metadata.

levels_paths: list[str] property

Get the paths of the levels in the image.

num_levels: int property

Get the number of levels in the image.

__init__(store: StoreLike) -> None

Initialize the NGFFImage in read mode.

Source code in ngio/core/ngff_image.py 
71
72
73
74
75
76
77
78
79
80
def __init__(self, store: StoreLike) -> None:
    """Initialize the NGFFImage in read mode."""
    self.store = store
    self.group = open_group_wrapper(store=store, mode="r+")
    self._image_meta = get_ngff_image_meta_handler(
        self.group, meta_mode="image", cache=False
    )

    self.table = TableGroup(self.group)
    self.label = LabelGroup(self.group, image_ref=self.get_image())

derive_new_image(store: StoreLike, name: str, overwrite: bool = True, **kwargs) -> NgffImage

Derive a new image from the current image.

Parameters:

  • store (StoreLike) –

    The store to create the new image in.

  • name (str) –

    The name of the new image.

  • overwrite (bool, default: True ) –

    Whether to overwrite the image if it exists

  • **kwargs –

    Additional keyword arguments. Follow the same signature as create_empty_ome_zarr_image.

Returns:

Source code in ngio/core/ngff_image.py 
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
def derive_new_image(
    self,
    store: StoreLike,
    name: str,
    overwrite: bool = True,
    **kwargs,
) -> "NgffImage":
    """Derive a new image from the current image.

    Args:
        store (StoreLike): The store to create the new image in.
        name (str): The name of the new image.
        overwrite (bool): Whether to overwrite the image if it exists
        **kwargs: Additional keyword arguments.
            Follow the same signature as `create_empty_ome_zarr_image`.

    Returns:
        NgffImage: The new image.
    """
    image_0 = self.get_image(highest_resolution=True)

    default_kwargs = {
        "store": store,
        "shape": image_0.on_disk_shape,
        "chunks": image_0.on_disk_array.chunks,
        "dtype": image_0.on_disk_array.dtype,
        "on_disk_axis": image_0.dataset.on_disk_axes_names,
        "pixel_sizes": image_0.pixel_size,
        "xy_scaling_factor": self.image_meta.xy_scaling_factor,
        "z_scaling_factor": self.image_meta.z_scaling_factor,
        "time_spacing": image_0.dataset.time_spacing,
        "time_units": image_0.dataset.time_axis_unit,
        "num_levels": self.num_levels,
        "name": name,
        "channel_labels": image_0.channel_labels,
        "channel_wavelengths": None,
        "channel_kwargs": None,
        "omero_kwargs": None,
        "overwrite": overwrite,
        "version": self.image_meta.version,
    }

    default_kwargs.update(kwargs)

    create_empty_ome_zarr_image(
        **default_kwargs,
    )
    return NgffImage(store=store)

get_image(*, path: str | None = None, pixel_size: PixelSize | None = None, highest_resolution: bool = True) -> Image

Get an image handler for the given level.

Parameters:

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

    The path to the level.

  • pixel_size (tuple[float, ...] | list[float] | None, default: None ) –

    The pixel size of the level.

  • highest_resolution (bool, default: True ) –

    Whether to get the highest resolution level

Returns:

  • ImageHandler ( Image ) –

    The image handler.

Source code in ngio/core/ngff_image.py 
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
def get_image(
    self,
    *,
    path: str | None = None,
    pixel_size: PixelSize | None = None,
    highest_resolution: bool = True,
) -> Image:
    """Get an image handler for the given level.

    Args:
        path (str | None, optional): The path to the level.
        pixel_size (tuple[float, ...] | list[float] | None, optional): The pixel
            size of the level.
        highest_resolution (bool, optional): Whether to get the highest
            resolution level

    Returns:
        ImageHandler: The image handler.
    """
    if path is not None or pixel_size is not None:
        highest_resolution = False

    return Image(
        store=self.group,
        path=path,
        pixel_size=pixel_size,
        highest_resolution=highest_resolution,
        label_group=LabelGroup(self.group, image_ref=None),
    )