bfio.BioWriter

class BioWriter(file_path, max_workers=None, backend=None, metadata=None, image=None, **kwargs)

Bases: BioBase

BioWriter Write OME tiled tiff images.

This class handles the writing OME tiled tif images. There is a Java backend version of this tool that directly interacts with the Bio-Formats java library directly, and is primarily used for testing. It is currently not possible to change the tile size (which is set to 1024x1024).

Unlike the BioReader class, the properties of this class are settable until the first time the write method is called.

For for information, visit the Bio-Formats page: https://www.openmicroscopy.org/bio-formats/

Note

In order to use the bioformats backend, jpype must be installed.

Initialize a BioWriter.

Parameters
  • file_path (Union[str, Path]) – Path to file to read

  • max_workers (Optional[int]) – Number of threads used to read and image. Default is half the number of detected cores.

  • backend (Optional[str]) – Must be python or bioformats. Default is python.

  • metadata (Optional[OME]) – This directly sets the ome tiff metadata using the OMEXML class if specified. Defaults to None.

  • image (Optional[ndarray]) – The metadata will be set based on the dimensions and data type of the numpy array specified by this keyword argument. Ignored if metadata is specified. Defaults to None.

  • kwargs – Most BioWriter object properties can be passed as keyword arguments to initialize the image metadata. If the metadata argument is used, then keyword arguments are ignored.

X()
py:property::
Setter

Set the number of pixels in the x-dimension (width)

Getter

Number of pixels in the x-dimension (width)

Type

int

Y()
py:property::
Setter

Set the number of pixels in the y-dimension (height)

Getter

Number of pixels in the y-dimension (height)

Type

int

Z()
py:property::
Setter

Set the number of pixels in the z-dimension (depth)

Getter

Number of pixels in the z-dimension (depth)

Type

int

C()
py:property::
Setter

Set the number of pixels in the c-dimension

Getter

Number of pixels in the c-dimension

Type

int

T()
py:property::
Setter

Set the number of pixels in the t-dimension

Getter

Number of pixels in the t-dimension

Type

int

property spp

Same as samples_per_pixel.

property dtype: dtype

The numpy pixel type of the data.

__setitem__(keys, value)

Image saving using numpy-like indexing.

This is an abbreviated method of accessing the write method, where a portion of the image will be saved using numpy-like slicing syntax. Up to 5 dimensions can be designated depending on the number of available dimensions in the image array (Y, X, Z, C, T).

Note

Not all methods of indexing can be used, and some indexing will lead to unexpected results. For example, logical indexing cannot be used, and step sizes in slice objects is ignored for the first three indices. This means and index such as [0:100:2,0:100:2,0,0,0] will save a 100x100x1x1x1 numpy array.

Parameters
  • keys (Union[tuple, slice]) – numpy-like slicing used to save a section of an image.

  • value (ndarray) – Image chunk to save.

Return type

None

Example

import bfio

# Initialize the biowriter
bw = bfio.BioWriter('Path/To/File.ome.tif',
                    X=100,
                    Y=100,
                    dtype=numpy.uint8)

# Load and copy a 100x100 array of pixels
bw[:100,:100,0,0,0] = np.zeros((100,100),dtype=numpy.uint8)

# Slice steps sizes are ignored for the first 3 indices, so this
# does the same as above
bw[0:100:2,0:100:2] = np.zeros((100,100),dtype=numpy.uint8)

# The last two dimensions can receive a tuple or list as input
# Save two channels
bw[:100,100,0,:2,0] = np.ones((100,100,1,2),dtype=numpy.uint8)

# If the file is 3d, save the first 10 z-slices
br[...,:10,0,0] = np.ones((100,100,1,2),dtype=numpy.uint8)
property bpp

Same as bytes_per_pixel.

property bytes_per_pixel: int

Number of bytes per pixel.

property channel_names: List[str]

Get the channel names for the image.

property cnames: List[str]

Same as channel_names.

maximum_batch_size(tile_size, tile_stride=None)

maximum_batch_size Maximum allowable batch size for tiling.

The pixel buffer only loads at most two supertiles at a time. If the batch size is too large, then the tiling function will attempt to create more tiles than what the buffer holds. To prevent the tiling function from doing this, there is a limit on the number of tiles that can be retrieved in a single call. This function determines what the largest number of retrievable batches is.

Parameters
  • tile_size (List[int]) – The height and width of the tiles to retrieve

  • tile_stride (Optional[List[int]]) – If None, defaults to tile_size. Defaults to None.

Return type

int

Returns

Maximum allowed number of batches that can be retrieved by the

iterate method.

property metadata: OME

Get the metadata for the image.

This function calls the Bio-Formats metadata parser, which extracts metadata from an image. This returns a reference to an OMEXML class, which is a convenient handler for the complex xml metadata created by Bio-Formats.

Most basic metadata information have their own BioReader methods, such as image dimensions(i.e. x, y, etc). However, in some cases it may be necessary to access the underlying metadata class.

Minor changes have been made to the original OMEXML class created for python-bioformats, so the original OMEXML documentation should assist those interested in directly accessing the metadata. In general, it is best to assign data using the object properties to ensure the metadata stays in sync with the file.

For information on the OMEXML class: https://github.com/CellProfiler/python-bioformats/blob/master/bioformats/omexml.py

Returns

OMEXML object for the image

property physical_size_x: Tuple[float, str]

Physical size of pixels in x-dimension.

Returns

Units per pixel, Units (i.e. “cm” or “mm”)

property physical_size_y: Tuple[float, str]

Physical size of pixels in y-dimension.

Returns

Units per pixel, Units (i.e. “cm” or “mm”)

property physical_size_z: Tuple[float, str]

Physical size of pixels in z-dimension.

Returns

Units per pixel, Units (i.e. “cm” or “mm”)

property ps_x: Tuple[float, str]

Same as physical_size_x.

property ps_y

Same as physical_size_y.

property ps_z

Same as physical_size_z.

property read_only: bool

Returns true if object is ready only.

property samples_per_pixel: int

Number of samples per pixel.

property shape: Tuple[int, int, int, int, int]

The 5-dimensional shape of the image.

Returns

(Y, X, Z, C, T) shape of the image

write(image, X=None, Y=None, Z=None, C=None, T=None)

write_image Write the image.

Write all or part of the image. A 5-dimmensional numpy.ndarray is required as the image input.

Parameters
  • image (ndarray) – a 5-d numpy array

  • X (Optional[int]) – The starting index of where to save data along the x-axis (columns). If None, loads the full range. Defaults to None.

  • Y (Optional[int]) – The starting index of where to save data along the y-axis (rows). If None, loads the full range. Defaults to None.

  • Z (Optional[int]) – The starting index of where to save data along the z-axis (depth). If None, loads the full range. Defaults to None.

  • C (Union[list, tuple, int, None]) – Values indicating channel indices to load. If None, loads the full range. Defaults to None.

  • T (Union[list, tuple, int, None]) – Values indicating timepoints to load. If None, loads the full range. Defaults to None.

Return type

None

close()

Close the image.

This function should be called when an image will no longer be written to. This allows for proper closing and organization of metadata.

Return type

None