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 
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 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
200
201
202
203
204
205
class NgffImage:
    """A class to handle OME-NGFF images."""

    def __init__(
        self, store: StoreLike, cache: bool = False, mode: AccessModeLiteral = "r+"
    ) -> None:
        """Initialize the NGFFImage in read mode."""
        self.store = store
        self._mode = mode
        self.group = open_group_wrapper(store=store, mode=self._mode)

        if self.group.read_only:
            self._mode = "r"

        self._image_meta = get_ngff_image_meta_handler(
            self.group, meta_mode="image", cache=cache
        )
        self._metadata_cache = cache
        self.table = TableGroup(self.group, mode=self._mode)
        self.label = LabelGroup(self.group, image_ref=self.get_image(), mode=self._mode)

        ngio_logger.info(f"Opened image located in store: {store}")
        ngio_logger.info(f"- Image number of levels: {self.num_levels}")

    @property
    def image_meta(self) -> ImageMeta:
        """Get the image metadata."""
        meta = self._image_meta.load_meta()
        assert isinstance(meta, ImageMeta)
        return 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

        image = Image(
            store=self.group,
            path=path,
            pixel_size=pixel_size,
            highest_resolution=highest_resolution,
            label_group=LabelGroup(self.group, image_ref=None, mode=self._mode),
            cache=self._metadata_cache,
            mode=self._mode,
        )
        ngio_logger.info(f"Opened image at path: {image.path}")
        ngio_logger.info(f"- {image.dimensions}")
        ngio_logger.info(f"- {image.pixel_size}")
        return image

    def update_omero_window(
        self, start_percentile: int = 5, end_percentile: int = 95
    ) -> None:
        """Update the OMERO window.

        This will setup percentiles based values for the window of each channel.

        Args:
            start_percentile (int): The start percentile.
            end_percentile (int): The end percentile

        """
        meta = self.image_meta

        lowest_res_image = self.get_image(highest_resolution=True)
        lowest_res_shape = lowest_res_image.shape
        for path in self.levels_paths:
            image = self.get_image(path=path)
            if np.prod(image.shape) < np.prod(lowest_res_shape):
                lowest_res_shape = image.shape
                lowest_res_image = image

        max_dtype = np.iinfo(image.on_disk_array.dtype).max
        num_c = lowest_res_image.dimensions.get("c", 1)

        if meta.omero is None:
            raise NotImplementedError(
                "OMERO metadata not found. " " Please add OMERO metadata to the image."
            )

        channel_list = meta.omero.channels
        if len(channel_list) != num_c:
            raise ValueError("The number of channels does not match the image.")

        for c, channel in enumerate(channel_list):
            data = image.get_array(c=c, mode="dask").ravel()
            _start_percentile = da.percentile(
                data, start_percentile, method="nearest"
            ).compute()
            _end_percentile = da.percentile(
                data, end_percentile, method="nearest"
            ).compute()
            channel.extra_fields["window"] = {
                "start": _start_percentile,
                "end": _end_percentile,
                "min": 0,
                "max": max_dtype,
            }
            ngio_logger.info(
                f"Updated window for channel {channel.label}. "
                f"Start: {start_percentile}, End: {end_percentile}"
            )
            meta.omero.channels[c] = channel

        self._image_meta.write_meta(meta)

    def derive_new_image(
        self,
        store: StoreLike,
        name: str,
        overwrite: bool = True,
        **kwargs: dict,
    ) -> "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)

        # Get the channel information if it exists
        omero = self.image_meta.omero
        if omero is not None:
            channels = omero.channels
            omero_kwargs = omero.extra_fields
        else:
            channels = []
            omero_kwargs = {}

        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": [ch.wavelength_id for ch in channels],
            "channel_kwargs": [ch.extra_fields for ch in channels],
            "omero_kwargs": omero_kwargs,
            "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, cache: bool = False, mode: AccessModeLiteral = 'r+') -> None

Initialize the NGFFImage in read mode.

Source code in ngio/core/ngff_image.py 
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
def __init__(
    self, store: StoreLike, cache: bool = False, mode: AccessModeLiteral = "r+"
) -> None:
    """Initialize the NGFFImage in read mode."""
    self.store = store
    self._mode = mode
    self.group = open_group_wrapper(store=store, mode=self._mode)

    if self.group.read_only:
        self._mode = "r"

    self._image_meta = get_ngff_image_meta_handler(
        self.group, meta_mode="image", cache=cache
    )
    self._metadata_cache = cache
    self.table = TableGroup(self.group, mode=self._mode)
    self.label = LabelGroup(self.group, image_ref=self.get_image(), mode=self._mode)

    ngio_logger.info(f"Opened image located in store: {store}")
    ngio_logger.info(f"- Image number of levels: {self.num_levels}")

derive_new_image(store: StoreLike, name: str, overwrite: bool = True, **kwargs: dict) -> 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 (dict, default: {} ) –

    Additional keyword arguments. Follow the same signature as create_empty_ome_zarr_image.

Returns:

Source code in ngio/core/ngff_image.py 
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
200
201
202
203
204
205
def derive_new_image(
    self,
    store: StoreLike,
    name: str,
    overwrite: bool = True,
    **kwargs: dict,
) -> "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)

    # Get the channel information if it exists
    omero = self.image_meta.omero
    if omero is not None:
        channels = omero.channels
        omero_kwargs = omero.extra_fields
    else:
        channels = []
        omero_kwargs = {}

    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": [ch.wavelength_id for ch in channels],
        "channel_kwargs": [ch.extra_fields for ch in channels],
        "omero_kwargs": omero_kwargs,
        "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 
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
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

    image = Image(
        store=self.group,
        path=path,
        pixel_size=pixel_size,
        highest_resolution=highest_resolution,
        label_group=LabelGroup(self.group, image_ref=None, mode=self._mode),
        cache=self._metadata_cache,
        mode=self._mode,
    )
    ngio_logger.info(f"Opened image at path: {image.path}")
    ngio_logger.info(f"- {image.dimensions}")
    ngio_logger.info(f"- {image.pixel_size}")
    return image

update_omero_window(start_percentile: int = 5, end_percentile: int = 95) -> None

Update the OMERO window.

This will setup percentiles based values for the window of each channel.

Parameters:

  • start_percentile (int, default: 5 ) –

    The start percentile.

  • end_percentile (int, default: 95 ) –

    The end percentile

Source code in ngio/core/ngff_image.py 
 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
def update_omero_window(
    self, start_percentile: int = 5, end_percentile: int = 95
) -> None:
    """Update the OMERO window.

    This will setup percentiles based values for the window of each channel.

    Args:
        start_percentile (int): The start percentile.
        end_percentile (int): The end percentile

    """
    meta = self.image_meta

    lowest_res_image = self.get_image(highest_resolution=True)
    lowest_res_shape = lowest_res_image.shape
    for path in self.levels_paths:
        image = self.get_image(path=path)
        if np.prod(image.shape) < np.prod(lowest_res_shape):
            lowest_res_shape = image.shape
            lowest_res_image = image

    max_dtype = np.iinfo(image.on_disk_array.dtype).max
    num_c = lowest_res_image.dimensions.get("c", 1)

    if meta.omero is None:
        raise NotImplementedError(
            "OMERO metadata not found. " " Please add OMERO metadata to the image."
        )

    channel_list = meta.omero.channels
    if len(channel_list) != num_c:
        raise ValueError("The number of channels does not match the image.")

    for c, channel in enumerate(channel_list):
        data = image.get_array(c=c, mode="dask").ravel()
        _start_percentile = da.percentile(
            data, start_percentile, method="nearest"
        ).compute()
        _end_percentile = da.percentile(
            data, end_percentile, method="nearest"
        ).compute()
        channel.extra_fields["window"] = {
            "start": _start_percentile,
            "end": _end_percentile,
            "min": 0,
            "max": max_dtype,
        }
        ngio_logger.info(
            f"Updated window for channel {channel.label}. "
            f"Start: {start_percentile}, End: {end_percentile}"
        )
        meta.omero.channels[c] = channel

    self._image_meta.write_meta(meta)