Skip to content

Czi Image Stack

Source

Image stack implementation for CZI files.

CziImageStack

A class for extracting patches from an image stack that is stored as a CZI file.

Parameters:

  • data_path (str or Path) –

    Path to the CZI file.

  • scene (int, default: None ) –

    Index of the scene to extract.

    A single CZI file can contain multiple "scenes", which are stored alongside each other at different coordinates in the image plane, often separated by empty space. Specifying this argument will read only the single scene with that index from the file. Think of it as cropping the CZI file to the region where that scene is located.

    If no scene index is specified, the entire image will be read. In case it contains multiple scenes, they will all be present in the resulting image. This is usually not desirable due to the empty space between them. In general, only omit this argument or set it to None if you know that your CZI file does not contain any scenes.

    The static function 🇵🇾meth:get_bounding_rectangles can be used to find out how many scenes a given file contains and what their bounding rectangles are.

    The scene can also be provided as part of data_path by appending an "@" followed by the scene index to the filename.

  • depth_axis (('none', 'Z', 'T'), default: "none" ) –

    Which axis to use as depth-axis for providing 3-D patches.

    • "none": Only provide 2-D patches. If a Z or T dimension is present in the data, they will be combined into the sample dimension S.
    • "Z": Use the Z-axis as depth-axis. If a T axis is present as well, it will be merged into the sample dimensions S.
    • "T": Use the T-axis as depth-axis. If a Z axis is present as well, it will be merged into the sample dimensions S.

Attributes:

  • source (Path) –

    Path to the CZI file, including the scene index if specified.

  • data_path (Path) –

    Path to the CZI file without scene index.

  • scene (int or None) –

    Index of the scene to extract, or None if not specified.

  • data_shape (Sequence[int]) –

    The shape of the data in the order (SC(Z)YX).

  • axes (str) –

    The axes in the CZI file corresponding to the dimensions in data_shape. The following values can occur:

    • "SCZYX" for 3-D volumes if depth_axis is "Z".
    • "SCTYX" for time-series if depth_axis is "T".
    • "SCYX" if depth_axis is "none".

    The axis S (sample) is the only one not mapping one-to-one to an axis in the CZI file but combines all remaining axes present in the file into one.

Examples:

Create an image stack for the first scene in a CZI file:

>>> stack = CziImageStack("path/to/file.czi", scene=0)

Alternatively, the scene index can also be provided as part of the filename. This is mainly intended for re-creating an image stack from the source property:

>>> stack = CziImageStack("path/to/file.czi@0")
>>> stack2 = CziImageStack(stack.source)

If the CZI file contains a third dimension (Z or T) and you want to perform 3-D denoising, you need to explicitly set depth_axis to "Z" or "T":

>>> stack_2d = CziImageStack("path/to/file.czi", scene=0)
>>> stack_2d.axes, stack_2d.data_shape
('SCYX', [40, 1, 512, 512])
>>> stack_3d = CziImageStack(
...     "path/to/file.czi", scene=0, depth_axis="Z"
... )
>>> stack_3d.axes, stack_3d.data_shape
('SCZYX', [4, 1, 10, 512, 512])

original_axes property

Original axes of the data.

Returns:

  • str –

    Axis string before merging dimensions into the sample axis S.

original_data_shape property

Original shape of the data.

Returns:

  • tuple[int, ...] –

    Shape before merging dimensions into the sample axis S.

source property

Path to the CZI file, including scene index in the filename if set.

Returns:

  • Path –

    Path that can be used to recreate this image stack (e.g. file.czi@0).

__del__()

Close the CZI file handle when the instance is destroyed.

__getstate__()

Return state for pickling, excluding the non-picklable CZI reader.

Returns:

  • dict[str, Any] –

    Instance dictionary without the CZI reader.

__init__(data_path, scene=None, depth_axis='none')

Constructor.

As a CZI file can contain multiple scenes, the scene to extract can be specified either as a separate argument scene or as part of the data_path by appending an "@" followed by the scene index to the filename (e.g. file.czi@0 for scene 0). If both are provided, a ValueError is raised.

Both T and Z axes can be used as depth axes for 3D denoising, other non spatial axes will be merged into the sample dimension S.

Parameters:

  • data_path (str or Path) –

    Path to the CZI file (optionally with @scene suffix).

  • scene (int or None, default: None ) –

    Scene index to load; see class docstring. Omit if encoded in path.

  • depth_axis (('none', 'Z', 'T'), default: "none" ) –

    Axis to use as depth for 3D patches.

Raises:

  • ImportError –

    If the pylibCZIrw package is not installed.

  • ValueError –

    If the scene index is specified both in the filename and as an argument.

__setstate__(state)

Restore state after unpickling and reopen the CZI file.

Parameters:

  • state (dict[str, Any]) –

    State from __getstate__.

Returns:

  • None –

    No return value; instance state is updated in place.

extract_patch(sample_idx, channels, coords, patch_size)

Extract a patch for a given sample and channels within the image stack.

Parameters:

  • sample_idx (int) –

    Sample index.

  • channels (sequence of int or None) –

    Channel indices to extract. If None, all channels will be extracted.

  • coords (sequence of int) –

    Spatial coordinates of the top-left corner of the patch.

  • patch_size (sequence of int) –

    Size of the patch in each spatial dimension.

Returns:

  • ndarray –

    A patch of the image data from a particular sample with dimensions C(Z)YX.

get_bounding_rectangles(czi) classmethod

Get the bounding rectangles of all scenes in a CZI file.

Parameters:

  • czi (Path or str or CziReader) –

    Path to the CZI file or an already opened file as CziReader object.

Returns:

  • dict[int | None, Rectangle] –

    A dictionary mapping scene indices to their bounding rectangles in the format (x, y, w, h). If no scenes are present in the CZI file, the returned dictionary will have only one entry with key None, whose bounding rectangle covers the entire image.