# AICSImageIO
[](https://github.com/AllenCellModeling/aicsimageio/actions)
[](https://AllenCellModeling.github.io/aicsimageio/)
[](https://app.codecov.io/gh/AllenCellModeling/aicsimageio/branch/main)
[](https://doi.org/10.5281/zenodo.4906608)
Image Reading, Metadata Conversion, and Image Writing for Microscopy Images in Pure Python
---
## Features
- 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.](https://github.com/imageio/imageio) -- (`pip install aicsimageio[base-imageio]`)
- Files supported by [Bio-Formats](https://docs.openmicroscopy.org/bio-formats/latest/supported-formats.html) -- (`pip install aicsimageio bioformats_jar`) (Note: requires `java` and `maven`, see below for details.)
- Supports writing metadata and imaging data for:
- `OME-TIFF`
- `PNG`, `GIF`, [etc.](https://github.com/imageio/imageio) -- (`pip install aicsimageio[base-imageio]`)
- Supports reading and writing to
[fsspec](https://github.com/intake/filesystem_spec) supported file systems
wherever possible:
- Local paths (i.e. `my-file.png`)
- HTTP URLs (i.e. `https://my-domain.com/my-file.png`)
- [s3fs](https://github.com/dask/s3fs) (i.e. `s3://my-bucket/my-file.png`)
- [gcsfs](https://github.com/dask/gcsfs) (i.e. `gcs://my-bucket/my-file.png`)
See [Cloud IO Support](#cloud-io-support) for more details.
## Installation
**Stable Release:** `pip install aicsimageio`<br>
**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.
#### Extra Format Installation
TIFF and OME-TIFF reading and writing is always available after
installing `aicsimageio`, 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 with `pip 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 with `pip 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 with `pip install aicsimageio bioformats_jar`. **Important!!** Bio-Formats support also requires a `java` and `mvn` executable in the environment. The simplest method is to install `bioformats_jar` from conda: `conda install -c conda-forge bioformats_jar` (which will additionally bring `openjdk` and `maven` packages).
## Documentation
For full package documentation please visit
[allencellmodeling.github.io/aicsimageio](https://allencellmodeling.github.io/aicsimageio/index.html).
## Quickstart
### Full Image Reading
If your image fits in memory:
```python
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
# Get the id of the current operating scene
img.current_scene
# Get a list valid scene ids
img.scenes
# Change scene using name
img.set_scene("Image:1")
# Or by scene index
img.set_scene(1)
# Use the same operations on a different scene
# ...
```
#### Full Image Reading Notes
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 retrieve
the specified chunk.
### Delayed Image Reading
If your image doesn't fit in memory:
```python
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
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
# 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
# Get the id of the current operating scene
img.current_scene
# Get a list valid scene ids
img.scenes
# Change scene using name
img.set_scene("Image:1")
# Or by scene index
img.set_scene(1)
# Use the same operations on a different scene
# ...
```
#### 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 imaging data into memory until you specifically
call `.compute` on the returned Dask array. In doing so, you will only then load the
selected chunk in-memory.
### Mosaic Image Reading
Read stitched data or single tiles as a dimension.
Readers that support mosaic tile stitching:
- `LifReader`
- `CziReader`
#### AICSImage
If the file format reader supports stitching mosaic tiles together, the
`AICSImage` object will default to stitching the tiles back together.
```python
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:
```python
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 be
available on the `AICSImage` object:
```python
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
```
#### Reader
If the file format reader detects mosaic tiles in the image, the `Reader` object
will store the tiles as a dimension.
If tile stitching is implemented, the `Reader` can also return the stitched image.
```python
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 tiles
reader.mosaic_dask_data # returns stitched mosaic - T, C, Z, big Y, big, X, (S optional)
```
#### Single Tile Absolute Positioning
There are functions available on both the `AICSImage` and `Reader` objects
to help with single tile positioning:
```python
img = AICSImage("very-large-mosaic.lif")
img.mosaic_tile_dims # Returns a Dimensions object with just Y and X dim sizes
img.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 Reading
```python
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 file format (XML, JSON, etc.)
img.channel_names # returns a list of string channel names found in the metadata
img.physical_pixel_sizes.Z # returns the Z dimension pixel size as found in the metadata
img.physical_pixel_sizes.Y # returns the Y dimension pixel size as found in the metadata
img.physical_pixel_sizes.X # returns the X dimension pixel size as found in the metadata
```
### Xarray Coordinate Plane Attachment
If `aicsimageio` finds coordinate information for the spatial-temporal dimensions of
the image in metadata, you can use
[xarray](http://xarray.pydata.org/en/stable/index.html) for indexing by coordinates.
```python
from aicsimageio import AICSImage
# Get an AICSImage object
img = 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 Z
first_ten_mm_in_z = img.xarray_data.loc[:, :, :10]
# Get the first ten major units (usually micrometers, not indices) in Y
first_ten_mm_in_y = img.xarray_data.loc[:, :, :, :10]
# Get the first ten major units (usually micrometers, not indices) in X
first_ten_mm_in_x = img.xarray_data.loc[:, :, :, :, :10]
```
See `xarray`
["Indexing and Selecting Data" Documentation](http://xarray.pydata.org/en/stable/indexing.html)
for more information.
### Cloud IO Support
[File-System Specification (fsspec)](https://github.com/intake/filesystem_spec) 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.
```python
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")
# Or read with specific filesystem creation arguments
img = 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 the
target backend is installed.
- For `s3`: `pip install s3fs`
- For `gs`: `pip install gcsfs`
See the [list of known implementations](https://filesystem-spec.readthedocs.io/en/latest/?badge=latest#implementations).
### Saving to OME-TIFF
The simpliest method to save your image as an OME-TIFF file with key pieces of
metadata is to use the `save` function.
```python
from aicsimageio import AICSImage
AICSImage("my_file.czi").save("my_file.ome.tiff")
```
**Note:** By default `aicsimageio` will 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.
```python
import numpy as np
from aicsimageio.writers import OmeTiffWriter
image = np.random.rand(10, 3, 1024, 2048)
OmeTiffWriter.save(image, "file.ome.tif", dim_order="ZCYX")
```
See
[OmeTiffWriter documentation](./aicsimageio.writers.html#aicsimageio.writers.ome_tiff_writer.OmeTiffWriter.save)
for more details.
#### Other Writers
In most cases, `AICSImage.save` is usually a good default but there are other image
writers available. For more information, please refer to
[our writers documentation](https://allencellmodeling.github.io/aicsimageio/aicsimageio.writers.html).
## Benchmarks
AICSImageIO is benchmarked using [asv](https://asv.readthedocs.io/en/stable/).
You can find the benchmark results for every commit to `main` starting at the 4.0
release on our
[benchmarks page](https://AllenCellModeling.github.io/aicsimageio/_benchmarks/index.html).
## Development
See our
[developer resources](https://allencellmodeling.github.io/aicsimageio/developer_resources)
for information related to developing the code.
## Citation
If you find `aicsimageio` 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:
```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)_
Raw data
{
"_id": null,
"home_page": "https://github.com/AllenCellModeling/aicsimageio",
"name": "aicsimageio",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": "",
"keywords": "imageio,image reading,image writing,metadata,microscopy,allen cell",
"author": "Eva Maxfield Brown, Allen Institute for Cell Science",
"author_email": "evamaxfieldbrown@gmail.com, jamie.sherman@gmail.com, bowdenm@spu.edu",
"download_url": "https://files.pythonhosted.org/packages/17/84/02534b7183e042e37445cfac89307c30505db02d34fceae1639ce5fa8476/aicsimageio-4.14.0.tar.gz",
"platform": null,
"description": "# AICSImageIO\n\n[](https://github.com/AllenCellModeling/aicsimageio/actions)\n[](https://AllenCellModeling.github.io/aicsimageio/)\n[](https://app.codecov.io/gh/AllenCellModeling/aicsimageio/branch/main)\n[](https://doi.org/10.5281/zenodo.4906608)\n\nImage Reading, Metadata Conversion, and Image Writing for Microscopy Images in Pure Python\n\n---\n\n## Features\n\n- Supports reading metadata and imaging data for:\n - `OME-TIFF`\n - `TIFF`\n - `ND2` -- (`pip install aicsimageio[nd2]`)\n - `DV` -- (`pip install aicsimageio[dv]`)\n - `CZI` -- (`pip install aicspylibczi>=3.1.1 fsspec>=2022.8.0`)\n - `LIF` -- (`pip install readlif>=0.6.4`)\n - `PNG`, `GIF`, [etc.](https://github.com/imageio/imageio) -- (`pip install aicsimageio[base-imageio]`)\n - Files supported by [Bio-Formats](https://docs.openmicroscopy.org/bio-formats/latest/supported-formats.html) -- (`pip install aicsimageio bioformats_jar`) (Note: requires `java` and `maven`, see below for details.)\n- Supports writing metadata and imaging data for:\n - `OME-TIFF`\n - `PNG`, `GIF`, [etc.](https://github.com/imageio/imageio) -- (`pip install aicsimageio[base-imageio]`)\n- Supports reading and writing to\n [fsspec](https://github.com/intake/filesystem_spec) supported file systems\n wherever possible:\n\n - Local paths (i.e. `my-file.png`)\n - HTTP URLs (i.e. `https://my-domain.com/my-file.png`)\n - [s3fs](https://github.com/dask/s3fs) (i.e. `s3://my-bucket/my-file.png`)\n - [gcsfs](https://github.com/dask/gcsfs) (i.e. `gcs://my-bucket/my-file.png`)\n\n See [Cloud IO Support](#cloud-io-support) for more details.\n\n## Installation\n\n**Stable Release:** `pip install aicsimageio`<br>\n**Development Head:** `pip install git+https://github.com/AllenCellModeling/aicsimageio.git`\n\nAICSImageIO is supported on Windows, Mac, and Ubuntu.\nFor other platforms, you will likely need to build from source.\n\n#### Extra Format Installation\n\nTIFF and OME-TIFF reading and writing is always available after\ninstalling `aicsimageio`, but extra supported formats can be\noptionally installed using `[...]` syntax.\n\n- For a single additional supported format (e.g. ND2): `pip install aicsimageio[nd2]`\n- For a single additional supported format (e.g. ND2), development head: `pip install \"aicsimageio[nd2] @ git+https://github.com/AllenCellModeling/aicsimageio.git\"`\n- 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\"`\n- For faster OME-TIFF reading with tile tags: `pip install aicsimageio[bfio]`\n- For multiple additional supported formats: `pip install aicsimageio[base-imageio,nd2]`\n- For all additional supported (and openly licensed) formats: `pip install aicsimageio[all]`\n- Due to the GPL license, LIF support is not included with the `[all]` extra, and must be installed manually with `pip install aicsimageio readlif>=0.6.4`\n- Due to the GPL license, CZI support is not included with the `[all]` extra, and must be installed manually with `pip install aicsimageio aicspylibczi>=3.1.1 fsspec>=2022.8.0`\n- Due to the GPL license, Bio-Formats support is not included with the `[all]` extra, and must be installed manually with `pip install aicsimageio bioformats_jar`. **Important!!** Bio-Formats support also requires a `java` and `mvn` executable in the environment. The simplest method is to install `bioformats_jar` from conda: `conda install -c conda-forge bioformats_jar` (which will additionally bring `openjdk` and `maven` packages).\n\n## Documentation\n\nFor full package documentation please visit\n[allencellmodeling.github.io/aicsimageio](https://allencellmodeling.github.io/aicsimageio/index.html).\n\n## Quickstart\n\n### Full Image Reading\n\nIf your image fits in memory:\n\n```python\nfrom aicsimageio import AICSImage\n\n# Get an AICSImage object\nimg = AICSImage(\"my_file.tiff\") # selects the first scene found\nimg.data # returns 5D TCZYX numpy array\nimg.xarray_data # returns 5D TCZYX xarray data array backed by numpy\nimg.dims # returns a Dimensions object\nimg.dims.order # returns string \"TCZYX\"\nimg.dims.X # returns size of X dimension\nimg.shape # returns tuple of dimension sizes in TCZYX order\nimg.get_image_data(\"CZYX\", T=0) # returns 4D CZYX numpy array\n\n# Get the id of the current operating scene\nimg.current_scene\n\n# Get a list valid scene ids\nimg.scenes\n\n# Change scene using name\nimg.set_scene(\"Image:1\")\n# Or by scene index\nimg.set_scene(1)\n\n# Use the same operations on a different scene\n# ...\n```\n\n#### Full Image Reading Notes\n\nThe `.data` and `.xarray_data` properties will load the whole scene into memory.\nThe `.get_image_data` function will load the whole scene into memory and then retrieve\nthe specified chunk.\n\n### Delayed Image Reading\n\nIf your image doesn't fit in memory:\n\n```python\nfrom aicsimageio import AICSImage\n\n# Get an AICSImage object\nimg = AICSImage(\"my_file.tiff\") # selects the first scene found\nimg.dask_data # returns 5D TCZYX dask array\nimg.xarray_dask_data # returns 5D TCZYX xarray data array backed by dask array\nimg.dims # returns a Dimensions object\nimg.dims.order # returns string \"TCZYX\"\nimg.dims.X # returns size of X dimension\nimg.shape # returns tuple of dimension sizes in TCZYX order\n\n# Pull only a specific chunk in-memory\nlazy_t0 = img.get_image_dask_data(\"CZYX\", T=0) # returns out-of-memory 4D dask array\nt0 = lazy_t0.compute() # returns in-memory 4D numpy array\n\n# Get the id of the current operating scene\nimg.current_scene\n\n# Get a list valid scene ids\nimg.scenes\n\n# Change scene using name\nimg.set_scene(\"Image:1\")\n# Or by scene index\nimg.set_scene(1)\n\n# Use the same operations on a different scene\n# ...\n```\n\n#### Delayed Image Reading Notes\n\nThe `.dask_data` and `.xarray_dask_data` properties and the `.get_image_dask_data`\nfunction will not load any piece of the imaging data into memory until you specifically\ncall `.compute` on the returned Dask array. In doing so, you will only then load the\nselected chunk in-memory.\n\n### Mosaic Image Reading\n\nRead stitched data or single tiles as a dimension.\n\nReaders that support mosaic tile stitching:\n\n- `LifReader`\n- `CziReader`\n\n#### AICSImage\n\nIf the file format reader supports stitching mosaic tiles together, the\n`AICSImage` object will default to stitching the tiles back together.\n\n```python\nimg = AICSImage(\"very-large-mosaic.lif\")\nimg.dims.order # T, C, Z, big Y, big X, (S optional)\nimg.dask_data # Dask chunks fall on tile boundaries, pull YX chunks out of the image\n```\n\nThis behavior can be manually turned off:\n\n```python\nimg = AICSImage(\"very-large-mosaic.lif\", reconstruct_mosaic=False)\nimg.dims.order # M (tile index), T, C, Z, small Y, small X, (S optional)\nimg.dask_data # Chunks use normal ZYX\n```\n\nIf the reader does not support stitching tiles together the M tile index will be\navailable on the `AICSImage` object:\n\n```python\nimg = AICSImage(\"some-unsupported-mosaic-stitching-format.ext\")\nimg.dims.order # M (tile index), T, C, Z, small Y, small X, (S optional)\nimg.dask_data # Chunks use normal ZYX\n```\n\n#### Reader\n\nIf the file format reader detects mosaic tiles in the image, the `Reader` object\nwill store the tiles as a dimension.\n\nIf tile stitching is implemented, the `Reader` can also return the stitched image.\n\n```python\nreader = LifReader(\"ver-large-mosaic.lif\")\nreader.dims.order # M, T, C, Z, tile size Y, tile size X, (S optional)\nreader.dask_data # normal operations, can use M dimension to select individual tiles\nreader.mosaic_dask_data # returns stitched mosaic - T, C, Z, big Y, big, X, (S optional)\n```\n\n#### Single Tile Absolute Positioning\n\nThere are functions available on both the `AICSImage` and `Reader` objects\nto help with single tile positioning:\n\n```python\nimg = AICSImage(\"very-large-mosaic.lif\")\nimg.mosaic_tile_dims # Returns a Dimensions object with just Y and X dim sizes\nimg.mosaic_tile_dims.Y # 512 (for example)\n\n# Get the tile start indices (top left corner of tile)\ny_start_index, x_start_index = img.get_mosaic_tile_position(12)\n```\n\n### Metadata Reading\n\n```python\nfrom aicsimageio import AICSImage\n\n# Get an AICSImage object\nimg = AICSImage(\"my_file.tiff\") # selects the first scene found\nimg.metadata # returns the metadata object for this file format (XML, JSON, etc.)\nimg.channel_names # returns a list of string channel names found in the metadata\nimg.physical_pixel_sizes.Z # returns the Z dimension pixel size as found in the metadata\nimg.physical_pixel_sizes.Y # returns the Y dimension pixel size as found in the metadata\nimg.physical_pixel_sizes.X # returns the X dimension pixel size as found in the metadata\n```\n\n### Xarray Coordinate Plane Attachment\n\nIf `aicsimageio` finds coordinate information for the spatial-temporal dimensions of\nthe image in metadata, you can use\n[xarray](http://xarray.pydata.org/en/stable/index.html) for indexing by coordinates.\n\n```python\nfrom aicsimageio import AICSImage\n\n# Get an AICSImage object\nimg = AICSImage(\"my_file.ome.tiff\")\n\n# Get the first ten seconds (not frames)\nfirst_ten_seconds = img.xarray_data.loc[:10] # returns an xarray.DataArray\n\n# Get the first ten major units (usually micrometers, not indices) in Z\nfirst_ten_mm_in_z = img.xarray_data.loc[:, :, :10]\n\n# Get the first ten major units (usually micrometers, not indices) in Y\nfirst_ten_mm_in_y = img.xarray_data.loc[:, :, :, :10]\n\n# Get the first ten major units (usually micrometers, not indices) in X\nfirst_ten_mm_in_x = img.xarray_data.loc[:, :, :, :, :10]\n```\n\nSee `xarray`\n[\"Indexing and Selecting Data\" Documentation](http://xarray.pydata.org/en/stable/indexing.html)\nfor more information.\n\n### Cloud IO Support\n\n[File-System Specification (fsspec)](https://github.com/intake/filesystem_spec) allows\nfor common object storage services (S3, GCS, etc.) to act like normal filesystems by\nfollowing the same base specification across them all. AICSImageIO utilizes this\nstandard specification to make it possible to read directly from remote resources when\nthe specification is installed.\n\n```python\nfrom aicsimageio import AICSImage\n\n# Get an AICSImage object\nimg = AICSImage(\"http://my-website.com/my_file.tiff\")\nimg = AICSImage(\"s3://my-bucket/my_file.tiff\")\nimg = AICSImage(\"gcs://my-bucket/my_file.tiff\")\n\n# Or read with specific filesystem creation arguments\nimg = AICSImage(\"s3://my-bucket/my_file.tiff\", fs_kwargs=dict(anon=True))\nimg = AICSImage(\"gcs://my-bucket/my_file.tiff\", fs_kwargs=dict(anon=True))\n\n# All other normal operations work just fine\n```\n\nRemote reading requires that the file-system specification implementation for the\ntarget backend is installed.\n\n- For `s3`: `pip install s3fs`\n- For `gs`: `pip install gcsfs`\n\nSee the [list of known implementations](https://filesystem-spec.readthedocs.io/en/latest/?badge=latest#implementations).\n\n### Saving to OME-TIFF\n\nThe simpliest method to save your image as an OME-TIFF file with key pieces of\nmetadata is to use the `save` function.\n\n```python\nfrom aicsimageio import AICSImage\n\nAICSImage(\"my_file.czi\").save(\"my_file.ome.tiff\")\n```\n\n**Note:** By default `aicsimageio` will generate only a portion of metadata to pass\nalong from the reader to the OME model. This function currently does not do a full\nmetadata translation.\n\nFor finer grain customization of the metadata, scenes, or if you want to save an array\nas an OME-TIFF, the writer class can also be used to customize as needed.\n\n```python\nimport numpy as np\nfrom aicsimageio.writers import OmeTiffWriter\n\nimage = np.random.rand(10, 3, 1024, 2048)\nOmeTiffWriter.save(image, \"file.ome.tif\", dim_order=\"ZCYX\")\n```\n\nSee\n[OmeTiffWriter documentation](./aicsimageio.writers.html#aicsimageio.writers.ome_tiff_writer.OmeTiffWriter.save)\nfor more details.\n\n#### Other Writers\n\nIn most cases, `AICSImage.save` is usually a good default but there are other image\nwriters available. For more information, please refer to\n[our writers documentation](https://allencellmodeling.github.io/aicsimageio/aicsimageio.writers.html).\n\n## Benchmarks\n\nAICSImageIO is benchmarked using [asv](https://asv.readthedocs.io/en/stable/).\nYou can find the benchmark results for every commit to `main` starting at the 4.0\nrelease on our\n[benchmarks page](https://AllenCellModeling.github.io/aicsimageio/_benchmarks/index.html).\n\n## Development\n\nSee our\n[developer resources](https://allencellmodeling.github.io/aicsimageio/developer_resources)\nfor information related to developing the code.\n\n## Citation\n\nIf you find `aicsimageio` useful, please cite this repository as:\n\n> 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\n\nbibtex:\n\n```bibtex\n@misc{aicsimageio,\n author = {Brown, Eva Maxfield and Toloudis, Dan and Sherman, Jamie and Swain-Bowden, Madison and Lambert, Talley and {AICSImageIO Contributors}},\n title = {AICSImageIO: Image Reading, Metadata Conversion, and Image Writing for Microscopy Images in Pure Python},\n year = {2021},\n publisher = {GitHub},\n url = {https://github.com/AllenCellModeling/aicsimageio}\n}\n```\n\n_Free software: BSD-3-Clause_\n\n_(The LIF component is licensed under GPLv3 and is not included in this package)_\n_(The Bio-Formats component is licensed under GPLv2 and is not included in this package)_\n_(The CZI component is licensed under GPLv3 and is not included in this package)_\n",
"bugtrack_url": null,
"license": "BSD-3-Clause",
"summary": "Image Reading, Metadata Conversion, and Image Writing for Microscopy Images in Pure Python",
"version": "4.14.0",
"project_urls": {
"Homepage": "https://github.com/AllenCellModeling/aicsimageio"
},
"split_keywords": [
"imageio",
"image reading",
"image writing",
"metadata",
"microscopy",
"allen cell"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "d6d92ee5b3136cab29904a2816d40ace37236fcf47081976705087d12230ec2e",
"md5": "96174741931f7ca49fa4c126771fcc63",
"sha256": "b3df2beba7d000c35660816116d562bfe96ed2beb79713b023a7579e5e72c646"
},
"downloads": -1,
"filename": "aicsimageio-4.14.0-py2.py3-none-any.whl",
"has_sig": false,
"md5_digest": "96174741931f7ca49fa4c126771fcc63",
"packagetype": "bdist_wheel",
"python_version": "py2.py3",
"requires_python": ">=3.9",
"size": 138652,
"upload_time": "2023-11-01T21:55:22",
"upload_time_iso_8601": "2023-11-01T21:55:22.017355Z",
"url": "https://files.pythonhosted.org/packages/d6/d9/2ee5b3136cab29904a2816d40ace37236fcf47081976705087d12230ec2e/aicsimageio-4.14.0-py2.py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "178402534b7183e042e37445cfac89307c30505db02d34fceae1639ce5fa8476",
"md5": "d74a71df5ca234c7a0e31bf84d63f339",
"sha256": "0f6684587b1d833ce5b10f3e81314e2a89269cd94bd09747fcd6460f3119855c"
},
"downloads": -1,
"filename": "aicsimageio-4.14.0.tar.gz",
"has_sig": false,
"md5_digest": "d74a71df5ca234c7a0e31bf84d63f339",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 125582,
"upload_time": "2023-11-01T21:55:24",
"upload_time_iso_8601": "2023-11-01T21:55:24.482342Z",
"url": "https://files.pythonhosted.org/packages/17/84/02534b7183e042e37445cfac89307c30505db02d34fceae1639ce5fa8476/aicsimageio-4.14.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-11-01 21:55:24",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "AllenCellModeling",
"github_project": "aicsimageio",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"tox": true,
"lcname": "aicsimageio"
}
JSON
