Repository files navigation

Image Reading, Metadata Conversion, and Image Writing for Microscopy Images in Pure Python

• Supports reading metadata and imaging data for:

  • OME-TIFF
  • TIFF
  • ND2 -- (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: requiresjava andmaven, see below for details.)

• Supports writing metadata and imaging data for:

  • OME-TIFF
  • PNG,GIF,etc. -- (pip install aicsimageio[base-imageio])

• Supports reading and writing tofsspec supported file systemswherever 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 Support for more details.

Stable Release:pip install aicsimageio
Development Head:pip install git+https://github.com/AllenCellModeling/aicsimageio.git

AICSImageIO is supported on Windows, Mac, and Ubuntu.For other platforms, you will likely need to build from source.

TIFF and OME-TIFF reading and writing is always available afterinstallingaicsimageio, but extra supported formats can beoptionally 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.4
• Due 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.0
• Due 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 ajava andmvn executable in the environment. The simplest method is to installbioformats_jar from conda:conda install -c conda-forge bioformats_jar (which will additionally bringopenjdk andmaven packages).

For full package documentation please visitallencellmodeling.github.io/aicsimageio.

If 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# ...

The.data and.xarray_data properties will load the whole scene into memory.The.get_image_data function will load the whole scene into memory and then retrievethe specified chunk.

If 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# ...

The.dask_data and.xarray_dask_data properties and the.get_image_dask_datafunction will not load any piece of the imaging data into memory until you specificallycall.compute on the returned Dask array. In doing so, you will only then load theselected chunk in-memory.

Read stitched data or single tiles as a dimension.

Readers that support mosaic tile stitching:

• LifReader
• CziReader

If the file format reader supports stitching mosaic tiles together, theAICSImage object 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 image

This 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 ZYX

If the reader does not support stitching tiles together the M tile index will beavailable on theAICSImage object:

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 ZYX

If the file format reader detects mosaic tiles in the image, theReader objectwill store the tiles as a dimension.

If tile stitching is implemented, theReader can 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)

There are functions available on both theAICSImage andReader objectsto 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)

fromaicsimageioimportAICSImage# 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 metadata

Ifaicsimageio finds coordinate information for the spatial-temporal dimensions ofthe image in metadata, you can usexarray for 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.

File-System Specification (fsspec) allowsfor common object storage services (S3, GCS, etc.) to act like normal filesystems byfollowing the same base specification across them all. AICSImageIO utilizes thisstandard specification to make it possible to read directly from remote resources whenthe 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 fine

Remote reading requires that the file-system specification implementation for thetarget backend is installed.

• Fors3:pip install s3fs
• Forgs:pip install gcsfs

See thelist of known implementations.

The simpliest method to save your image as an OME-TIFF file with key pieces ofmetadata is to use thesave function.

fromaicsimageioimportAICSImageAICSImage("my_file.czi").save("my_file.ome.tiff")

Note: By defaultaicsimageio will generate only a portion of metadata to passalong from the reader to the OME model. This function currently does not do a fullmetadata translation.

For finer grain customization of the metadata, scenes, or if you want to save an arrayas 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.

In most cases,AICSImage.save is usually a good default but there are other imagewriters available. For more information, please refer toour writers documentation.

AICSImageIO is benchmarked usingasv.You can find the benchmark results for every commit tomain starting at the 4.0release on ourbenchmarks page.

See ourdeveloper resourcesfor information related to developing the code.

If you findaicsimageio useful, 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/aicsimageio

bibtex:

@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)