Package: aicsimageio
AICSImageIOImage Reading, Metadata Conversion, and Image Writing for Microscopy Images in Pure PythonFeaturesSupports reading metadata and imaging data for:OME-TIFFTIFFND2-- (pip install aicsimageio[nd2])DV-- (pip install aicsimageio[dv])CZI-- (pip install aicspylibczi>=3.1.1 fsspec>=2022.8.0)LIF-- (pip install readlif>=0.6.4)PNG,GIF,etc.-- (pip install aicsimageio[base-imageio])Files supported byBio-Formats-- (pip install aicsimageio bioformats_jar) (Note: requiresjavaandmaven, see below for details.)Supports writing metadata and imaging data for:OME-TIFFPNG,GIF,etc.-- (pip install aicsimageio[base-imageio])Supports reading and writing tofsspecsupported file systems
wherever possible:Local paths (i.e.my-file.png)HTTP URLs (i.e.https://my-domain.com/my-file.png)s3fs(i.e.s3://my-bucket/my-file.png)gcsfs(i.e.gcs://my-bucket/my-file.png)SeeCloud IO Supportfor more details.InstallationStable Release:pip install aicsimageioDevelopment Head:pip install git+https://github.com/AllenCellModeling/aicsimageio.gitAICSImageIO is supported on Windows, Mac, and Ubuntu.
For other platforms, you will likely need to build from source.Extra Format InstallationTIFF and OME-TIFF reading and writing is always available after
installingaicsimageio, but extra supported formats can be
optionally installed using[...]syntax.For a single additional supported format (e.g. ND2):pip install aicsimageio[nd2]For a single additional supported format (e.g. ND2), development head:pip install "aicsimageio[nd2] @ git+https://github.com/AllenCellModeling/aicsimageio.git"For a single additional supported format (e.g. ND2), specific tag (e.g.v4.0.0.dev6):pip install "aicsimageio[nd2] @ git+https://github.com/AllenCellModeling/aicsimageio.git@v4.0.0.dev6"For faster OME-TIFF reading with tile tags:pip install aicsimageio[bfio]For multiple additional supported formats:pip install aicsimageio[base-imageio,nd2]For all additional supported (and openly licensed) formats:pip install aicsimageio[all]Due to the GPL license, LIF support is not included with the[all]extra, and must be installed manually withpip install aicsimageio readlif>=0.6.4Due to the GPL license, CZI support is not included with the[all]extra, and must be installed manually withpip install aicsimageio aicspylibczi>=3.1.1 fsspec>=2022.8.0Due to the GPL license, Bio-Formats support is not included with the[all]extra, and must be installed manually withpip install aicsimageio bioformats_jar.Important!!Bio-Formats support also requires ajavaandmvnexecutable in the environment. The simplest method is to installbioformats_jarfrom conda:conda install -c conda-forge bioformats_jar(which will additionally bringopenjdkandmavenpackages).DocumentationFor full package documentation please visitallencellmodeling.github.io/aicsimageio.QuickstartFull Image ReadingIf your image fits in memory:fromaicsimageioimportAICSImage# Get an AICSImage objectimg=AICSImage("my_file.tiff")# selects the first scene foundimg.data# returns 5D TCZYX numpy arrayimg.xarray_data# returns 5D TCZYX xarray data array backed by numpyimg.dims# returns a Dimensions objectimg.dims.order# returns string "TCZYX"img.dims.X# returns size of X dimensionimg.shape# returns tuple of dimension sizes in TCZYX orderimg.get_image_data("CZYX",T=0)# returns 4D CZYX numpy array# Get the id of the current operating sceneimg.current_scene# Get a list valid scene idsimg.scenes# Change scene using nameimg.set_scene("Image:1")# Or by scene indeximg.set_scene(1)# Use the same operations on a different scene# ...Full Image Reading NotesThe.dataand.xarray_dataproperties will load the whole scene into memory.
The.get_image_datafunction will load the whole scene into memory and then retrieve
the specified chunk.Delayed Image ReadingIf your image doesn't fit in memory:fromaicsimageioimportAICSImage# Get an AICSImage objectimg=AICSImage("my_file.tiff")# selects the first scene foundimg.dask_data# returns 5D TCZYX dask arrayimg.xarray_dask_data# returns 5D TCZYX xarray data array backed by dask arrayimg.dims# returns a Dimensions objectimg.dims.order# returns string "TCZYX"img.dims.X# returns size of X dimensionimg.shape# returns tuple of dimension sizes in TCZYX order# Pull only a specific chunk in-memorylazy_t0=img.get_image_dask_data("CZYX",T=0)# returns out-of-memory 4D dask arrayt0=lazy_t0.compute()# returns in-memory 4D numpy array# Get the id of the current operating sceneimg.current_scene# Get a list valid scene idsimg.scenes# Change scene using nameimg.set_scene("Image:1")# Or by scene indeximg.set_scene(1)# Use the same operations on a different scene# ...Delayed Image Reading NotesThe.dask_dataand.xarray_dask_dataproperties and the.get_image_dask_datafunction will not load any piece of the imaging data into memory until you specifically
call.computeon the returned Dask array. In doing so, you will only then load the
selected chunk in-memory.Mosaic Image ReadingRead stitched data or single tiles as a dimension.Readers that support mosaic tile stitching:LifReaderCziReaderAICSImageIf the file format reader supports stitching mosaic tiles together, theAICSImageobject will default to stitching the tiles back together.img=AICSImage("very-large-mosaic.lif")img.dims.order# T, C, Z, big Y, big X, (S optional)img.dask_data# Dask chunks fall on tile boundaries, pull YX chunks out of the imageThis behavior can be manually turned off:img=AICSImage("very-large-mosaic.lif",reconstruct_mosaic=False)img.dims.order# M (tile index), T, C, Z, small Y, small X, (S optional)img.dask_data# Chunks use normal ZYXIf the reader does not support stitching tiles together the M tile index will be
available on theAICSImageobject:img=AICSImage("some-unsupported-mosaic-stitching-format.ext")img.dims.order# M (tile index), T, C, Z, small Y, small X, (S optional)img.dask_data# Chunks use normal ZYXReaderIf the file format reader detects mosaic tiles in the image, theReaderobject
will store the tiles as a dimension.If tile stitching is implemented, theReadercan also return the stitched image.reader=LifReader("ver-large-mosaic.lif")reader.dims.order# M, T, C, Z, tile size Y, tile size X, (S optional)reader.dask_data# normal operations, can use M dimension to select individual tilesreader.mosaic_dask_data# returns stitched mosaic - T, C, Z, big Y, big, X, (S optional)Single Tile Absolute PositioningThere are functions available on both theAICSImageandReaderobjects
to help with single tile positioning:img=AICSImage("very-large-mosaic.lif")img.mosaic_tile_dims# Returns a Dimensions object with just Y and X dim sizesimg.mosaic_tile_dims.Y# 512 (for example)# Get the tile start indices (top left corner of tile)y_start_index,x_start_index=img.get_mosaic_tile_position(12)Metadata ReadingfromaicsimageioimportAICSImage# Get an AICSImage objectimg=AICSImage("my_file.tiff")# selects the first scene foundimg.metadata# returns the metadata object for this file format (XML, JSON, etc.)img.channel_names# returns a list of string channel names found in the metadataimg.physical_pixel_sizes.Z# returns the Z dimension pixel size as found in the metadataimg.physical_pixel_sizes.Y# returns the Y dimension pixel size as found in the metadataimg.physical_pixel_sizes.X# returns the X dimension pixel size as found in the metadataXarray Coordinate Plane AttachmentIfaicsimageiofinds coordinate information for the spatial-temporal dimensions of
the image in metadata, you can usexarrayfor indexing by coordinates.fromaicsimageioimportAICSImage# Get an AICSImage objectimg=AICSImage("my_file.ome.tiff")# Get the first ten seconds (not frames)first_ten_seconds=img.xarray_data.loc[:10]# returns an xarray.DataArray# Get the first ten major units (usually micrometers, not indices) in Zfirst_ten_mm_in_z=img.xarray_data.loc[:,:,:10]# Get the first ten major units (usually micrometers, not indices) in Yfirst_ten_mm_in_y=img.xarray_data.loc[:,:,:,:10]# Get the first ten major units (usually micrometers, not indices) in Xfirst_ten_mm_in_x=img.xarray_data.loc[:,:,:,:,:10]Seexarray"Indexing and Selecting Data" Documentationfor more information.Cloud IO SupportFile-System Specification (fsspec)allows
for common object storage services (S3, GCS, etc.) to act like normal filesystems by
following the same base specification across them all. AICSImageIO utilizes this
standard specification to make it possible to read directly from remote resources when
the specification is installed.fromaicsimageioimportAICSImage# Get an AICSImage objectimg=AICSImage("http://my-website.com/my_file.tiff")img=AICSImage("s3://my-bucket/my_file.tiff")img=AICSImage("gcs://my-bucket/my_file.tiff")# Or read with specific filesystem creation argumentsimg=AICSImage("s3://my-bucket/my_file.tiff",fs_kwargs=dict(anon=True))img=AICSImage("gcs://my-bucket/my_file.tiff",fs_kwargs=dict(anon=True))# All other normal operations work just fineRemote reading requires that the file-system specification implementation for the
target backend is installed.Fors3:pip install s3fsForgs:pip install gcsfsSee thelist of known implementations.Saving to OME-TIFFThe simpliest method to save your image as an OME-TIFF file with key pieces of
metadata is to use thesavefunction.fromaicsimageioimportAICSImageAICSImage("my_file.czi").save("my_file.ome.tiff")Note:By defaultaicsimageiowill generate only a portion of metadata to pass
along from the reader to the OME model. This function currently does not do a full
metadata translation.For finer grain customization of the metadata, scenes, or if you want to save an array
as an OME-TIFF, the writer class can also be used to customize as needed.importnumpyasnpfromaicsimageio.writersimportOmeTiffWriterimage=np.random.rand(10,3,1024,2048)OmeTiffWriter.save(image,"file.ome.tif",dim_order="ZCYX")SeeOmeTiffWriter documentationfor more details.Other WritersIn most cases,AICSImage.saveis usually a good default but there are other image
writers available. For more information, please refer toour writers documentation.BenchmarksAICSImageIO is benchmarked usingasv.
You can find the benchmark results for every commit tomainstarting at the 4.0
release on ourbenchmarks page.DevelopmentSee ourdeveloper resourcesfor information related to developing the code.CitationIf you findaicsimageiouseful, please cite this repository as:Eva Maxfield Brown, Dan Toloudis, Jamie Sherman, Madison Swain-Bowden, Talley Lambert, AICSImageIO Contributors (2021). AICSImageIO: Image Reading, Metadata Conversion, and Image Writing for Microscopy Images in Pure Python [Computer software]. GitHub.https://github.com/AllenCellModeling/aicsimageiobibtex:@misc{aicsimageio,author={Brown, Eva Maxfield and Toloudis, Dan and Sherman, Jamie and Swain-Bowden, Madison and Lambert, Talley and {AICSImageIO Contributors}},title={AICSImageIO: Image Reading, Metadata Conversion, and Image Writing for Microscopy Images in Pure Python},year={2021},publisher={GitHub},url={https://github.com/AllenCellModeling/aicsimageio}}Free software: BSD-3-Clause(The LIF component is licensed under GPLv3 and is not included in this package)(The Bio-Formats component is licensed under GPLv2 and is not included in this package)(The CZI component is licensed under GPLv3 and is not included in this package)