Image Reading, Metadata Conversion, and Image Writing for Microscopy Images in Pure Python
Project description
AICSImageIO
Image Reading, Metadata Conversion, and Image Writing for Microscopy Images in Pure Python
Features
-
Supports reading metadata and imaging data for:
CZI
OME-TIFF
TIFF
LIF
- Any additional format supported by imageio
-
Supports writing metadata and imaging data for:
OME-TIFF
-
Supports reading from and writing to any fsspec supported file system:
- 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
)
See the list of known implementations.
- Local paths (i.e.
Installation
Stable Release: pip install aicsimageio
Development Head: pip install git+https://github.com/AllenCellModeling/aicsimageio.git
Documentation
For full package documentation please visit allencellmodeling.github.io/aicsimageio.
Quickstart
Full Image Reading
from aicsimageio import AICSImage, imread
# Get an AICSImage object
img = AICSImage("my_file.tiff") # selects the first scene found
img.data # returns 5D TCZYX numpy array
img.xarray_data # returns 5D TCZYX xarray data array backed by numpy
img.dims # returns a Dimensions object
img.dims.order # returns string "TCZYX"
img.dims.X # returns size of X dimension
img.shape # returns tuple of dimension sizes in TCZYX order
img.get_image_data("CZYX", T=0) # returns 4D CZYX numpy array
# Get the id of the current operating scene
img.current_scene
# Get a list valid scene ids
img.scenes
# Change scene
img.set_scene("Image:1")
# Same operations on a different scene
img.data # returns 5D TCZYX numpy array
img.xarray_data # returns 5D TCZYX xarray data array backed by numpy
img.dims # returns a Dimensions object
img.dims.order # returns string "TCZYX"
img.dims.X # returns size of X dimension
img.shape # returns tuple of dimension sizes in TCZYX order
img.get_image_data("CZYX", T=0) # returns 4D CZYX numpy array
# Get 5D TCZYX numpy array
data = imread("my_file.tiff") # optionally provide a scene id, default first
Full Image Reading Notes
The .data
and .xarray_data
properties and the .get_image_data
function will
load the whole image into memory prior to returning the specified chunk (if using
.get_image_data
).
Delayed Image Reading
from aicsimageio import AICSImage, imread_dask
# Get an AICSImage object
img = AICSImage("my_file.tiff") # selects the first scene found
img.dask_data # returns 5D TCZYX dask array
img.xarray_dask_data # returns 5D TCZYX xarray data array backed by dask array
img.dims # returns a Dimensions object
img.dims.order # returns string "TCZYX"
img.dims.X # returns size of X dimension
img.shape # returns tuple of dimension sizes in TCZYX order
img.get_image_dask_data("CZYX", T=0) # returns 4D CZYX dask array
# Get the id of the current operating scene
img.current_scene
# Get a list valid scene ids
img.scenes
# Change scene
img.set_scene("Image:1")
# Same operations on a different scene
img.dask_data # returns 5D TCZYX dask array
img.xarray_dask_data # returns 5D TCZYX xarray data array backed by dask array
img.dims # returns a Dimensions object
img.dims.order # returns string "TCZYX"
img.dims.X # returns size of X dimension
img.shape # returns tuple of dimension sizes in TCZYX order
img.get_image_dask_data("CZYX", T=0) # returns 4D CZYX dask array
# Read a specified portion of dask array
lazy_t0 = img.get_image_dask_data("CZYX", T=0) # returns 4D CZYX dask array
t0 = lazy_t0.compute() # returns 4D CZYX numpy array
# Get a 5D TCZYX dask array
lazy_data = imread_dask("my_file.tiff") # optionally provide a scene id, default first
lazy_t0 = lazy_data[0, :]
t0 = lazy_t0.compute()
Delayed Image Reading Notes
The .dask_data
and .xarray_dask_data
properties and the .get_image_dask_data
function will not load any piece of the image into memory until you specifically
call .compute
on the returned Dask array. In doing so, you will only then load the
selected data in-memory.
Remote Image Reading
from aicsimageio import AICSImage
# Get an AICSImage object
img = AICSImage("http://my-website.com/my_file.tiff")
img = AICSImage("s3://my-bucket/my_file.tiff")
img = AICSImage("gcs://my-bucket/my_file.tiff")
# All other normal operations work just fine
Metadata Reading
from aicsimageio import AICSImage
# Get an AICSImage object
img = AICSImage("my_file.tiff") # selects the first scene found
img.metadata # returns the metadata object for this image type
img.channel_names # returns a list of string channel names found in the metadata
img.physical_pixel_size.Z # returns the Z dimension pixel size as found in the metadata
img.physical_pixel_size.Y # returns the Y dimension pixel size as found in the metadata
img.physical_pixel_size.X # returns the X dimension pixel size as found in the metadata
Performance Considerations
- If your image fits in memory: use
AICSImage.data
,AICSImage.xarray_data
,AICSImage.get_image_data
, orReader
equivalents. - If your image is too large to fit in memory: use
AICSImage.dask_data
,AICSImage.xarray_dask_data
,AICSImage.get_image_dask_data
, orReader
equivalents. - If your image does not support native chunk reading: it may not be best to read chunks from a remote source. While possible, the format of the image matters a lot for chunked read performance.
Benchmarks
AICSImageIO is benchmarked using asv.
You can find the benchmark results for every commit to main
starting at the 4.0
release on our
benchmarks page.
Napari Interactive Viewer
napari is a fast, interactive, multi-dimensional image viewer for python and it is pretty useful for imaging data that this package tends to interact with.
We have also released
napari-aicsimageio, a plugin
that allows use of all the functionality described in this library, but in the napari
default viewer itself.
Development
See our developer resources for information related to developing the code.
Free software: BSD-3-Clause
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for aicsimageio-4.0.0.dev2-py2.py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 211fce29a98bf01a7fe084f138b9708687a720c7dc52558bc418998fd63423ec |
|
MD5 | 0fbdedb9b5f5a214918492b30244e3f9 |
|
BLAKE2b-256 | 75bfe04cee29dd42d1629cff9aaff0049e9e78ccfa639d55b6d886c9f7a0f1a3 |