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 readmax_workers (
Optional
[int
]) – Number of threads used to read and image. Default is half the number of detected cores.backend (
Optional
[str
]) – Must bepython
orbioformats
. 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.
- 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 retrievetile_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.
- __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)
- 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 arrayX (
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