Skip to content

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+",
    axes_setup: AxesSetup | None = None,
    validate_arrays: bool = True,
) -> OmeZarrContainer

Open an OME-Zarr image.

Source code in ngio/images/_ome_zarr_container.py 
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
def open_ome_zarr_container(
    store: StoreOrGroup,
    cache: bool = False,
    mode: AccessModeLiteral = "r+",
    axes_setup: AxesSetup | None = None,
    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,
        axes_setup=axes_setup,
    )

Create an OME-Zarr Container

ngio.create_empty_ome_zarr 

create_empty_ome_zarr(
    store: StoreOrGroup,
    shape: Sequence[int],
    pixelsize: float | tuple[float, float] | None = None,
    z_spacing: float = 1.0,
    time_spacing: float = 1.0,
    scaling_factors: Sequence[float]
    | Literal["auto"] = "auto",
    levels: int | list[str] = 5,
    translation: Sequence[float] | None = None,
    space_unit: SpaceUnits = DefaultSpaceUnit,
    time_unit: TimeUnits = DefaultTimeUnit,
    axes_names: Sequence[str] | None = None,
    channels_meta: Sequence[str | Channel] | None = None,
    name: str | None = None,
    axes_setup: AxesSetup | None = None,
    ngff_version: NgffVersions = DefaultNgffVersion,
    chunks: ChunksLike = "auto",
    shards: ShardsLike | None = None,
    dtype: str = "uint16",
    dimension_separator: Literal[".", "/"] = "/",
    compressors: CompressorLike = "auto",
    extra_array_kwargs: Mapping[str, Any] | None = None,
    overwrite: bool = False,
    xy_pixelsize: float | None = None,
    xy_scaling_factor: float | None = None,
    z_scaling_factor: float | None = None,
    channel_labels: list[str] | None = None,
    channel_wavelengths: list[str] | None = None,
    channel_colors: Sequence[str] | None = None,
    channel_active: Sequence[bool] | None = None,
) -> 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 (Sequence[int]) –

    The shape of the image.

  • pixelsize (float | tuple[float, float] | None, default: None ) –

    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.

  • scaling_factors (Sequence[float] | Literal['auto'], default: 'auto' ) –

    The down-scaling factors for the pyramid levels. Defaults to "auto".

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

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

  • translation (Sequence[float] | None, default: None ) –

    The translation for each axis. at the highest resolution level. Defaults to None.

  • 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 (Sequence[str] | None, default: None ) –

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

  • channels_meta (Sequence[str | Channel] | None, default: None ) –

    The channels metadata. Defaults to None.

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

    The name of the image. Defaults to None.

  • axes_setup (AxesSetup | None, default: None ) –

    Axes setup to create ome-zarr with non-standard axes configurations. Defaults to None.

  • ngff_version (NgffVersions, default: DefaultNgffVersion ) –

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

  • chunks (ChunksLike, default: 'auto' ) –

    The chunk shape. Defaults to "auto".

  • shards (ShardsLike | None, default: None ) –

    The shard shape. Defaults to None.

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

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

  • dimension_separator (Literal['.', '/'], default: '/' ) –

    The dimension separator to use. Defaults to "/".

  • compressors (CompressorLike, default: 'auto' ) –

    The compressor to use. Defaults to "auto".

  • extra_array_kwargs (Mapping[str, Any] | None, default: None ) –

    Extra arguments to pass to the zarr array creation. Defaults to None.

  • overwrite (bool, default: False ) –

    Whether to overwrite an existing image. Defaults to False.

  • xy_pixelsize (float | None, default: None ) –

    Deprecated. Use pixelsize instead.

  • xy_scaling_factor (float | None, default: None ) –

    Deprecated. Use scaling_factors instead.

  • z_scaling_factor (float | None, default: None ) –

    Deprecated. Use scaling_factors instead.

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

    Deprecated. Use channels_meta instead.

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

    Deprecated. Use channels_meta instead.

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

    Deprecated. Use channels_meta instead.

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

    Deprecated. Use channels_meta instead.

Source code in ngio/images/_ome_zarr_container.py 
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
def create_empty_ome_zarr(
    store: StoreOrGroup,
    shape: Sequence[int],
    pixelsize: float | tuple[float, float] | None = None,
    z_spacing: float = 1.0,
    time_spacing: float = 1.0,
    scaling_factors: Sequence[float] | Literal["auto"] = "auto",
    levels: int | list[str] = 5,
    translation: Sequence[float] | None = None,
    space_unit: SpaceUnits = DefaultSpaceUnit,
    time_unit: TimeUnits = DefaultTimeUnit,
    axes_names: Sequence[str] | None = None,
    channels_meta: Sequence[str | Channel] | None = None,
    name: str | None = None,
    axes_setup: AxesSetup | None = None,
    ngff_version: NgffVersions = DefaultNgffVersion,
    chunks: ChunksLike = "auto",
    shards: ShardsLike | None = None,
    dtype: str = "uint16",
    dimension_separator: Literal[".", "/"] = "/",
    compressors: CompressorLike = "auto",
    extra_array_kwargs: Mapping[str, Any] | None = None,
    overwrite: bool = False,
    # Deprecated arguments
    xy_pixelsize: float | None = None,
    xy_scaling_factor: float | None = None,
    z_scaling_factor: float | None = None,
    channel_labels: list[str] | None = None,
    channel_wavelengths: list[str] | None = None,
    channel_colors: Sequence[str] | None = None,
    channel_active: Sequence[bool] | None = None,
) -> 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 (Sequence[int]): The shape of the image.
        pixelsize (float | tuple[float, float] | None): The pixel size in x and y
            dimensions.
        z_spacing (float): The spacing between z slices. Defaults to 1.0.
        time_spacing (float): The spacing between time points. Defaults to 1.0.
        scaling_factors (Sequence[float] | Literal["auto"]): The down-scaling factors
            for the pyramid levels. Defaults to "auto".
        levels (int | list[str]): The number of levels in the pyramid or a list of
            level names. Defaults to 5.
        translation (Sequence[float] | None): The translation for each axis.
            at the highest resolution level. Defaults to None.
        space_unit (SpaceUnits): The unit of space. Defaults to DefaultSpaceUnit.
        time_unit (TimeUnits): The unit of time. Defaults to DefaultTimeUnit.
        axes_names (Sequence[str] | None): The names of the axes. If None the
            canonical names are used. Defaults to None.
        channels_meta (Sequence[str | Channel] | None): The channels metadata.
            Defaults to None.
        name (str | None): The name of the image. Defaults to None.
        axes_setup (AxesSetup | None): Axes setup to create ome-zarr with
            non-standard axes configurations. Defaults to None.
        ngff_version (NgffVersions): The version of the OME-Zarr specification.
            Defaults to DefaultNgffVersion.
        chunks (ChunksLike): The chunk shape. Defaults to "auto".
        shards (ShardsLike | None): The shard shape. Defaults to None.
        dtype (str): The data type of the image. Defaults to "uint16".
        dimension_separator (Literal[".", "/"]): The dimension separator to use.
            Defaults to "/".
        compressors (CompressorLike): The compressor to use. Defaults to "auto".
        extra_array_kwargs (Mapping[str, Any] | None): Extra arguments to pass to
            the zarr array creation. Defaults to None.
        overwrite (bool): Whether to overwrite an existing image. Defaults to False.
        xy_pixelsize (float | None): Deprecated. Use pixelsize instead.
        xy_scaling_factor (float | None): Deprecated. Use scaling_factors instead.
        z_scaling_factor (float | None): Deprecated. Use scaling_factors instead.
        channel_labels (list[str] | None): Deprecated. Use channels_meta instead.
        channel_wavelengths (list[str] | None): Deprecated. Use channels_meta instead.
        channel_colors (Sequence[str] | None): Deprecated. Use channels_meta instead.
        channel_active (Sequence[bool] | None): Deprecated. Use channels_meta instead.
    """
    if xy_pixelsize is not None:
        logger.warning(
            "'xy_pixelsize' is deprecated and will be removed in ngio=0.6. "
            "Please use 'pixelsize' instead."
        )
        pixelsize = xy_pixelsize
    if xy_scaling_factor is not None or z_scaling_factor is not None:
        logger.warning(
            "'xy_scaling_factor' and 'z_scaling_factor' are deprecated and will be "
            "removed in ngio=0.6. Please use 'scaling_factors' instead."
        )
        xy_scaling_factor_ = xy_scaling_factor or 2.0
        z_scaling_factor_ = z_scaling_factor or 1.0
        if len(shape) == 2:
            scaling_factors = (xy_scaling_factor_, xy_scaling_factor_)
        else:
            zyx_factors = (z_scaling_factor_, xy_scaling_factor_, xy_scaling_factor_)
            scaling_factors = (1.0,) * (len(shape) - 3) + zyx_factors

    if channel_labels is not None:
        logger.warning(
            "'channel_labels' is deprecated and will be removed in ngio=0.6. "
            "Please use 'channels_meta' instead."
        )
        channels_meta = channel_labels

    if channel_wavelengths is not None:
        logger.warning(
            "'channel_wavelengths' is deprecated and will be removed in ngio=0.6. "
            "Please use 'channels_meta' instead."
        )
    if channel_colors is not None:
        logger.warning(
            "'channel_colors' is deprecated and will be removed in ngio=0.6. "
            "Please use 'channels_meta' instead."
        )
    if channel_active is not None:
        logger.warning(
            "'channel_active' is deprecated and will be removed in ngio=0.6. "
            "Please use 'channels_meta' instead."
        )

    if pixelsize is None:
        raise NgioValueError("pixelsize must be provided.")

    handler, axes_setup = init_image_like(
        store=store,
        meta_type=NgioImageMeta,
        shape=shape,
        pixelsize=pixelsize,
        z_spacing=z_spacing,
        time_spacing=time_spacing,
        scaling_factors=scaling_factors,
        levels=levels,
        translation=translation,
        space_unit=space_unit,
        time_unit=time_unit,
        axes_names=axes_names,
        channels_meta=channels_meta,
        name=name,
        axes_setup=axes_setup,
        ngff_version=ngff_version,
        chunks=chunks,
        shards=shards,
        dtype=dtype,
        dimension_separator=dimension_separator,
        compressors=compressors,
        extra_array_kwargs=extra_array_kwargs,
        overwrite=overwrite,
    )

    ome_zarr = OmeZarrContainer(group_handler=handler, axes_setup=axes_setup)
    if (
        channel_labels is not None
        or channel_wavelengths is not None
        or channel_colors is not None
        or channel_active is not None
    ):
        # Deprecated way of setting channel metadata
        # we set it here for backward compatibility
        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,
    pixelsize: float | tuple[float, float] | None = None,
    z_spacing: float = 1.0,
    time_spacing: float = 1.0,
    scaling_factors: Sequence[float]
    | Literal["auto"] = "auto",
    levels: int | list[str] = 5,
    translation: Sequence[float] | None = None,
    space_unit: SpaceUnits = DefaultSpaceUnit,
    time_unit: TimeUnits = DefaultTimeUnit,
    axes_names: Sequence[str] | None = None,
    channels_meta: Sequence[str | Channel] | None = None,
    percentiles: tuple[float, float] = (0.1, 99.9),
    name: str | None = None,
    axes_setup: AxesSetup | None = None,
    ngff_version: NgffVersions = DefaultNgffVersion,
    chunks: ChunksLike = "auto",
    shards: ShardsLike | None = None,
    dimension_separator: Literal[".", "/"] = "/",
    compressors: CompressorLike = "auto",
    extra_array_kwargs: Mapping[str, Any] | None = None,
    overwrite: bool = False,
    xy_pixelsize: float | None = None,
    xy_scaling_factor: float | None = None,
    z_scaling_factor: float | None = None,
    channel_labels: list[str] | None = None,
    channel_wavelengths: list[str] | None = None,
    channel_colors: Sequence[str] | None = None,
    channel_active: Sequence[bool] | None = None,
) -> 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.

  • pixelsize (float | tuple[float, float] | None, default: None ) –

    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.

  • scaling_factors (Sequence[float] | Literal['auto'], default: 'auto' ) –

    The down-scaling factors for the pyramid levels. Defaults to "auto".

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

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

  • translation (Sequence[float] | None, default: None ) –

    The translation for each axis. at the highest resolution level. Defaults to None.

  • 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 (Sequence[str] | None, default: None ) –

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

  • channels_meta (Sequence[str | Channel] | None, default: None ) –

    The channels metadata. Defaults to None.

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

    The percentiles of the channels for computing display ranges. Defaults to (0.1, 99.9).

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

    The name of the image. Defaults to None.

  • axes_setup (AxesSetup | None, default: None ) –

    Axes setup to create ome-zarr with non-standard axes configurations. Defaults to None.

  • ngff_version (NgffVersions, default: DefaultNgffVersion ) –

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

  • chunks (ChunksLike, default: 'auto' ) –

    The chunk shape. Defaults to "auto".

  • shards (ShardsLike | None, default: None ) –

    The shard shape. Defaults to None.

  • dimension_separator (Literal['.', '/'], default: '/' ) –

    The separator to use for dimensions. Defaults to "/".

  • compressors (CompressorLike, default: 'auto' ) –

    The compressors to use. Defaults to "auto".

  • extra_array_kwargs (Mapping[str, Any] | None, default: None ) –

    Extra arguments to pass to the zarr array creation. Defaults to None.

  • overwrite (bool, default: False ) –

    Whether to overwrite an existing image. Defaults to False.

  • xy_pixelsize (float | None, default: None ) –

    Deprecated. Use pixelsize instead.

  • xy_scaling_factor (float | None, default: None ) –

    Deprecated. Use scaling_factors instead.

  • z_scaling_factor (float | None, default: None ) –

    Deprecated. Use scaling_factors instead.

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

    Deprecated. Use channels_meta instead.

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

    Deprecated. Use channels_meta instead.

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

    Deprecated. Use channels_meta instead.

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

    Deprecated. Use channels_meta instead.

Source code in ngio/images/_ome_zarr_container.py 
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
1336
1337
1338
1339
1340
1341
1342
1343
1344
1345
1346
1347
1348
1349
1350
1351
1352
1353
1354
1355
1356
1357
1358
1359
1360
1361
1362
1363
1364
1365
1366
1367
1368
1369
1370
1371
1372
1373
1374
1375
1376
1377
1378
1379
1380
1381
1382
1383
1384
1385
1386
1387
1388
1389
1390
1391
1392
1393
1394
1395
1396
1397
1398
1399
1400
1401
1402
1403
1404
def create_ome_zarr_from_array(
    store: StoreOrGroup,
    array: np.ndarray,
    pixelsize: float | tuple[float, float] | None = None,
    z_spacing: float = 1.0,
    time_spacing: float = 1.0,
    scaling_factors: Sequence[float] | Literal["auto"] = "auto",
    levels: int | list[str] = 5,
    translation: Sequence[float] | None = None,
    space_unit: SpaceUnits = DefaultSpaceUnit,
    time_unit: TimeUnits = DefaultTimeUnit,
    axes_names: Sequence[str] | None = None,
    channels_meta: Sequence[str | Channel] | None = None,
    percentiles: tuple[float, float] = (0.1, 99.9),
    name: str | None = None,
    axes_setup: AxesSetup | None = None,
    ngff_version: NgffVersions = DefaultNgffVersion,
    chunks: ChunksLike = "auto",
    shards: ShardsLike | None = None,
    dimension_separator: Literal[".", "/"] = "/",
    compressors: CompressorLike = "auto",
    extra_array_kwargs: Mapping[str, Any] | None = None,
    overwrite: bool = False,
    # Deprecated arguments
    xy_pixelsize: float | None = None,
    xy_scaling_factor: float | None = None,
    z_scaling_factor: float | None = None,
    channel_labels: list[str] | None = None,
    channel_wavelengths: list[str] | None = None,
    channel_colors: Sequence[str] | None = None,
    channel_active: Sequence[bool] | None = None,
) -> 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.
        pixelsize (float | tuple[float, float] | None): The pixel size in x and y
            dimensions.
        z_spacing (float): The spacing between z slices. Defaults to 1.0.
        time_spacing (float): The spacing between time points. Defaults to 1.0.
        scaling_factors (Sequence[float] | Literal["auto"]): The down-scaling factors
            for the pyramid levels. Defaults to "auto".
        levels (int | list[str]): The number of levels in the pyramid or a list of
            level names. Defaults to 5.
        translation (Sequence[float] | None): The translation for each axis.
            at the highest resolution level. Defaults to None.
        space_unit (SpaceUnits): The unit of space. Defaults to DefaultSpaceUnit.
        time_unit (TimeUnits): The unit of time. Defaults to DefaultTimeUnit.
        axes_names (Sequence[str] | None): The names of the axes. If None the
            canonical names are used. Defaults to None.
        channels_meta (Sequence[str | Channel] | None): The channels metadata.
            Defaults to None.
        percentiles (tuple[float, float]): The percentiles of the channels for
            computing display ranges. Defaults to (0.1, 99.9).
        name (str | None): The name of the image. Defaults to None.
        axes_setup (AxesSetup | None): Axes setup to create ome-zarr with
            non-standard axes configurations. Defaults to None.
        ngff_version (NgffVersions): The version of the OME-Zarr specification.
            Defaults to DefaultNgffVersion.
        chunks (ChunksLike): The chunk shape. Defaults to "auto".
        shards (ShardsLike | None): The shard shape. Defaults to None.
        dimension_separator (Literal[".", "/"]): The separator to use for
            dimensions. Defaults to "/".
        compressors (CompressorLike): The compressors to use. Defaults to "auto".
        extra_array_kwargs (Mapping[str, Any] | None): Extra arguments to pass to
            the zarr array creation. Defaults to None.
        overwrite (bool): Whether to overwrite an existing image. Defaults to False.
        xy_pixelsize (float | None): Deprecated. Use pixelsize instead.
        xy_scaling_factor (float | None): Deprecated. Use scaling_factors instead.
        z_scaling_factor (float | None): Deprecated. Use scaling_factors instead.
        channel_labels (list[str] | None): Deprecated. Use channels_meta instead.
        channel_wavelengths (list[str] | None): Deprecated. Use channels_meta instead.
        channel_colors (Sequence[str] | None): Deprecated. Use channels_meta instead.
        channel_active (Sequence[bool] | None): Deprecated. Use channels_meta instead.
    """
    if len(percentiles) != 2:
        raise NgioValueError(
            f"'percentiles' must be a tuple of two values. Got {percentiles}"
        )
    ome_zarr = create_empty_ome_zarr(
        store=store,
        shape=array.shape,
        pixelsize=pixelsize,
        z_spacing=z_spacing,
        time_spacing=time_spacing,
        scaling_factors=scaling_factors,
        levels=levels,
        translation=translation,
        space_unit=space_unit,
        time_unit=time_unit,
        axes_names=axes_names,
        channels_meta=channels_meta,
        name=name,
        axes_setup=axes_setup,
        ngff_version=ngff_version,
        chunks=chunks,
        shards=shards,
        dimension_separator=dimension_separator,
        compressors=compressors,
        extra_array_kwargs=extra_array_kwargs,
        overwrite=overwrite,
        xy_pixelsize=xy_pixelsize,
        xy_scaling_factor=xy_scaling_factor,
        z_scaling_factor=z_scaling_factor,
        channel_labels=channel_labels,
        channel_wavelengths=channel_wavelengths,
        channel_colors=channel_colors,
        channel_active=channel_active,
    )
    image = ome_zarr.get_image()
    image.set_array(array)
    image.consolidate()
    ome_zarr.set_channel_windows_with_percentiles(percentiles=percentiles)
    return ome_zarr

OmeZarrContainer Class

ngio.OmeZarrContainer 

OmeZarrContainer(
    group_handler: ZarrGroupHandler,
    table_container: TablesContainer | None = None,
    label_container: LabelsContainer | None = None,
    axes_setup: AxesSetup | 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:

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.

  • axes_setup (AxesSetup | None, default: None ) –

    Axes setup to load ome-zarr with non-standard axes configurations.

  • validate_paths (bool, default: False ) –

    Whether to validate the paths of the image multiscale

Source code in ngio/images/_ome_zarr_container.py 
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
def __init__(
    self,
    group_handler: ZarrGroupHandler,
    table_container: TablesContainer | None = None,
    label_container: LabelsContainer | None = None,
    axes_setup: AxesSetup | 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.
        axes_setup (AxesSetup | None): Axes setup to load ome-zarr with
            non-standard axes configurations.
        validate_paths (bool): Whether to validate the paths of the image multiscale
    """
    self._group_handler = group_handler
    self._images_container = ImagesContainer(
        self._group_handler, axes_setup=axes_setup
    )
    self._labels_container = label_container
    self._tables_container = table_container

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

images_container property 

images_container: ImagesContainer

Return the images container.

Returns:

labels_container property 

labels_container: LabelsContainer

Return the labels container.

tables_container property 

tables_container: TablesContainer

Return the tables container.

meta property 

meta: NgioImageMeta

Return the image metadata.

image_meta property 

image_meta: NgioImageMeta

Return the image metadata.

axes_setup property 

axes_setup: AxesSetup

Return the axes setup.

levels property 

levels: int

Return the number of levels in the image.

level_paths property 

level_paths: list[str]

Return the paths of the levels in the image.

levels_paths property 

levels_paths: list[str]

Deprecated: use 'level_paths' instead.

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 
295
296
297
298
299
300
301
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
    )

set_channel_meta 

set_channel_meta(
    channel_meta: ChannelsMeta | None = None,
    labels: Sequence[str | None] | int | None = None,
    wavelength_id: Sequence[str | None] | None = None,
    start: Sequence[float | None] | None = None,
    end: Sequence[float | None] | None = None,
    percentiles: tuple[float, float] | None = None,
    colors: Sequence[str | None] | None = None,
    active: Sequence[bool | None] | None = None,
    **omero_kwargs: dict,
) -> None

Create a ChannelsMeta object with the default unit.

Parameters:

  • channel_meta (ChannelsMeta | None, default: None ) –

    The channels metadata to set. If none, it will fall back to the deprecated parameters.

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

    Deprecated. The list of channels names in the image. If an integer is provided, the channels will be named "channel_i".

  • wavelength_id (Sequence[str | None], default: None ) –

    Deprecated. The wavelength ID of the channel. If None, the wavelength ID will be the same as the channel name.

  • start (Sequence[float | None], default: None ) –

    Deprecated. The start value for each channel. If None, the start value will be computed from the image.

  • end (Sequence[float | None], default: None ) –

    Deprecated. The end value for each channel. If None, the end value will be computed from the image.

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

    Deprecated. The start and end percentiles for each channel. If None, the percentiles will not be computed.

  • colors (Sequence[str | None], default: None ) –

    Deprecated. The list of colors for the channels. If None, the colors will be random.

  • active (Sequence[bool | None], default: None ) –

    Deprecated. Whether the channel should be shown by default.

  • omero_kwargs (dict, default: {} ) –

    Deprecated. Extra fields to store in the omero attributes.

Source code in ngio/images/_ome_zarr_container.py 
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
def set_channel_meta(
    self,
    channel_meta: ChannelsMeta | None = None,
    labels: Sequence[str | None] | int | None = None,
    wavelength_id: Sequence[str | None] | None = None,
    start: Sequence[float | None] | None = None,
    end: Sequence[float | None] | None = None,
    percentiles: tuple[float, float] | None = None,
    colors: Sequence[str | None] | None = None,
    active: Sequence[bool | None] | None = None,
    **omero_kwargs: dict,
) -> None:
    """Create a ChannelsMeta object with the default unit.

    Args:
        channel_meta (ChannelsMeta | None): The channels metadata to set.
            If none, it will fall back to the deprecated parameters.
        labels(Sequence[str | None] | int): Deprecated. The list of channels names
            in the image. If an integer is provided, the channels will
            be named "channel_i".
        wavelength_id(Sequence[str | None]): Deprecated. The wavelength ID of the
            channel. If None, the wavelength ID will be the same as
            the channel name.
        start(Sequence[float | None]): Deprecated. The start value for each channel.
            If None, the start value will be computed from the image.
        end(Sequence[float | None]): Deprecated. The end value for each channel.
            If None, the end value will be computed from the image.
        percentiles(tuple[float, float] | None): Deprecated. The start and end
            percentiles for each channel. If None, the percentiles will
            not be computed.
        colors(Sequence[str | None]): Deprecated. The list of colors for the
            channels. If None, the colors will be random.
        active (Sequence[bool | None]): Deprecated. Whether the channel should
            be shown by default.
        omero_kwargs(dict): Deprecated. Extra fields to store in the omero
            attributes.
    """
    self._images_container.set_channel_meta(
        channel_meta=channel_meta,
        labels=labels,
        wavelength_id=wavelength_id,
        start=start,
        end=end,
        percentiles=percentiles,
        colors=colors,
        active=active,
        **omero_kwargs,
    )

set_channel_labels 

set_channel_labels(labels: Sequence[str]) -> None

Update the labels of the channels.

Parameters:

  • labels (Sequence[str]) –

    The new labels for the channels.

Source code in ngio/images/_ome_zarr_container.py 
352
353
354
355
356
357
358
359
360
361
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)

set_channel_colors 

set_channel_colors(colors: Sequence[str]) -> None

Update the colors of the channels.

Parameters:

  • colors (Sequence[str]) –

    The new colors for the channels.

Source code in ngio/images/_ome_zarr_container.py 
363
364
365
366
367
368
369
370
371
372
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)

set_channel_percentiles 

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

Deprecated: Update the channel windows using percentiles.

Parameters:

  • start_percentile (float, default: 0.1 ) –

    The start percentile.

  • end_percentile (float, default: 99.9 ) –

    The end percentile.

Source code in ngio/images/_ome_zarr_container.py 
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
def set_channel_percentiles(
    self,
    start_percentile: float = 0.1,
    end_percentile: float = 99.9,
) -> None:
    """Deprecated: Update the channel windows using percentiles.

    Args:
        start_percentile (float): The start percentile.
        end_percentile (float): The end percentile.
    """
    logger.warning(
        "The 'set_channel_percentiles' method is deprecated and will be removed in "
        "ngio=0.6. Please use 'set_channel_windows_with_percentiles' instead."
    )
    self._images_container.set_channel_windows_with_percentiles(
        percentiles=(start_percentile, end_percentile)
    )

set_channel_windows 

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

Parameters:

  • starts_ends (Sequence[tuple[float, float]]) –

    The start and end values for each channel.

  • min_max (Sequence[tuple[float, float]] | None, default: None ) –

    The min and max values for each channel. If None, the min and max values will not be updated.

Source code in ngio/images/_ome_zarr_container.py 
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
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,
    )

set_channel_windows_with_percentiles 

set_channel_windows_with_percentiles(
    percentiles: tuple[float, float]
    | list[tuple[float, float]] = (0.1, 99.9),
) -> None

Update the channel windows using percentiles.

Parameters:

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

    The start and end percentiles for each channel. If a single tuple is provided, the same percentiles will be used for all channels.

Source code in ngio/images/_ome_zarr_container.py 
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
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
    )

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 
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
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.
    """
    if set_labels:
        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)
    self._images_container.set_axes_unit(space_unit=space_unit, time_unit=time_unit)

set_axes_names 

set_axes_names(axes_names: Sequence[str]) -> None

Set the axes names of the image.

Parameters:

  • axes_names (Sequence[str]) –

    The axes names of the image.

Source code in ngio/images/_ome_zarr_container.py 
449
450
451
452
453
454
455
456
457
458
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)

set_name 

set_name(name: str) -> None

Set the name of the image in the metadata.

This does not change the group name or any paths.

Parameters:

  • name (str) –

    The name of the image.

Source code in ngio/images/_ome_zarr_container.py 
460
461
462
463
464
465
466
467
468
469
470
471
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)

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 
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
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 | 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.

Parameters:

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

    The name of the masking label to use. If None, the masking table must be provided.

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

    The name of the masking table to use. If None, the masking label must be provided.

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

    The path to the image in the ome_zarr file. If None, the first level will be used.

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

    The pixel size of the image. This is only used if path is None.

  • 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 
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
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 (PixelSize | None): The pixel size of the image.
            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,
    )

derive_image 

derive_image(
    store: StoreOrGroup,
    ref_path: str | None = None,
    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,
    chunks: ChunksLike | None = None,
    shards: ShardsLike | None = None,
    dtype: str = "uint16",
    dimension_separator: Literal[".", "/"] = "/",
    compressors: CompressorLike = "auto",
    extra_array_kwargs: Mapping[str, Any] | None = None,
    overwrite: bool = False,
    copy_labels: bool = False,
    copy_tables: bool = False,
    labels: Sequence[str] | None = None,
    pixel_size: PixelSize | None = None,
) -> 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.

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 (Sequence[int] | None, default: None ) –

    The shape of the new image.

  • pixelsize (float | tuple[float, float] | None, default: None ) –

    The pixel size of the new image.

  • z_spacing (float | None, default: None ) –

    The z spacing of the new image.

  • time_spacing (float | None, default: None ) –

    The time spacing of the new image.

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

    The name of the new image.

  • translation (Sequence[float] | None, default: None ) –

    The translation for each axis at the highest resolution level. Defaults to None.

  • channels_policy (Literal['squeeze', 'same', 'singleton'] | int, default: 'same' ) –

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

    The channels metadata of the new image.

  • ngff_version (NgffVersions | None, default: None ) –

    The NGFF version to use.

  • chunks (ChunksLike | None, default: None ) –

    The chunk shape of the new image.

  • shards (ShardsLike | None, default: None ) –

    The shard shape of the new image.

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

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

  • dimension_separator (Literal['.', '/'], default: '/' ) –

    The separator to use for dimensions. Defaults to "/".

  • compressors (CompressorLike, default: 'auto' ) –

    The compressors to use. Defaults to "auto".

  • extra_array_kwargs (Mapping[str, Any] | None, default: None ) –

    Extra arguments to pass to the zarr array creation.

  • overwrite (bool, default: False ) –

    Whether to overwrite an existing image. Defaults to False.

  • copy_labels (bool, default: False ) –

    Whether to copy the labels from the current image. Defaults to False.

  • copy_tables (bool, default: False ) –

    Whether to copy the tables from the current image. Defaults to False.

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

    Deprecated. This argument is deprecated, please use channels_meta instead.

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

    Deprecated. The pixel size of the new image. This argument is deprecated, please use pixelsize, z_spacing, and time_spacing instead.

Returns:

Source code in ngio/images/_ome_zarr_container.py 
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
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 = "uint16",
    dimension_separator: Literal[".", "/"] = "/",
    compressors: CompressorLike = "auto",
    extra_array_kwargs: Mapping[str, Any] | None = None,
    overwrite: bool = False,
    # Copy from current image
    copy_labels: bool = False,
    copy_tables: bool = False,
    # Deprecated arguments
    labels: Sequence[str] | None = None,
    pixel_size: PixelSize | None = None,
) -> "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.
        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): The data type of the new image. Defaults to "uint16".
        dimension_separator (Literal[".", "/"]): The separator to use for
            dimensions. Defaults to "/".
        compressors (CompressorLike): The compressors to use. Defaults to "auto".
        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.
        labels (Sequence[str] | None): Deprecated. This argument is deprecated,
            please use channels_meta instead.
        pixel_size (PixelSize | None): Deprecated. The pixel size of the new image.
            This argument is deprecated, please use pixelsize, z_spacing,
            and time_spacing instead.

    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,
        labels=labels,
        pixel_size=pixel_size,
    )
    new_ome_zarr = OmeZarrContainer(
        group_handler=new_container._group_handler,
        validate_paths=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

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 
695
696
697
698
699
700
701
702
703
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,
    )

list_roi_tables 

list_roi_tables() -> list[str]

List all ROI tables in the image.

Source code in ngio/images/_ome_zarr_container.py 
705
706
707
708
709
710
711
712
713
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 
715
716
717
718
719
720
721
722
723
724
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 
726
727
728
729
730
731
732
733
734
735
736
737
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 
739
740
741
742
743
744
745
746
747
748
749
750
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 
752
753
754
755
756
757
758
759
760
761
762
763
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 
765
766
767
768
769
770
771
772
773
774
775
776
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 
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
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:
        logger.warning(
            "The 'check_type' argument is deprecated and will be removed in "
            "ngio=0.6. Please use 'get_table_as' instead or one of the "
            "type specific get_*table() methods."
        )
    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 
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
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 | None = "image",
) -> RoiTable

Compute the ROI table for an image.

Source code in ngio/images/_ome_zarr_container.py 
816
817
818
def build_image_roi_table(self, name: str | None = "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 
820
821
822
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 
824
825
826
827
828
829
830
831
832
833
834
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
    )

delete_table 

delete_table(name: str, missing_ok: bool = False) -> None

Delete a table from the group.

Parameters:

  • name (str) –

    The name of the table to delete.

  • missing_ok (bool, default: False ) –

    If True, do not raise an error if the table does not exist.

Source code in ngio/images/_ome_zarr_container.py 
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
def delete_table(self, name: str, missing_ok: bool = False) -> None:
    """Delete a table from the group.

    Args:
        name (str): The name of the table to delete.
        missing_ok (bool): If True, do not raise an error if the table does not
            exist.

    """
    table_container = self._get_tables_container(create_mode=False)
    if table_container is None and missing_ok:
        return
    if table_container is None:
        raise NgioValueError(
            f"No tables found in the image, cannot delete {name}. "
            "Set missing_ok=True to ignore this error."
        )
    table_container.delete(name=name, missing_ok=missing_ok)

list_labels 

list_labels() -> list[str]

List all labels in the image.

Source code in ngio/images/_ome_zarr_container.py 
855
856
857
858
859
860
def list_labels(self) -> list[str]:
    """List all labels in the image."""
    label_container = self._get_labels_container(create_mode=False)
    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 
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
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 | None = None,
    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 | None, default: None ) –

    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 
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
def get_masked_label(
    self,
    label_name: str,
    masking_label_name: str | None = None,
    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 | None): 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, masking_table = self._find_matching_masking_label(
        masking_label_name=masking_label_name,
        masking_table_name=masking_table_name,
        pixel_size=pixel_size,
    )
    return MaskedLabel(
        group_handler=label._group_handler,
        path=label.path,
        meta_handler=label.meta_handler,
        label=masking_label,
        masking_roi_table=masking_table,
    )

delete_label 

delete_label(name: str, missing_ok: bool = False) -> None

Delete a label from the group.

Parameters:

  • name (str) –

    The name of the label to delete.

  • missing_ok (bool, default: False ) –

    If True, do not raise an error if the label does not exist.

Source code in ngio/images/_ome_zarr_container.py 
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
def delete_label(self, name: str, missing_ok: bool = False) -> None:
    """Delete a label from the group.

    Args:
        name (str): The name of the label to delete.
        missing_ok (bool): If True, do not raise an error if the label does not
            exist.

    """
    label_container = self._get_labels_container(create_mode=False)
    if label_container is None and missing_ok:
        return
    if label_container is None:
        raise NgioValueError(
            f"No labels found in the image, cannot delete {name}. "
            "Set missing_ok=True to ignore this error."
        )
    label_container.delete(name=name, missing_ok=missing_ok)

derive_label 

derive_label(
    name: str,
    ref_image: Image | Label | None = None,
    shape: Sequence[int] | None = None,
    pixelsize: float | tuple[float, float] | None = None,
    z_spacing: float | None = None,
    time_spacing: float | None = None,
    translation: Sequence[float] | None = None,
    channels_policy: Literal["same", "squeeze", "singleton"]
    | int = "squeeze",
    ngff_version: NgffVersions | None = None,
    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,
    labels: Sequence[str] | None = None,
    pixel_size: PixelSize | None = None,
) -> Label

Derive a new label from an existing image or label.

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

Parameters:

  • name (str) –

    The name of the new label.

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

    The reference image to derive the new label from. If None, the first level image will be used.

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

    The shape of the new label.

  • pixelsize (float | tuple[float, float] | None, default: None ) –

    The pixel size of the new label.

  • z_spacing (float | None, default: None ) –

    The z spacing of the new label.

  • time_spacing (float | None, default: None ) –

    The time spacing of the new label.

  • translation (Sequence[float] | None, default: None ) –

    The translation for each axis at the highest resolution level. Defaults to None.

  • channels_policy (Literal['same', 'squeeze', 'singleton'] | int, default: 'squeeze' ) –

    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. Defaults to "squeeze".

  • ngff_version (NgffVersions | None, default: None ) –

    The NGFF version to use.

  • chunks (ChunksLike | None, default: None ) –

    The chunk shape of the new label.

  • shards (ShardsLike | None, default: None ) –

    The shard shape of the new label.

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

    The data type of the new label.

  • dimension_separator (Literal['.', '/'] | None, default: None ) –

    The separator to use for dimensions.

  • compressors (CompressorLike | None, default: None ) –

    The compressors to use.

  • extra_array_kwargs (Mapping[str, Any] | None, default: None ) –

    Extra arguments to pass to the zarr array creation.

  • overwrite (bool, default: False ) –

    Whether to overwrite an existing label. Defaults to False.

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

    Deprecated. This argument is deprecated, please use channels_meta instead.

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

    Deprecated. The pixel size of the new label. This argument is deprecated, please use pixelsize, z_spacing, and time_spacing instead.

Returns:

  • Label ( Label ) –

    The new derived label.

Source code in ngio/images/_ome_zarr_container.py 
 939
 940
 941
 942
 943
 944
 945
 946
 947
 948
 949
 950
 951
 952
 953
 954
 955
 956
 957
 958
 959
 960
 961
 962
 963
 964
 965
 966
 967
 968
 969
 970
 971
 972
 973
 974
 975
 976
 977
 978
 979
 980
 981
 982
 983
 984
 985
 986
 987
 988
 989
 990
 991
 992
 993
 994
 995
 996
 997
 998
 999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
def derive_label(
    self,
    name: str,
    ref_image: Image | Label | 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,
    translation: Sequence[float] | None = None,
    channels_policy: Literal["same", "squeeze", "singleton"] | int = "squeeze",
    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,
    # Deprecated arguments
    labels: Sequence[str] | None = None,
    pixel_size: PixelSize | None = None,
) -> "Label":
    """Derive a new label from an existing image or label.

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

    Args:
        name (str): The name of the new label.
        ref_image (Image | Label | None): The reference image to derive the new
            label from. If None, the first level image will be used.
        shape (Sequence[int] | None): The shape of the new label.
        pixelsize (float | tuple[float, float] | None): The pixel size of the new
            label.
        z_spacing (float | None): The z spacing of the new label.
        time_spacing (float | None): The time spacing of the new label.
        translation (Sequence[float] | None): The translation for each axis
            at the highest resolution level. Defaults to None.
        channels_policy (Literal["same", "squeeze", "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.
            Defaults to "squeeze".
        ngff_version (NgffVersions | None): The NGFF version to use.
        chunks (ChunksLike | None): The chunk shape of the new label.
        shards (ShardsLike | None): The shard shape of the new label.
        dtype (str | None): The data type of the new label.
        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 label. Defaults to False.
        labels (Sequence[str] | None): Deprecated. This argument is deprecated,
            please use channels_meta instead.
        pixel_size (PixelSize | None): Deprecated. The pixel size of the new label.
            This argument is deprecated, please use pixelsize, z_spacing,
            and time_spacing instead.

    Returns:
        Label: The new derived label.

    """
    if ref_image is None:
        ref_image = self.get_image()
    return self.labels_container.derive(
        name=name,
        ref_image=ref_image,
        shape=shape,
        pixelsize=pixelsize,
        z_spacing=z_spacing,
        time_spacing=time_spacing,
        translation=translation,
        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,
        labels=labels,
        pixel_size=pixel_size,
    )