aicspylibczi package

Submodules

aicspylibczi.CziFile module

class aicspylibczi.CziFile.CziFile(czi_filename: str | Path | bytes | BinaryIO | BufferedIOBase | BufferedReader, verbose: bool = False)

Bases: object

Zeiss CZI file object.

Args:

czi_filename (str): Filename of czifile to access.

Kwargs:

verbose (bool): Print information and times during czi file access.

Note

Utilizes compiled wrapper to libCZI for accessing the CZI file.

ZISRAW_DIMS = {'B', 'C', 'H', 'I', 'R', 'S', 'T', 'V', 'Z'}

static convert_to_buffer(file: str | Path | bytes | BinaryIO | BufferedIOBase | BufferedReader) → BinaryIO | ndarray

property dims

Get the dimensions present the binary data (not the metadata) M, Y, X, A are included for completeness but can not be used as constraints.

Returns:

A string containing Dimensions letters present, ie “BSTZYX”

Return type:

str

Note

Dimensions defined in libCZI -

V - view H - phase I - illumination S - scene R - rotation T - time C - channel Z - z plane (height)

Dimensions added by aicspylibczi -

M - mosaic tile, mosaic images only Y - image height X - image width A - samples, BGR/RGB images only

get_all_mosaic_scene_bounding_boxes()

Get the scene (subblocks) bounding boxes (pyramid=0) for the specified dimensions. For mosaic files.

Returns:

A dictionary with keys of type Int and values of type BBox. The integer key is the Scene Index. For a value, ie bbox, of type BBox:

bbox.x = The x coordinate of the upper left corner of the bounding box. bbox.y = The y coordinate of the upper left corner of the bounding box. bbox.w = The width of the bounding box. bbox.h = The height of the bounding box.

Return type:

dict[int, bbox]

get_all_mosaic_tile_bounding_boxes(**kwargs)

Get one or more tiles (subblocks) bounding boxes (pyramid=0) for the specified dimensions. For mosaic files.

Parameters:

kwargs – The keywords below allow you to specify the dimensions that you wish to match. If you under-specify the constraints you can easily end up with a massive image stack.

Z = 1 # The Z-dimension. C = 2 # The C-dimension (“channel”). T = 3 # The T-dimension (“time”). R = 4 # The R-dimension (“rotation”). S = 5 # The S-dimension (“scene”). I = 6 # The I-dimension (“illumination”). H = 7 # The H-dimension (“phase”). V = 8 # The V-dimension (“view”).

Returns:

A dictionary with keys of type TileInfo and values of type BBox. For a key, ie tle, of type Tile:

tle.dimension_coordinates = A dictionary of Dimensions for the tile

For a value, ie bbox, of type BBox:

bbox.x = The x coordinate of the upper left corner of the bounding box. bbox.y = The y coordinate of the upper left corner of the bounding box. bbox.w = The width of the bounding box. bbox.h = The height of the bounding box.

Return type:

dict[tile_info, bbox]

get_all_scene_bounding_boxes()

Get one or more tiles (subblocks) bounding boxes (pyramid=0) for the specified dimensions. For non-mosaic files.

Returns:

A dictionary with keys of type Int and values of type BBox. The integer key is the Scene Index. For a value, ie bbox, of type BBox:

bbox.x = The x coordinate of the upper left corner of the bounding box. bbox.y = The y coordinate of the upper left corner of the bounding box. bbox.w = The width of the bounding box. bbox.h = The height of the bounding box.

Return type:

dict[int, bbox]

get_all_tile_bounding_boxes(**kwargs)

Get one or more tiles (subblocks) bounding boxes (pyramid=0) for the specified dimensions. For non-mosaic files.

Parameters:

kwargs – The keywords below allow you to specify the dimensions that you wish to match. If you under-specify the constraints you can easily end up with a massive image stack.

Z = 1 # The Z-dimension. C = 2 # The C-dimension (“channel”). T = 3 # The T-dimension (“time”). R = 4 # The R-dimension (“rotation”). S = 5 # The S-dimension (“scene”). I = 6 # The I-dimension (“illumination”). H = 7 # The H-dimension (“phase”). V = 8 # The V-dimension (“view”).

Returns:

A dictionary with keys of type TileInfo and values of type BBox. For a key, ie tile, of type Tile:

tile.dimension_coordinates = A dictionary of Dimensions for the tile

For a value, ie bbox, of type BBox:

bbox.x = The x coordinate of the upper left corner of the bounding box. bbox.y = The y coordinate of the upper left corner of the bounding box. bbox.w = The width of the bounding box. bbox.h = The height of the bounding box.

Return type:

dict[tile_info, bbox]

get_dims_shape()

Get the dimensions for the opened file from the binary data (not the metadata)

Returns:

A list of dictionaries containing Dimension / depth. If the shape is consistent across Scenes then the list will have only one Dictionary. If the shape is inconsistent the the list will have a dictionary

for each Scene. A consistently shaped file with 3 scenes, 7 time-points

and 4 Z slices containing images of (h,w) = (325, 475) would return [

{‘S’: (0, 3), ‘T’: (0,7), ‘X’: (0, 475), ‘Y’: (0, 325), ‘Z’: (0, 4)}

]. The result for a similarly shaped file but with different number of time-points per scene would yield [

{‘S’: (0, 1), ‘T’: (0,8), ‘X’: (0, 475), ‘Y’: (0, 325), ‘Z’: (0, 4)}, {‘S’: (1, 2), ‘T’: (0,6), ‘X’: (0, 475), ‘Y’: (0, 325), ‘Z’: (0, 4)}, {‘S’: (2, 3), ‘T’: (0,7), ‘X’: (0, 475), ‘Y’: (0, 325), ‘Z’: (0, 4)}

] For the same initial file but with an RGB pixel type the result would be [

{‘S’: (0, 3), ‘T’: (0,7), ‘X’: (0, 475), ‘Y’: (0, 325), ‘Z’: (0, 4), ‘A’: (0,3)}

].

Return type:

list[dict]

get_mosaic_bounding_box()

Get the bounding box for the entire mosaic image.

Returns:

A Bounding Box, bbox, of type BBox. bbox.x = The x coordinate of the upper left corner of the bounding box. bbox.y = The y coordinate of the upper left corner of the bounding box. bbox.w = The width of the bounding box. bbox.h = The height of the bounding box.

Return type:

bbox

get_mosaic_scene_bounding_box(index: int = 0)

Get the bounding box (pyramid=0) for the specified scene. For mosaic files. This is not equivalent to the results from get_mosaic_tile_bounding_box.

Parameters:

index – the scene index, if omitted it defaults to Zero

Returns:

A Bounding Box, bbox, of type BBox. bbox.x = The x coordinate of the upper left corner of the bounding box. bbox.y = The y coordinate of the upper left corner of the bounding box. bbox.w = The width of the bounding box. bbox.h = The height of the bounding box.

Return type:

bbox

get_mosaic_tile_bounding_box(**kwargs)

Get a single tile (subblock) bounding box (pyramid=0) for the specified dimensions. For mosaic files.

Parameters:

kwargs – The keywords below allow you to specify the dimensions that you wish to match. If you under-specify the constraints you can easily end up with a massive image stack.

Z = 1 # The Z-dimension. C = 2 # The C-dimension (“channel”). T = 3 # The T-dimension (“time”). R = 4 # The R-dimension (“rotation”). S = 5 # The S-dimension (“scene”). I = 6 # The I-dimension (“illumination”). H = 7 # The H-dimension (“phase”). V = 8 # The V-dimension (“view”). M = 10 # The M_index, this is only valid for Mosaic files!

Returns:

A Bounding Box, bbox, of type BBox. bbox.x = The x coordinate of the upper left corner of the bounding box. bbox.y = The y coordinate of the upper left corner of the bounding box. bbox.w = The width of the bounding box. bbox.h = The height of the bounding box.

Return type:

bbox

get_scene_bounding_box(index: int = 0)

Get the bounding box (pyramid=0) for the specified scene. For non-mosaic files. This should be equivalent to the results from get_tile_bounding_box but requiring only one arguments.

Parameters:

index – the scene index, if omitted it defaults to Zero

Returns:

A Bounding Box, bbox, of type BBox. bbox.x = The x coordinate of the upper left corner of the bounding box. bbox.y = The y coordinate of the upper left corner of the bounding box. bbox.w = The width of the bounding box. bbox.h = The height of the bounding box.

Return type:

bbox

get_tile_bounding_box(**kwargs)

Get a single tile (subblock) bounding box (pyramid=0) for the specified dimensions. For non-mosaic files.

Parameters:

kwargs – The keywords below allow you to specify the dimensions that you wish to match. If you under-specify the constraints you can easily end up with a massive image stack.

Z = 1 # The Z-dimension. C = 2 # The C-dimension (“channel”). T = 3 # The T-dimension (“time”). R = 4 # The R-dimension (“rotation”). S = 5 # The S-dimension (“scene”). I = 6 # The I-dimension (“illumination”). H = 7 # The H-dimension (“phase”). V = 8 # The V-dimension (“view”).

Returns:

A Bounding Box, bbox, of type BBox. bbox.x = The x coordinate of the upper left corner of the bounding box. bbox.y = The y coordinate of the upper left corner of the bounding box. bbox.w = The width of the bounding box. bbox.h = The height of the bounding box.

Return type:

bbox

is_mosaic()

Test if the loaded file is a mosaic file

Returns:

True | False ie is this a mosaic file

Return type:

bool

property meta

Extract the metadata block from the czi file.

Returns:

The root element of the metadata tree

Return type:

xml.etree.ElementTree.Element

property pixel_type

The pixelType of the images. If the pixelType is different in the different subblocks it returns Invalid.

Return type:

A string containing the name of the type of each pixel. If inconsistent it returns invalid.

read_image(**kwargs)

Read the subblocks in the CZI file and for any subblocks that match all the constraints in kwargs return that data. This allows you to select channels/scenes/time-points/Z-slices etc. Note if passed a BGR image then the dims of the object will returned by this function and the implicit BGR will be expanded into an A dimension. A is samples per pixel and will only be present for BGR images. This is logically more consistent than mixing the samples into the channels as was done before aicspylibczi-3.0.0.

Parameters:

**kwargs – The keywords below allow you to specify the dimensions that you wish to match. If you under-specify the constraints you can easily end up with a massive image stack.

Z = 1 # The Z-dimension. C = 2 # The C-dimension (“channel”). T = 3 # The T-dimension (“time”). R = 4 # The R-dimension (“rotation”). S = 5 # The S-dimension (“scene”). I = 6 # The I-dimension (“illumination”). H = 7 # The H-dimension (“phase”). V = 8 # The V-dimension (“view”). M = 10 # The M_index, this is only valid for Mosaic files!

Specify the number of cores to use for multithreading with cores.

cores = 3 # use 3 cores for threaded reading of the image.

Returns:

a tuple of (numpy.ndarray, a list of (Dimension, size)) the second element of the tuple is to make sure the numpy.ndarray is interpretable. An example of the list is [(‘S’, 1), (‘T’, 1), (‘C’, 2), (‘Z’, 25), (‘Y’, 1024), (‘X’, 1024)] so if you probed the numpy.ndarray with .shape you would get (1, 1, 2, 25, 1024, 1024).

Return type:

(numpy.ndarray, [Dimension, Size])

Notes

The M Dimension is a representation of the m_index used inside libCZI. Unfortunately this can be sparsely packed for a given selection which causes problems when indexing memory. Consequently the M Dimension may not match the m_index that is being used in libCZI or displayed in Zeiss’ Zen software.

read_mosaic(region: Tuple | None = None, scale_factor: float = 1.0, background_color: Tuple | None = None, **kwargs)

Reads a mosaic file and returns an image corresponding to the specified dimensions. If the file is more than a 2D sheet of pixels, meaning only one channel, z-slice, time-index, etc then the kwargs must specify the dimension with more than one possible value.

Example: Read in the C=1 channel of a mosaic file at 1/10th the size

czi = CziFile(filename) img = czi.read_mosaic(scale_factor=0.1, C=1)

Parameters:

• region – A bounding box specifying the extraction box (x0, y0, width, height) specified in pixels

• scale_factor – The amount to scale the data by, 0.1 would mean an image 1/10 the height and width of native, if you get distortions it seems to be due to a bug in Zeiss’s libCZI I’m trying to track it down but for now if you use scale_factor=1.0 it should work properly.

• background_color – Background color used when pixel is outside of a sublock. If omitted, it defaults to black (r,g,b)=(0.0,0.0,0.0). Each color component is a float value between 0.0 and 1.0.

• kwargs – The keywords below allow you to specify the dimension plane that constrains the 2D data. If the constraints are underspecified the function will fail.

  Z = 1   # The Z-dimension.
  C = 2   # The C-dimension ("channel").
  T = 3   # The T-dimension ("time").
  R = 4   # The R-dimension ("rotation").
  S = 5   # The S-dimension ("scene").
  I = 6   # The I-dimension ("illumination").
  H = 7   # The H-dimension ("phase").
  V = 8   # The V-dimension ("view").
  

Returns:

(1, height, width)

Return type:

numpy.ndarray

read_subblock_metadata(unified_xml: bool = False, **kwargs)

Read the subblock specific metadata, ie time subblock was acquired / position at acquisition time etc.

Parameters:

• unified_xml (bool) – If True return a single unified xml tree containing the requested subblock. If False return a list of tuples (dims, xml)

• kwargs – The keywords below allow you to specify the dimensions that you wish to match. If you under-specify the constraints you can easily end up with a massive image stack.

  Z = 1 # The Z-dimension. C = 2 # The C-dimension (“channel”). T = 3 # The T-dimension (“time”). R = 4 # The R-dimension (“rotation”). S = 5 # The S-dimension (“scene”). I = 6 # The I-dimension (“illumination”). H = 7 # The H-dimension (“phase”). V = 8 # The V-dimension (“view”). M = 10 # The M_index, this is only valid for Mosaic files!

Returns:

• [(dict, str)] if unified_xml is False – an array of tuples containing a dimension dictionary and the corresponding subblock metadata

• xml.etree.ElementTree.Element if unified_xml is True – an xml document containing the requested subblock metadata.

property shape_is_consistent

Query if the file shape is consistent across scenes.

Returns:

true if consistent, false the scenes have different dimension shapes

Return type:

bool

property size

This returns the Size of each dimension in the dims string. So if S had valid indexes of [0, 1, 2, 3, 4] the returned tuple would have a value of 5 in the same position as the S occurs in the dims string.

Returns:

a tuple of dimension sizes. If the data has inconsistent shape the list will only contain -1 values and the user needs to use dims_shape() to get the indexes.

Return type:

tuple

aicspylibczi.types module

Module contents

class aicspylibczi.CziFile(czi_filename: str | Path | bytes | BinaryIO | BufferedIOBase | BufferedReader, verbose: bool = False)

Bases: object

Zeiss CZI file object.

Args:

czi_filename (str): Filename of czifile to access.

Kwargs:

verbose (bool): Print information and times during czi file access.

Note

Utilizes compiled wrapper to libCZI for accessing the CZI file.

ZISRAW_DIMS = {'B', 'C', 'H', 'I', 'R', 'S', 'T', 'V', 'Z'}

static convert_to_buffer(file: str | Path | bytes | BinaryIO | BufferedIOBase | BufferedReader) → BinaryIO | ndarray

property dims

Get the dimensions present the binary data (not the metadata) M, Y, X, A are included for completeness but can not be used as constraints.

Returns:

A string containing Dimensions letters present, ie “BSTZYX”

Return type:

str

Note

Dimensions defined in libCZI -

V - view H - phase I - illumination S - scene R - rotation T - time C - channel Z - z plane (height)

Dimensions added by aicspylibczi -

M - mosaic tile, mosaic images only Y - image height X - image width A - samples, BGR/RGB images only

get_all_mosaic_scene_bounding_boxes()

Get the scene (subblocks) bounding boxes (pyramid=0) for the specified dimensions. For mosaic files.

Returns:

A dictionary with keys of type Int and values of type BBox. The integer key is the Scene Index. For a value, ie bbox, of type BBox:

bbox.x = The x coordinate of the upper left corner of the bounding box. bbox.y = The y coordinate of the upper left corner of the bounding box. bbox.w = The width of the bounding box. bbox.h = The height of the bounding box.

Return type:

dict[int, bbox]

get_all_mosaic_tile_bounding_boxes(**kwargs)

Get one or more tiles (subblocks) bounding boxes (pyramid=0) for the specified dimensions. For mosaic files.

Parameters:

kwargs – The keywords below allow you to specify the dimensions that you wish to match. If you under-specify the constraints you can easily end up with a massive image stack.

Z = 1 # The Z-dimension. C = 2 # The C-dimension (“channel”). T = 3 # The T-dimension (“time”). R = 4 # The R-dimension (“rotation”). S = 5 # The S-dimension (“scene”). I = 6 # The I-dimension (“illumination”). H = 7 # The H-dimension (“phase”). V = 8 # The V-dimension (“view”).

Returns:

A dictionary with keys of type TileInfo and values of type BBox. For a key, ie tle, of type Tile:

tle.dimension_coordinates = A dictionary of Dimensions for the tile

For a value, ie bbox, of type BBox:

bbox.x = The x coordinate of the upper left corner of the bounding box. bbox.y = The y coordinate of the upper left corner of the bounding box. bbox.w = The width of the bounding box. bbox.h = The height of the bounding box.

Return type:

dict[tile_info, bbox]

get_all_scene_bounding_boxes()

Get one or more tiles (subblocks) bounding boxes (pyramid=0) for the specified dimensions. For non-mosaic files.

Returns:

A dictionary with keys of type Int and values of type BBox. The integer key is the Scene Index. For a value, ie bbox, of type BBox:

bbox.x = The x coordinate of the upper left corner of the bounding box. bbox.y = The y coordinate of the upper left corner of the bounding box. bbox.w = The width of the bounding box. bbox.h = The height of the bounding box.

Return type:

dict[int, bbox]

get_all_tile_bounding_boxes(**kwargs)

Get one or more tiles (subblocks) bounding boxes (pyramid=0) for the specified dimensions. For non-mosaic files.

Parameters:

kwargs – The keywords below allow you to specify the dimensions that you wish to match. If you under-specify the constraints you can easily end up with a massive image stack.

Z = 1 # The Z-dimension. C = 2 # The C-dimension (“channel”). T = 3 # The T-dimension (“time”). R = 4 # The R-dimension (“rotation”). S = 5 # The S-dimension (“scene”). I = 6 # The I-dimension (“illumination”). H = 7 # The H-dimension (“phase”). V = 8 # The V-dimension (“view”).

Returns:

A dictionary with keys of type TileInfo and values of type BBox. For a key, ie tile, of type Tile:

tile.dimension_coordinates = A dictionary of Dimensions for the tile

For a value, ie bbox, of type BBox:

bbox.x = The x coordinate of the upper left corner of the bounding box. bbox.y = The y coordinate of the upper left corner of the bounding box. bbox.w = The width of the bounding box. bbox.h = The height of the bounding box.

Return type:

dict[tile_info, bbox]

get_dims_shape()

Get the dimensions for the opened file from the binary data (not the metadata)

Returns:

A list of dictionaries containing Dimension / depth. If the shape is consistent across Scenes then the list will have only one Dictionary. If the shape is inconsistent the the list will have a dictionary

for each Scene. A consistently shaped file with 3 scenes, 7 time-points

and 4 Z slices containing images of (h,w) = (325, 475) would return [

{‘S’: (0, 3), ‘T’: (0,7), ‘X’: (0, 475), ‘Y’: (0, 325), ‘Z’: (0, 4)}

]. The result for a similarly shaped file but with different number of time-points per scene would yield [

{‘S’: (0, 1), ‘T’: (0,8), ‘X’: (0, 475), ‘Y’: (0, 325), ‘Z’: (0, 4)}, {‘S’: (1, 2), ‘T’: (0,6), ‘X’: (0, 475), ‘Y’: (0, 325), ‘Z’: (0, 4)}, {‘S’: (2, 3), ‘T’: (0,7), ‘X’: (0, 475), ‘Y’: (0, 325), ‘Z’: (0, 4)}

] For the same initial file but with an RGB pixel type the result would be [

{‘S’: (0, 3), ‘T’: (0,7), ‘X’: (0, 475), ‘Y’: (0, 325), ‘Z’: (0, 4), ‘A’: (0,3)}

].

Return type:

list[dict]

get_mosaic_bounding_box()

Get the bounding box for the entire mosaic image.

Returns:

A Bounding Box, bbox, of type BBox. bbox.x = The x coordinate of the upper left corner of the bounding box. bbox.y = The y coordinate of the upper left corner of the bounding box. bbox.w = The width of the bounding box. bbox.h = The height of the bounding box.

Return type:

bbox

get_mosaic_scene_bounding_box(index: int = 0)

Get the bounding box (pyramid=0) for the specified scene. For mosaic files. This is not equivalent to the results from get_mosaic_tile_bounding_box.

Parameters:

index – the scene index, if omitted it defaults to Zero

Returns:

A Bounding Box, bbox, of type BBox. bbox.x = The x coordinate of the upper left corner of the bounding box. bbox.y = The y coordinate of the upper left corner of the bounding box. bbox.w = The width of the bounding box. bbox.h = The height of the bounding box.

Return type:

bbox

get_mosaic_tile_bounding_box(**kwargs)

Get a single tile (subblock) bounding box (pyramid=0) for the specified dimensions. For mosaic files.

Parameters:

kwargs – The keywords below allow you to specify the dimensions that you wish to match. If you under-specify the constraints you can easily end up with a massive image stack.

Z = 1 # The Z-dimension. C = 2 # The C-dimension (“channel”). T = 3 # The T-dimension (“time”). R = 4 # The R-dimension (“rotation”). S = 5 # The S-dimension (“scene”). I = 6 # The I-dimension (“illumination”). H = 7 # The H-dimension (“phase”). V = 8 # The V-dimension (“view”). M = 10 # The M_index, this is only valid for Mosaic files!

Returns:

A Bounding Box, bbox, of type BBox. bbox.x = The x coordinate of the upper left corner of the bounding box. bbox.y = The y coordinate of the upper left corner of the bounding box. bbox.w = The width of the bounding box. bbox.h = The height of the bounding box.

Return type:

bbox

get_scene_bounding_box(index: int = 0)

Get the bounding box (pyramid=0) for the specified scene. For non-mosaic files. This should be equivalent to the results from get_tile_bounding_box but requiring only one arguments.

Parameters:

index – the scene index, if omitted it defaults to Zero

Returns:

A Bounding Box, bbox, of type BBox. bbox.x = The x coordinate of the upper left corner of the bounding box. bbox.y = The y coordinate of the upper left corner of the bounding box. bbox.w = The width of the bounding box. bbox.h = The height of the bounding box.

Return type:

bbox

get_tile_bounding_box(**kwargs)

Get a single tile (subblock) bounding box (pyramid=0) for the specified dimensions. For non-mosaic files.

Parameters:

kwargs – The keywords below allow you to specify the dimensions that you wish to match. If you under-specify the constraints you can easily end up with a massive image stack.

Z = 1 # The Z-dimension. C = 2 # The C-dimension (“channel”). T = 3 # The T-dimension (“time”). R = 4 # The R-dimension (“rotation”). S = 5 # The S-dimension (“scene”). I = 6 # The I-dimension (“illumination”). H = 7 # The H-dimension (“phase”). V = 8 # The V-dimension (“view”).

Returns:

A Bounding Box, bbox, of type BBox. bbox.x = The x coordinate of the upper left corner of the bounding box. bbox.y = The y coordinate of the upper left corner of the bounding box. bbox.w = The width of the bounding box. bbox.h = The height of the bounding box.

Return type:

bbox

is_mosaic()

Test if the loaded file is a mosaic file

Returns:

True | False ie is this a mosaic file

Return type:

bool

property meta

Extract the metadata block from the czi file.

Returns:

The root element of the metadata tree

Return type:

xml.etree.ElementTree.Element

property pixel_type

The pixelType of the images. If the pixelType is different in the different subblocks it returns Invalid.

Return type:

A string containing the name of the type of each pixel. If inconsistent it returns invalid.

read_image(**kwargs)

Read the subblocks in the CZI file and for any subblocks that match all the constraints in kwargs return that data. This allows you to select channels/scenes/time-points/Z-slices etc. Note if passed a BGR image then the dims of the object will returned by this function and the implicit BGR will be expanded into an A dimension. A is samples per pixel and will only be present for BGR images. This is logically more consistent than mixing the samples into the channels as was done before aicspylibczi-3.0.0.

Parameters:

**kwargs – The keywords below allow you to specify the dimensions that you wish to match. If you under-specify the constraints you can easily end up with a massive image stack.

Z = 1 # The Z-dimension. C = 2 # The C-dimension (“channel”). T = 3 # The T-dimension (“time”). R = 4 # The R-dimension (“rotation”). S = 5 # The S-dimension (“scene”). I = 6 # The I-dimension (“illumination”). H = 7 # The H-dimension (“phase”). V = 8 # The V-dimension (“view”). M = 10 # The M_index, this is only valid for Mosaic files!

Specify the number of cores to use for multithreading with cores.

cores = 3 # use 3 cores for threaded reading of the image.

Returns:

a tuple of (numpy.ndarray, a list of (Dimension, size)) the second element of the tuple is to make sure the numpy.ndarray is interpretable. An example of the list is [(‘S’, 1), (‘T’, 1), (‘C’, 2), (‘Z’, 25), (‘Y’, 1024), (‘X’, 1024)] so if you probed the numpy.ndarray with .shape you would get (1, 1, 2, 25, 1024, 1024).

Return type:

(numpy.ndarray, [Dimension, Size])

Notes

The M Dimension is a representation of the m_index used inside libCZI. Unfortunately this can be sparsely packed for a given selection which causes problems when indexing memory. Consequently the M Dimension may not match the m_index that is being used in libCZI or displayed in Zeiss’ Zen software.

read_mosaic(region: Tuple | None = None, scale_factor: float = 1.0, background_color: Tuple | None = None, **kwargs)

Reads a mosaic file and returns an image corresponding to the specified dimensions. If the file is more than a 2D sheet of pixels, meaning only one channel, z-slice, time-index, etc then the kwargs must specify the dimension with more than one possible value.

Example: Read in the C=1 channel of a mosaic file at 1/10th the size

czi = CziFile(filename) img = czi.read_mosaic(scale_factor=0.1, C=1)

Parameters:

• region – A bounding box specifying the extraction box (x0, y0, width, height) specified in pixels

• scale_factor – The amount to scale the data by, 0.1 would mean an image 1/10 the height and width of native, if you get distortions it seems to be due to a bug in Zeiss’s libCZI I’m trying to track it down but for now if you use scale_factor=1.0 it should work properly.

• background_color – Background color used when pixel is outside of a sublock. If omitted, it defaults to black (r,g,b)=(0.0,0.0,0.0). Each color component is a float value between 0.0 and 1.0.

• kwargs – The keywords below allow you to specify the dimension plane that constrains the 2D data. If the constraints are underspecified the function will fail.

  Z = 1   # The Z-dimension.
  C = 2   # The C-dimension ("channel").
  T = 3   # The T-dimension ("time").
  R = 4   # The R-dimension ("rotation").
  S = 5   # The S-dimension ("scene").
  I = 6   # The I-dimension ("illumination").
  H = 7   # The H-dimension ("phase").
  V = 8   # The V-dimension ("view").
  

Returns:

(1, height, width)

Return type:

numpy.ndarray

read_subblock_metadata(unified_xml: bool = False, **kwargs)

Read the subblock specific metadata, ie time subblock was acquired / position at acquisition time etc.

Parameters:

• unified_xml (bool) – If True return a single unified xml tree containing the requested subblock. If False return a list of tuples (dims, xml)

• kwargs – The keywords below allow you to specify the dimensions that you wish to match. If you under-specify the constraints you can easily end up with a massive image stack.

  Z = 1 # The Z-dimension. C = 2 # The C-dimension (“channel”). T = 3 # The T-dimension (“time”). R = 4 # The R-dimension (“rotation”). S = 5 # The S-dimension (“scene”). I = 6 # The I-dimension (“illumination”). H = 7 # The H-dimension (“phase”). V = 8 # The V-dimension (“view”). M = 10 # The M_index, this is only valid for Mosaic files!

Returns:

• [(dict, str)] if unified_xml is False – an array of tuples containing a dimension dictionary and the corresponding subblock metadata

• xml.etree.ElementTree.Element if unified_xml is True – an xml document containing the requested subblock metadata.

property shape_is_consistent

Query if the file shape is consistent across scenes.

Returns:

true if consistent, false the scenes have different dimension shapes

Return type:

bool

property size

This returns the Size of each dimension in the dims string. So if S had valid indexes of [0, 1, 2, 3, 4] the returned tuple would have a value of 5 in the same position as the S occurs in the dims string.

Returns:

a tuple of dimension sizes. If the data has inconsistent shape the list will only contain -1 values and the user needs to use dims_shape() to get the indexes.

Return type:

tuple