API

class ryomen.Slicer(image, crop_size, overlap, batch_size=1, pad=True, output_transform=<function Slicer.<lambda>>, collate=<function default_collate>, progress_bar=<function default_progress_bar>)

Ryomen is a generic cropping utility for separating up large microscopy images into smaller, equal sized, sub crops.

Ryomen works with any generic array type, as long as it implements the following methods: __getitem__, __setitem__, __iter__, and __size__. Furthermore, the array type must support either a flip method, or support negative indexing, and must implement a parameter shape. These criteria basically fit all numpy-like arrays. Tested array libraries include zarr, numpy, and pytorch.

Basic Usage:

>>> import numpy as np
>>> from ryomen import Slicer
>>> image = np.random.randn((3, 100, 100, 100))  # A large, 3D array with a color channel
>>> # image.shape is [B, C, X, Y, Z]
>>> crop_size, overlap = (10, 10, 10), (2, 2, 2)  # we want to crop on the spatial dimensions!
>>>
>>> for crop, index = Slicer(image, crop_size, overlap)
>>>     print(crop.shape)  # [3, 10, 10, 10]

The function also allows for batching and a custom colate function, usefull if you want to use this for machine learning evaluation. The default behavior is to agregate all batched images into a list. A custom collate function should accept a list of arrays and may return anything.

The default behavior looks like this…

>>> import numpy as np
>>> from ryomen import Slicer
>>> image = np.random.randn((3, 100, 100, 100))  # A large, 3D array with a color channel
>>> crop_size, overlap = (10, 10, 10), (2, 2, 2)  # we want to crop on the spatial dimensions!
>>> for crop, index = Slicer(maige, crop_size, overlap, batch_size=8)
>>>     print(len(crop))  # 8

Now with a custom collate function…

>>> import numpy as np
>>> from ryomen import Slicer
>>> image = np.random.randn((3, 100, 100, 100))  # A large, 3D array with a color channel
>>> crop_size, overlap = (10, 10, 10), (2, 2, 2)  # we want to crop on the spatial dimensions!
>>> collate = lambda x: np.stack(x, axis=0)
>>> for crop, index = Slicer(image, crop_size, overlap, batch_size=8, collate=collate)
>>>     print(crop.shape)  # [8, 3, 10, 10, 10]

This utility also allows for the evaluation of arbitrary functions on each crop prior to collating. This is useful if you want to normalize each crop. This function should accept an ArrayLike and return an ArrayLike

>>> import numpy as np
>>> from ryomen import Slicer
>>> image = np.random.randn((3, 100, 100, 100))  # A large, 3D array with a color channel
>>> crop_size, overlap = (10, 10, 10), (2, 2, 2)  # we want to crop on the spatial dimensions!
>>> collate = lambda x: np.stack(x, axis=0)
>>> normalize = lambda x: x / 255 * 2 - 1
>>> for crop, index = Slicer(image, crop_size, overlap, batch_size=8, collate=collate, output_transform=normalize)
>>>     print(crop.shape)  # [8, 3, 10, 10, 10]

Parameters:

• image (TensorLike) – N Dimensional Array of any type

• crop_size (Sequence[int]) – Tuple ints for cropping dimensions

• overlap (Sequence[int]) – Tuple of ints for the overlap between crops

• batch_size (int) – batch size of crops. Allows for returning multiple crops in one iteration

• pad (bool) – pads the image by reflection if true. Only supported if input tensor implements a flip method.

• output_transform (Callable[[TensorLike], TensorLike]) – function to apply to each crop before returning

• collate (Callable[[Sequence[TensorLike]], Union[TensorLike, Sequence[TensorLike]]]) – function to collate images, the default behavior is to return a list of crops

• progress_bar (Callable[[Union[Iterator, Generator]], Any]) – function which wraps the iteration and displays a progress bar. (e.g. tqdm)

__iter__()

Creates a generator which yields a TensorLike Crop, Source Indices, and Destination Indices.

Return type:

Generator[Tuple[Union[TensorLike, Sequence[TensorLike]], Union[Tuple[Union[EllipsisType, slice], ...], Sequence[Tuple[Union[EllipsisType, slice], ...]]], Union[Tuple[Union[EllipsisType, slice], ...], Sequence[Tuple[Union[EllipsisType, slice], ...]]]], None, None]

__len__()

Returns the number of slices this iterator will iterate over

class ryomen.TensorLike

Any array type that matches this signature will work with ryomen. Tested include: zarr, numpy, pytorch…

__getitem__(item)

Required Method

Return type:

TensorLike

__iter__()

Required Method

Return type:

Iterator

__setitem__(index, item)

Required Method

Return type:

TensorLike

flip(dim)

not necessary if tensor supports negative strides

Return type:

TensorLike

size()

Required Method

Return type:

Sequence[int]