Metadata-Version: 2.1
Name: aicsimageio
Version: 3.1.3
Summary: Python library for reading and writing image data with special handlers for bio-formats from Allen Institute for Cell Science.
Home-page: https://github.com/AllenCellModeling/aicsimageio
Author: Allen Institute for Cell Science
Author-email: jacksonb@alleninstitute.org, bowdenm@spu.edu
License: BSD-3-Clause
Keywords: aicsimageio,allen cell,imaging,computational biology
Platform: UNKNOWN
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Education
Classifier: License :: OSI Approved :: BSD License
Classifier: Natural Language :: English
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Requires-Python: >=3.6
Description-Content-Type: text/markdown
Requires-Dist: aicspylibczi (>=2.5.0)
Requires-Dist: dask (>=2.9.0)
Requires-Dist: distributed (>=2.9.3)
Requires-Dist: numpy (>=1.16)
Requires-Dist: imageio (>=2.3.0)
Requires-Dist: lxml (>=4.4.2)
Requires-Dist: tifffile (>=2019.7.26.2)
Requires-Dist: toolz (>=0.10.0)
Provides-Extra: all
Requires-Dist: aicspylibczi (>=2.5.0) ; extra == 'all'
Requires-Dist: dask (>=2.9.0) ; extra == 'all'
Requires-Dist: distributed (>=2.9.3) ; extra == 'all'
Requires-Dist: numpy (>=1.16) ; extra == 'all'
Requires-Dist: imageio (>=2.3.0) ; extra == 'all'
Requires-Dist: lxml (>=4.4.2) ; extra == 'all'
Requires-Dist: tifffile (>=2019.7.26.2) ; extra == 'all'
Requires-Dist: toolz (>=0.10.0) ; extra == 'all'
Requires-Dist: codecov ; extra == 'all'
Requires-Dist: flake8 ; extra == 'all'
Requires-Dist: napari ; extra == 'all'
Requires-Dist: psutil ; extra == 'all'
Requires-Dist: pytest ; extra == 'all'
Requires-Dist: pytest-cov ; extra == 'all'
Requires-Dist: pytest-raises ; extra == 'all'
Requires-Dist: pytest-runner ; extra == 'all'
Requires-Dist: bumpversion (>=0.5.3) ; extra == 'all'
Requires-Dist: coverage (>=5.0a4) ; extra == 'all'
Requires-Dist: flake8 (>=3.7.7) ; extra == 'all'
Requires-Dist: gitchangelog (>=3.0.4) ; extra == 'all'
Requires-Dist: ipython (>=7.5.0) ; extra == 'all'
Requires-Dist: m2r (>=0.2.1) ; extra == 'all'
Requires-Dist: pytest (>=4.3.0) ; extra == 'all'
Requires-Dist: pytest-cov (==2.6.1) ; extra == 'all'
Requires-Dist: pytest-raises (>=0.10) ; extra == 'all'
Requires-Dist: pytest-runner (>=4.4) ; extra == 'all'
Requires-Dist: Sphinx (>=2.0.0b1) ; extra == 'all'
Requires-Dist: sphinx-rtd-theme (>=0.1.2) ; extra == 'all'
Requires-Dist: tox (>=3.5.2) ; extra == 'all'
Requires-Dist: twine (>=1.13.0) ; extra == 'all'
Requires-Dist: wheel (>=0.33.1) ; extra == 'all'
Requires-Dist: altair ; extra == 'all'
Requires-Dist: bokeh ; extra == 'all'
Requires-Dist: jupyterlab ; extra == 'all'
Requires-Dist: matplotlib ; extra == 'all'
Requires-Dist: napari (>=0.2.10) ; extra == 'all'
Requires-Dist: pillow ; extra == 'all'
Provides-Extra: dev
Requires-Dist: bumpversion (>=0.5.3) ; extra == 'dev'
Requires-Dist: coverage (>=5.0a4) ; extra == 'dev'
Requires-Dist: flake8 (>=3.7.7) ; extra == 'dev'
Requires-Dist: gitchangelog (>=3.0.4) ; extra == 'dev'
Requires-Dist: ipython (>=7.5.0) ; extra == 'dev'
Requires-Dist: m2r (>=0.2.1) ; extra == 'dev'
Requires-Dist: pytest (>=4.3.0) ; extra == 'dev'
Requires-Dist: pytest-cov (==2.6.1) ; extra == 'dev'
Requires-Dist: pytest-raises (>=0.10) ; extra == 'dev'
Requires-Dist: pytest-runner (>=4.4) ; extra == 'dev'
Requires-Dist: Sphinx (>=2.0.0b1) ; extra == 'dev'
Requires-Dist: sphinx-rtd-theme (>=0.1.2) ; extra == 'dev'
Requires-Dist: tox (>=3.5.2) ; extra == 'dev'
Requires-Dist: twine (>=1.13.0) ; extra == 'dev'
Requires-Dist: wheel (>=0.33.1) ; extra == 'dev'
Provides-Extra: interactive
Requires-Dist: altair ; extra == 'interactive'
Requires-Dist: bokeh ; extra == 'interactive'
Requires-Dist: jupyterlab ; extra == 'interactive'
Requires-Dist: matplotlib ; extra == 'interactive'
Requires-Dist: napari (>=0.2.10) ; extra == 'interactive'
Requires-Dist: pillow ; extra == 'interactive'
Provides-Extra: setup
Requires-Dist: pytest-runner ; extra == 'setup'
Provides-Extra: test
Requires-Dist: codecov ; extra == 'test'
Requires-Dist: flake8 ; extra == 'test'
Requires-Dist: napari ; extra == 'test'
Requires-Dist: psutil ; extra == 'test'
Requires-Dist: pytest ; extra == 'test'
Requires-Dist: pytest-cov ; extra == 'test'
Requires-Dist: pytest-raises ; extra == 'test'

# AICSImageIO

[![Build Status](https://github.com/AllenCellModeling/aicsimageio/workflows/Build%20Master/badge.svg)](https://github.com/AllenCellModeling/aicsimageio/actions)
[![Documentation](https://github.com/AllenCellModeling/aicsimageio/workflows/Documentation/badge.svg)](https://allencellmodeling.github.io/aicsimageio)
[![Code Coverage](https://codecov.io/gh/AllenCellModeling/aicsimageio/branch/master/graph/badge.svg)](https://codecov.io/gh/AllenCellModeling/aicsimageio)

A Python library for reading and writing image data with specific support for handling bio-formats.

---

## Features
* Supports reading metadata and imaging data for:
    * `CZI`
    * `OME-TIFF`
    * `TIFF`
    * Any additional format supported by [`imageio`](https://github.com/imageio/imageio)
* Supports writing metadata and imaging data for:
    * `OME-TIFF`

## Installation
**Stable Release:** `pip install aicsimageio`<br>
**Development Head:** `pip install git+https://github.com/AllenCellModeling/aicsimageio.git`

## Documentation
For full package documentation please visit
[allencellmodeling.github.io/aicsimageio](https://allencellmodeling.github.io/aicsimageio/index.html).

## Quick Start

### Full Image Reading
```python
from aicsimageio import AICSImage, imread

# Get an AICSImage object
img = AICSImage("my_file.tiff")
img.data  # returns 6D STCZYX numpy array
img.dims  # returns string "STCZYX"
img.shape  # returns tuple of dimension sizes in STCZYX order
img.size("STC")  # returns tuple of dimensions sizes for just STC
img.get_image_data("CZYX", S=0, T=0)  # returns 4D CZYX numpy array

# Get 6D STCZYX numpy array
data = imread("my_file.tiff")
```

### Delayed Image Slice Reading
```python
from aicsimageio import AICSImage, imread_dask

# Get an AICSImage object
img = AICSImage("my_file.tiff")
img.dask_data  # returns 6D STCZYX dask array
img.dims  # returns string "STCZYX"
img.shape  # returns tuple of dimension sizes in STCZYX order
img.size("STC")  # returns tuple of dimensions sizes for just STC
img.get_image_dask_data("CZYX", S=0, T=0)  # returns 4D CZYX dask array

# Read specified portion of dask array
lazy_s0t0 = img.get_image_dask_data("CZYX", S=0, T=0)  # returns 4D CZYX dask array
s0t0 = lazy_s0t0.compute()  # returns 4D CZYX numpy array

# Or use normal numpy array slicing
lazy_data = imread_dask("my_file.tiff")
lazy_s0t0 = lazy_data[0, 0, :]
s0t0 = lazy_s0t0.compute()
```

When using the `dask_data` array, it is important to know when to `compute` or `persist` data and when to keep
chaining computation. [Here is a good rundown on the trade offs.](https://stackoverflow.com/questions/41806850/dask-difference-between-client-persist-and-client-compute#answer-41807160)


### Speed up IO and Processing with Dask Clients and Clusters
If you have already spun up a `distributed.Client` object in your Python process or your processing is running on a
distributed worker, great, you will naturally gain IO and processing gains. If you haven't done that or don't know what
either of those are, there are some utility functions to help construct and manage these for you.

```python
from aicsimageio import AICSImage, dask_utils

# Create a local dask cluster and client for the duration of the context manager
with AICSImage("filename.ome.tiff") as img:
    # do your work like normal
    print(img.dask_data.shape)

# Specify arguments for the local cluster initialization
with AICSImage("filename.ome.tiff", dask_kwargs={"nworkers": 4}) as img:
    # do your work like normal
    print(img.dask_data.shape)

# Connect to a dask client for the duration of the context manager
with AICSImage("filename.ome.tiff", dask_kwargs={"address": "tcp://localhost:12345"}) as img:
    # do your work like normal
    print(img.dask_data.shape)

# Or spawn a local cluster and / or connect to a client outside of a context manager
# This uses the same "address" and dask kwargs as above
# If you pass an address in, it will create and shutdown the client and no cluster will be created.
# Similar to AICSImage, these objects will be connected and useable for the lifespan of the context manager.
with dask_utils.cluster_and_client() as (cluster, client):

    img1 = AICSImage("1.tiff")
    img2 = AICSImage("2.tiff")
    img3 = AICSImage("3.tiff")

    # Do your image processing work
```

_**Note:** The `AICSImage` context manager and the `dask_utils` module require that the processing machine or container
have networking capabilities enabled to function properly._

### Metadata Reading
```python
from aicsimageio import AICSImage

# Get an AICSImage object
img = AICSImage("my_file.tiff")
img.metadata  # returns the metadata object for this image type
img.get_channel_names()  # returns a list of string channel names if found in the metadata
```

### Napari Interactive Viewer
[napari](https://github.com/Napari/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.
```python
from aicsimageio import AICSImage

# Get an AICSImage object
img = AICSImage("my_file.tiff")
img.view_napari()  # launches napari GUI and viewer
```

## Notes
* Image `data` and `dask_data` are always returned as six dimensional in dimension order `STCZYX`
or `Scene`, `Time`, `Channel`, `Z`, `Y`, and `X`.
* Each file format may use a different metadata parser it is dependent on the reader's implementation.
* The `AICSImage` object will only pull the `Scene`, `Time`, `Channel`, `Z`, `Y`, `X` dimensions from the reader.
If your file has dimensions outside of those, use the base reader classes `CziReader`, `OmeTiffReader`, `TiffReader`,
or `DefaultReader`.
* We make some choices for the user based off the image data during `img.view_napari`.
If you don't want this behavior, simply pass the `img.dask_data` into `napari.view_image` instead.

## Development
See [CONTRIBUTING.md](CONTRIBUTING.md) for information related to developing the code.

***Free software: BSD-3-Clause***


