aicsimageio.aics_image.AICSImage

class aicsimageio.aics_image.AICSImage(image: Union[str, Path, ndarray, Array, DataArray, List[Union[ndarray, Array, DataArray]], List[Union[str, Path]]], reader: Optional[Type[Reader]] = None, reconstruct_mosaic: bool = True, fs_kwargs: Dict[str, Any] = {}, **kwargs: Any)[source]

AICSImage takes microscopy image data types (files or arrays) of varying dimensions (“ZYX”, “TCZYX”, “CYX”) and reads them as consistent 5D “TCZYX” (“Time-Channel-Z-Y-X”) ordered array(s). The data and metadata are lazy loaded and can be accessed as needed.

Parameters

image (types.ImageLike) – A string, Path, fsspec supported URI, or arraylike to read.
reader (Optional[Type[Reader]]) – The Reader class to specifically use for reading the provided image. Default: None (find matching reader)
reconstruct_mosaic (bool) – Boolean for setting that data for this object to the reconstructed / stitched mosaic image. Default: True (reconstruct the mosaic image from tiles) Notes: If True and image is a mosaic, data will be fully reconstructed and stitched array. If True and base reader doesn’t support tile stitching, data won’t be stitched and instead will have an M dimension for tiles. If False and image is a mosaic, data won’t be stitched and instead will have an M dimension for tiles. If image is not a mosaic, data won’t be stitched or have an M dimension for tiles.
fs_kwargs (Dict[str, Any]) – Any specific keyword arguments to pass down to the fsspec created filesystem. Default: {}
kwargs (Any) – Extra keyword arguments that will be passed down to the reader subclass.

Examples

Initialize an image then read the file and return specified slices as a numpy array.

>>> img = AICSImage("my_file.tiff")
... zstack_t8 = img.get_image_data("ZYX", T=8, C=0)

Initialize an image, construct a delayed dask array for certain slices, then read only the specified chunk of data.

>>> img = AICSImage("my_file.czi")
... zstack_t8 = img.get_image_dask_data("ZYX", T=8, C=0)
... zstack_t8_data = zstack_t8.compute()

Initialize an image with a dask or numpy array.

>>> data = np.random.rand(100, 100)
... img = AICSImage(data)

Initialize an image from S3 with s3fs.

>>> img = AICSImage("s3://my_bucket/my_file.tiff")

Initialize an image and pass arguments to the reader using kwargs.

>>> img = AICSImage("my_file.czi", chunk_dims=["T", "Y", "X"])

Initialize an image, change scene, read data to numpy.

>>> img = AICSImage("my_many_scene.czi")
... img.set_scene("Image:3")
... img.data

Initialize an image with a specific reader. This is useful if you know the file type in advance or would like to skip a few of the file format checks we do internally. Useful when reading from remote sources to reduce network round trips.

>>> img = AICSImage("malformed_metadata.ome.tiff", reader=readers.TiffReader)

Data for a mosaic file is returned pre-stitched (if the base reader supports it).

>>> img = AICSImage("big_mosaic.czi")
... img.dims  # <Dimensions [T: 40, C: 3, Z: 1, Y: 30000, X: 45000]>

Data for mosaic file can be explicitly returned as tiles. This is the same data as a reconstructed mosaic except that the tiles are stored in their own dimension (M).

>>> img = AICSImage("big_mosaic.czi", reconstruct_mosaic=False)
... img.dims  # <Dimensions [M: 150, T: 40, C: 3, Z: 1, Y: 200, X: 300]>

Data is mosaic file but reader doesn’t support tile stitching.

>>> img = AICSImage("unsupported_mosaic.ext")
... img.dims  # <Dimensions [M: 100, T: 1, C: 2, Z: 1, Y: 400, X: 400]>

Notes

If your image is made up of mosaic tiles, data and dimension information returned from this object will be from the tiles already stitched together.

If you do not want the image pre-stitched together, you can use the base reader by either instantiating the reader independently or using the .reader property.

__init__(image: Union[str, Path, ndarray, Array, DataArray, List[Union[ndarray, Array, DataArray]], List[Union[str, Path]]], reader: Optional[Type[Reader]] = None, reconstruct_mosaic: bool = True, fs_kwargs: Dict[str, Any] = {}, **kwargs: Any)[source]

Methods

`__init__`(image[, reader, ...])
`determine_reader`(image[, fs_kwargs])	Cheaply check to see if a given file is a recognized type and return the appropriate reader for the image.
`get_dask_stack`(**kwargs)	Get all scenes stacked in to a single array.
`get_image_dask_data`([dimension_order_out])	Get specific dimension image data out of an image as a dask array.
`get_image_data`([dimension_order_out])	Read the image as a numpy array then return specific dimension image data.
`get_mosaic_tile_position`(mosaic_tile_index, ...)	Get the absolute position of the top left point for a single mosaic tile.
`get_mosaic_tile_positions`(**kwargs)	Get the absolute positions of the top left points for each mosaic tile matching the specified dimensions and current scene.
`get_stack`(**kwargs)	Get all scenes stacked in to a single array.
`get_xarray_dask_stack`(**kwargs)	Get all scenes stacked in to a single array.
`get_xarray_stack`(**kwargs)	Get all scenes stacked in to a single array.
`save`(uri[, select_scenes])	Saves the file data to OME-TIFF format with general naive best practices.
`set_scene`(scene_id)	Set the operating scene.

Attributes

`SUPPORTED_READERS`
`channel_names`	returns channel_names -- Using available metadata, the list of strings representing channel names.
`current_scene`	returns scene -- The current operating scene.
`current_scene_index`	returns scene_index -- The current operating scene index in the file.
`dask_data`	returns dask_data -- The image as a dask array with standard dimension ordering.
`data`	returns data -- The image as a numpy array with standard dimension ordering.
`dims`	returns dims -- Object with the paired dimension names and their sizes.
`dtype`	returns dtype -- Data-type of the image array's elements.
`metadata`	returns metadata -- Passthrough to the base image reader metadata property.
`mosaic_tile_dims`	returns tile_dims -- The dimensions for each tile in the mosaic image.
`ome_metadata`	returns metadata -- The original metadata transformed into the OME specfication.
`physical_pixel_sizes`	returns sizes -- Using available metadata, the floats representing physical pixel sizes for
`reader`	returns reader -- The object created to read the image file type.
`reader_path`
`reader_paths`
`scenes`	returns scenes -- A tuple of valid scene ids in the file.
`shape`	returns shape -- Tuple of the image array's dimensions.
`xarray_dask_data`	returns xarray_dask_data -- The delayed image and metadata as an annotated data array.
`xarray_data`	returns xarray_data -- The fully read image and metadata as an annotated data array.