AICSImageIO

纯Python实现的显微镜图像的图像读取、元数据转换和图像写入

功能

• 支持读取

  • 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, 等。 -- (pip install aicsimageio[base-imageio])
  • 由Bio-Formats支持的文件格式 -- (pip install aicsimageio bioformats_jar) (注意：需要java和maven，详情请见下文。)

• 支持写入

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

• 尽可能支持读取和写入fsspec支持的文件系统

  • 本地路径（例如 my-file.png）
  • HTTP URL（例如 https://my-domain.com/my-file.png）
  • s3fs（例如 s3://my-bucket/my-file.png）
  • gcsfs（例如 gcs://my-bucket/my-file.png）

  有关更多详细信息，请参阅云IO支持。

安装

稳定版本: pip install aicsimageio
开发版本: pip install git+https://github.com/AllenCellModeling/aicsimageio.git

AICSImageIO 支持在 Windows、Mac 和 Ubuntu 上运行。对于其他平台，你可能需要从源代码构建。

额外格式安装

安装 aicsimageio 后，始终可以使用 TIFF 和 OME-TIFF 进行读写，但可以通过 [...] 语法选择性地安装额外的支持格式。

• 对于单个额外的支持格式（例如 ND2）：pip install aicsimageio[nd2]
• 对于单个额外的支持格式（例如 ND2），开发头：pip install "aicsimageio[nd2] @ git+https://github.com/AllenCellModeling/aicsimageio.git"
• 对于单个额外的支持格式（例如 ND2），特定标签（例如 v4.0.0.dev6）：pip install "aicsimageio[nd2] @ git+https://github.com/AllenCellModeling/aicsimageio.git@v4.0.0.dev6"
• 为了使用带有瓦片标签的更快 OME-TIFF 读取：pip install aicsimageio[bfio]
• 对于多个额外的支持格式：pip install aicsimageio[base-imageio,nd2]
• 对于所有额外的支持（和开源许可）格式：pip install aicsimageio[all]
• 由于 GPL 许可证，LIF 支持不包括在 [all] 额外组件中，并且必须使用 pip install aicsimageio readlif>=0.6.4 手动安装。
• 由于 GPL 许可证，CZI 支持不包括在 [all] 额外组件中，并且必须使用 pip install aicsimageio aicspylibczi>=3.1.1 fsspec>=2022.8.0 手动安装。
• 由于 GPL 许可证，Bio-Formats 支持不包括在 [all] 额外组件中，并且必须使用 pip install aicsimageio bioformats_jar 手动安装。 重要!! Bio-Formats 支持还要求环境中存在 java 和 mvn 可执行文件。最简单的方法是从 conda 安装 bioformats_jar：conda install -c conda-forge bioformats_jar（这将额外引入 openjdk 和 maven 软件包）。

文档

有关完整包文档，请访问 allencellmodeling.github.io/aicsimageio。

快速入门

完整图像读取

如果您的图像适合内存

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

完整图像读取说明

.data 和 .xarray_data 属性将整个场景加载到内存中。.get_image_data 函数将整个场景加载到内存中，然后检索指定的块。

延迟图像读取

如果您的图像不适合内存

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

延迟图像读取说明

.dask_data 和 .xarray_dask_data 属性以及 .get_image_dask_data 函数不会在您特别调用返回的 Dask 数组上的 .compute 方法之前将任何图像数据块加载到内存中。在这样做的时候，您将只加载所选块到内存中。

马赛克图像读取

将拼接数据或单个瓦片作为维度读取。

支持马赛克瓦片拼接的读取器

• LifReader
• CziReader

AICSImage

如果文件格式读取器支持将马赛克瓦片拼接在一起，则 AICSImage 对象将默认将瓦片重新拼接。

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

此行为可以手动关闭

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

如果读取器不支持将瓦片拼接在一起，则 M 瓦片索引将在 AICSImage 对象上可用

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 对象将存储瓦片作为维度。

如果实现了瓦片拼接，则 Reader 还可以返回拼接的图像。

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)

单个瓦片绝对定位

在 AICSImage 和 Reader 对象上都有函数可以帮助进行单个瓦片定位

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)

元数据读取

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 坐标平面附件

如果 aicsimageio 在元数据中找到图像空间-时间维度的坐标信息，则可以使用 xarray 进行坐标索引。

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]

有关更多信息，请参阅 xarray 的 "索引和选择数据" 文档。

云 I/O 支持

文件系统规范（fsspec）允许常见的对象存储服务（如S3、GCS等）通过遵循所有这些服务中的相同基本规范，表现得像普通文件系统。AICSImageIO利用这个标准规范，使得在安装规范后，可以直接从远程资源读取。

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

远程读取需要安装目标后端对应的文件系统规范实现。

• 对于s3： pip install s3fs
• 对于gs： pip install gcsfs

请参阅已知实现列表。

保存为OME-TIFF

将图像保存为包含关键元数据的OME-TIFF文件的最简单方法是使用save函数。

from aicsimageio import AICSImage

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

注意：默认情况下，aicsimageio将只生成部分元数据，从读取器传递到OME模型。此函数目前不执行完整的元数据转换。

为了更精细地定制元数据、场景，或者如果您想将数组保存为OME-TIFF，也可以使用写入类进行所需的自定义。

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

有关详细信息，请参阅OmeTiffWriter文档。

其他写入器

在大多数情况下，AICSImage.save通常是好的默认设置，但还有其他图像写入器可用。有关更多信息，请参阅我们的写入器文档。

基准测试

AICSImageIO使用asv进行基准测试。您可以在我们的基准测试页面上找到从4.0版本开始的所有对main提交的基准测试结果。

开发

有关开发代码的信息，请参阅我们的开发者资源。

引用

如果您觉得aicsimageio很有用，请引用此存储库如下：

Eva Maxfield Brown, Dan Toloudis, Jamie Sherman, Madison Swain-Bowden, Talley Lambert, AICSImageIO贡献者（2021）。AICSImageIO：纯Python中显微镜图像的图像读取、元数据转换和图像写入[计算机软件]。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}
}

免费软件：BSD-3-Clause

（LIF组件受GPLv3许可，不包括在此包中） （Bio-Formats组件受GPLv2许可，不包括在此包中） （CZI组件受GPLv3许可，不包括在此包中）