giatools.image_processor

class giatools.image_processor.ImageProcessor(*args: Image, **kwargs: Image)

Bases: object

Processes one or more images with the same shape and axes, and yields one or more output images of the same shape.

Raises:

ValueError – If no input images are provided, or if the input images do not have the same shape and axes.

create_output_image(key: Any, dtype: dtype) → Image

Create and return an output image with the given key and data type.

The output image will have the same shape, axes, and metadata as the input images. The metadata is copied.

Raises:

ValueError – If an output image with the given key already exists.

image0: Image

An input image that is used to determine the shape, axes, and metadata of the output images.

inputs: MappingProxyType

Dictionary of the input images, keyed by strings (keyword arguments) or integers (positional arguments).

outputs: Dict[Any, Image]

Dictionary of the output images with arbitrary keys.

process(joint_axes: str, output_dtype_hints: Dict[Any, Literal['binary', 'bool', 'float16', 'float32', 'float64', 'floating', 'preserve', 'preserve_floating']] | None = None) → Iterator[ProcessorIteration]

Iterate over all slices of the input images along the given axes, yielding ProcessorIteration objects that provide access to the corresponding sections of the input and output images.

The axes in the yielded image sections correspond exactly to the joint_axes parameter (in the given order).

The data written to the output images in each iteration is automatically normalized according to the policy specified for the respective output image via the output_dtype_hints mapping (dictionary of output keys to the respective policies; see apply_output_dtype_hint() for a list of possible values).

Note

This method requires Python 3.11 or later.

Example

>>> from giatools import Image, ImageProcessor
>>> image = Image.read('data/input4_uint8.png')
>>> print(image.axes, image.data.shape)
QTZYXC (1, 1, 1, 10, 10, 3)
>>>
>>> proc = ImageProcessor(image)
>>> for section in proc.process('XY'):
...     section['result'] = (
...         section[0].data > section[0].data.mean()
...     )
>>>
>>> import numpy as np
>>> expected_result = np.stack(
...     [
...         image.data[..., c] > image.data[..., c].mean()
...         for c in range(image.data.shape[-1])
...     ],
...     axis=-1,
... )
>>> print(
...     np.allclose(
...         proc.outputs['result'].data,
...         expected_result,
...     ),
...     proc.outputs['result'].metadata == image.metadata,
... )
True True
Raises:

  • RuntimeError – If Python version is less than 3.11.

  • ValueError – If joint_axes contains invalid axes (must be a non-empty subset of the image axes); or if output_dtype_hints contains invalid values.

class giatools.image_processor.ProcessorIteration(processor: ImageProcessor, input_sections: MappingProxyType, output_slice: Tuple[int | slice, ...], joint_axes: str, output_dtype_hints: MappingProxyType)

Bases: object

Represents a single iteration of an ImageProcessor, providing access to corresponding input and output image sections.

__getitem__(key: str | int) → Image

Get the input image section corresponding to the given key.

Raises:

  • KeyError – If no input image was passed in by keyword argument equal to the given key.

  • IndexError – If no input image was passed in by positional argument at the given position.

__setitem__(key: Any, data: ndarray | DaskArray)

Set the output image section corresponding to the given key.

joint_axes: str

The axes of the image sections in this iteration.

giatools.image_processor.apply_output_dtype_hint(base_image: Image, image: Image, dtype_hint: Literal['binary', 'bool', 'float16', 'float32', 'float64', 'floating', 'preserve', 'preserve_floating']) → Image

Convert the data type of the image according to the specified dtype_hint.

The image is not changed in place, a new image is returned (the data can be copied, but not necessarily). The dtype_hint parameter determines the policy for deriving the target dtype of the output image:

  • ‘binary’: Like ‘bool’, but convert to uint8 and use 0/255 labels instead of False/True. Using high-contrast labels facilitates visual inspection.

  • ‘bool’: Convert to boolean type. Note that bool-typed images cannot be written to some files (e.g., PNG) and ‘binary’ should be generally preferred to also facilitate visual inspection.

  • ‘float16’, ‘float32’, ‘float64’: Convert to the explicitly specified float type.

  • ‘floating’: Use the float type that the image already has, if applicable; otherwise, convert to float64.

  • ‘preserve’: Convert to the same dtype as the input image base_image.

  • ‘preserve_floating’: Use the float type that the image already has, if applicable; otherwise, convert to the float type of the input image base_image, if applicable; otherwise, convert to float64.

Raises:

ValueError – If dtype_hint is none of the above.