ngff_zarr.to_multiscales

Module Contents

Functions

_ngff_image_scale_factors

_find_optimal_chunk_size

Find a chunk size that divides evenly into dim_size and is ideally divisible by min_divisor.

_large_image_serialization

_cache_2d_strips

Cache large 2D images in strips along the larger spatial dimension.

_cache_1d_segments

Cache large 1D images in segments along x.

to_multiscales

Generate multiple resolution scales for the OME-NGFF standard data model.

API

ngff_zarr.to_multiscales._ngff_image_scale_factors(ngff_image, min_length, out_chunks)
ngff_zarr.to_multiscales._find_optimal_chunk_size(first_chunk, dim_size, min_divisor=16)

Find a chunk size that divides evenly into dim_size and is ideally divisible by min_divisor.

The returned chunk size will:

  1. Divide evenly into dim_size (required for safe region writes)

  2. Be as close as possible to first_chunk

  3. Preferably be divisible by min_divisor for performance

ngff_zarr.to_multiscales._large_image_serialization(
image: ngff_zarr.ngff_image.NgffImage,
progress: ngff_zarr.rich_dask_progress.NgffProgress | ngff_zarr.rich_dask_progress.NgffProgressCallback | None,
)
ngff_zarr.to_multiscales._cache_2d_strips(data, dims, rechunks, cache_store, base_path, progress)

Cache large 2D images in strips along the larger spatial dimension.

This avoids constructing a massive dask rechunk graph for the full image by processing manageable strips and writing them incrementally to disk.

ngff_zarr.to_multiscales._cache_1d_segments(data, dims, rechunks, cache_store, base_path, progress)

Cache large 1D images in segments along x.

Handles the edge case of 1D data (only x dimension, possibly with c/t).

ngff_zarr.to_multiscales.to_multiscales(
data: ngff_zarr.ngff_image.NgffImage | numpy.typing.ArrayLike | collections.abc.MutableMapping | str | zarr.core.Array,
scale_factors: int | collections.abc.Sequence[dict[str, int] | int] = 128,
method: ngff_zarr.methods.Methods | None = None,
chunks: int | tuple[int, ...] | tuple[tuple[int, ...], ...] | collections.abc.Mapping[Any, None | int | tuple[int, ...]] | None = None,
progress: ngff_zarr.rich_dask_progress.NgffProgress | ngff_zarr.rich_dask_progress.NgffProgressCallback | None = None,
cache: bool | None = None,
orientation: str | collections.abc.Mapping[str, ngff_zarr.rfc4.AnatomicalOrientation] | None = None,
) → ngff_zarr.multiscales.NgffMultiscales

Generate multiple resolution scales for the OME-NGFF standard data model.

Parameters:

  • data (NgffImage, ArrayLike, ZarrArray, MutableMapping, str) – Multi-dimensional array that provides the image pixel values, or image pixel values + image metadata when an NgffImage.

  • scale_factors (int of minimum length, int per scale or dict of spatial dimension int's per scale) – If a single integer, scale factors in spatial dimensions will be increased by a factor of two until this minimum length is reached. If a list, integer scale factors to apply uniformly across all spatial dimensions or along individual spatial dimensions. Examples: 64 or [2, 4] or [{‘x’: 2, ‘y’: 4 }, {‘x’: 5, ‘y’: 10}] Scaling is constrained by size of chunks - we do not scale below the chunk size.

  • method (Methods, optional) – Specify the anti-aliasing method used to downsample the image. Default is ITKWASM_GAUSSIAN. See the Methods enum for all available options.

  • chunks (Dask array chunking specification, optional) – Specify the chunking used in each output scale. The default is 128 for 3D images and 256 for 2D images.

  • cache (bool, optional) – Cache intermediate results to disk to limit memory consumption. If None, the default, determine based on ngff_zarr.config.memory_target.

  • progress (NgffProgress, NgffProgressCallback) – Optional progress logger

  • orientation (str or mapping of str to AnatomicalOrientation, optional) – Anatomical orientation (RFC 4) for the spatial axes. Either a preset coordinate-system name ("LPS" or "RAS", case-insensitive) or a mapping of axis name to :class:AnatomicalOrientation. When provided, it takes precedence over any axes_orientations on the input image. Anatomical orientation is written to the output automatically whenever it is present; no separate opt-in is required.

Returns:

NgffImage for each resolution and NGFF multiscales metadata

Rtype :

NgffMultiscales