DOCSEARCHbyAlgolia
Submit Docs

AICSImageIO

repository·main·Indexed 42 days ago

https://github.com/allencellmodeling/aicsimageio

A pure Python library for reading and writing metadata and imaging data from various microscopy image formats, including OME-TIFF, ND2, and CZI. It supports cloud-based file systems via fsspec (S3, GCS, HTTP) and provides options for both in-memory loading via numpy and delayed loading via Dask. The library includes the AICSImage class for standardized data access and OmeZarrWriter for converting images to OME-Zarr. Note: AICSImageIO is in maintenance mode; its successor is bioio.

Tokens
4.6K
Snippets
17
Records
22
Agent score
53%

What's inside AICSImageIO

  2. Handle mosaic images and tile stitching

    main

    Some readers (like LifReader and CziReader) support mosaic tile stitching.

    Using AICSImage

    By default, AICSImage will stitch tiles back together. If you want to access the tiles individually, set reconstruct_mosaic=False.

    • With stitching (default): dims.order includes big Y and big X dimensions.
    • Without stitching: dims.order includes an M (tile index) dimension and small Y/X dimensions.

    Using the Reader directly

    If using a Reader object, you can access individual tiles via the M dimension or use .mosaic_dask_data to get the stitched version.

    Tile Positioning

    Use get_mosaic_tile_position(index) to find the top-left corner (y, x) of a specific tile.

    from aicsimageio import AICSImage

# Default behavior (stitched)
img = AICSImage("very-large-mosaic.lif")
img.dims.order  # T, C, Z, big Y, big X, (S optional)

# Manual tile access (unstitched)
img = AICSImage("very-large-mosaic.lif", reconstruct_mosaic=False)
img.dims.order  # M (tile index), T, C, Z, small Y, small X, (S optional)

# Get tile start indices
y_start_index, x_start_index = img.get_mosaic_tile_position(12)

  3. Implement a new custom Reader

    main

    AICSImageIO uses a two-tier architecture: Reader (accesses raw data) and AICSImage (standardizes data to the AICS/OME model).

    To implement a new Reader, you must inherit from the Reader base class and implement the following required methods:

    • _is_supported_image(self, object): Returns True if the reader can handle the provided object (file, array, etc.).
    • scenes (property): Returns a Tuple of all scene names (images/series).
    • _read_delayed(self): Returns an xarray.DataArray backed by a delayed dask.array.Array.
    • _read_immediate(self): Returns an xarray.DataArray backed by an in-memory numpy.ndarray.

    You can optionally implement these for enhanced functionality:

    • _get_stitched_dask_mosaic(self): Stitches mosaic tiles from a delayed dask array.
    • _get_stitched_mosaic(self): Stitches mosaic tiles from an in-memory numpy array.
    • get_mosaic_tile_position(self): Returns a specific mosaic tile's position from its index.
    • ome_metadata (property): Returns metadata converted to OME format.
    • physical_pixel_sizes (property): Returns spatial dimension pixel sizes.

  4. Cloud IO Support in AICSImageIO

    main

    AICSImageIO supports reading and writing to fsspec compatible file systems. This allows you to interact with remote data using standard paths.

    Supported systems include:

    • Local paths: my-file.png
    • HTTP URLs: https://my-domain.com/my-file.png
    • S3 (AWS): s3://my-bucket/my-file.png
    • GCS (Google Cloud): gcs://my-bucket/my-file.png

  6. Install extra format support for AICSImageIO

    main

    While OME-TIFF and TIFF support is included by default, other microscopy formats require additional dependencies. Use the [...] syntax with pip to install specific extras.

    Supported Formats and Installation Commands

    • ND2: pip install aicsimageio[nd2]
    • DV: pip install aicsimageio[dv]
    • CZI: pip install aicsimageio aicspylibczi>=3.1.1 fsspec>=2022.8.0 (Note: Not included in [all] due to GPL license)
    • LIF: pip install aicsimageio readlif>=0.6.4 (Note: Not included in [all] due to GPL license)
    • PNG, GIF, etc.: pip install aicsimageio[base-imageio]
    • Bio-Formats: pip install aicsimageio bioformats_jar (Requires java and maven. Recommended: conda install -c conda-forge bioformats_jar)
    • Faster OME-TIFF (tile tags): pip install aicsimageio[bfio]

    Installation Shortcuts

    • Multiple formats: pip install aicsimageio[base-imageio,nd2]
    • All openly licensed formats: pip install aicsimageio[all]
    • Development head with specific extra: pip install "aicsimageio[nd2] @ git+https://github.com/AllenCellModeling/aicsimageio.git"
    # Example: Install ND2 support
pip install aicsimageio[nd2]

# Example: Install all openly licensed formats
pip install aicsimageio[all]

  7. Read large images using delayed (Dask) loading

    main

    For images that exceed available memory, use delayed loading via Dask. This prevents loading the entire dataset into RAM until you explicitly request it.

    Key properties:

    • .dask_data: Returns a 5D TCZYX dask array.
    • .xarray_dask_data: Returns a 5D TCZYX xarray data array backed by a dask array.
    • .get_image_dask_data(dim_order, **kwargs): Returns an out-of-memory dask array for a specific chunk.

    To bring a specific chunk into memory, call .compute() on the resulting Dask array.

    from aicsimageio import AICSImage

# 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

# Pull only a specific chunk in-memory
lazy_t0 = img.get_image_dask_data("CZYX", T=0)  # returns out-of-memory 4D dask array
t0 = lazy_t0.compute()  # returns in-memory 4D numpy array

  8. Install aicsimageio from source

    main

    If you need to install from source, you can either clone the GitHub repository with its submodules or download the source tarball.

    Option 1: Clone the repository

    Clone the public repository and initialize submodules:

    $ git clone git://github.com/AllenCellModeling/aicsimageio
$ git submodule update --init --recursive

    Option 2: Download the tarball

    Download the tarball directly:

    $ curl -OL https://github.com/AllenCellModeling/aicsimageio/tarball/main

    Final Installation Step

    Once you have the source files locally, install them using setup.py:

    $ python setup.py install
    $ git clone git://github.com/AllenCellModeling/aicsimageio
$ git submodule update --init --recursive
$ python setup.py install

  9. Register a custom Reader for automatic resolution

    main

    To ensure the AICSImage object can automatically detect and use your new reader, you must register it in the FORMAT_IMPLEMENTATIONS lookup in aicsimageio/formats.py.

    Important: The order of FORMAT_IMPLEMENTATIONS matters. If a generic reader (like TiffReader) is listed before your specific reader (like OmeTiffReader), your reader may never be reached.

  10. Read full images into memory with AICSImage

    main

    Use the AICSImage class to load an entire image scene into memory. This is suitable for images that fit within your available RAM.

    Key properties:

    • .data: Returns a 5D TCZYX numpy array.
    • .xarray_data: Returns a 5D TCZYX xarray data array backed by numpy.
    • .dims: Returns a Dimensions object containing metadata about the axes.
    • .shape: Returns a tuple of dimension sizes in TCZYX order.
    • .get_image_data(dim_order, **kwargs): Returns a specific chunk as a numpy array (e.g., img.get_image_data("CZYX", T=0)).
    from aicsimageio import AICSImage

# 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

  11. Set up AICSImageIO for local development

    main

    To contribute to aicsimageio, follow these steps to set up your local environment:

    1. Fork and clone the repository.
    2. Initialize submodules:
      git submodule update --init --recursive
    3. Install in editable mode with development dependencies:
      pip install -e ".[dev]"
    4. Download test resources:
      python scripts/download_test_resources.py
    5. (Optional) Install pre-commit for automatic linting checks:
      pip install pre-commit
pre-commit install
    git submodule update --init --recursive
pip install -e ".[dev]"
python scripts/download_test_resources.py

  12. Read images from cloud storage (S3, GCS)

    main

    AICSImageIO supports remote reading via fsspec. To read from S3 or Google Cloud Storage, install the corresponding filesystem driver:

    • S3: pip install s3fs
    • GCS: pip install gcsfs

    You can pass filesystem arguments via fs_kwargs.

    from aicsimageio import AICSImage

# Read from S3 with anonymous access
img = AICSImage("s3://my-bucket/my_file.tiff", fs_kwargs=dict(anon=True))

# Read from GCS
img = AICSImage("gcs://my-bucket/my_file.tiff")