aicspylibczi

一个Python模块，用于公开libCZI功能，用于读取（部分）Zeiss CZI文件和元数据。我们目前仅支持64位架构，如果您急需32位支持，请提出问题或修改源代码，并为您的用例构建它。

用法

第一个示例展示了如何处理标准CZI文件（单个或多个场景）。第二个示例展示了如何处理马赛克CZI文件。

示例1：读取czi并选择图像的一部分进行显示

import numpy as np
from aicspylibczi import CziFile
from pathlib import Path
import matplotlib.pyplot as plt

pth = Path('20190610_S02-02.czi')
czi = CziFile(pth)

# Get the shape of the data, the coordinate pairs are (start index, size)
dimensions = czi.get_dims_shape()  # [{'X': (0, 1900), 'Y': (0, 1300), 'Z': (0, 60), 'C': (0, 4), 'S': (0, 40), 'B': (0, 1)}]

czi.dims  # BSCZYX

czi.size  # (1, 40, 4, 60, 1300, 1900)

# Load the image slice I want from the file
img, shp = czi.read_image(S=13, Z=16)


# shp = [('B', 1), ('S', 1), ('C', 4), ('Z', 1), ('Y', 1300), ('X', 1900)]  # List[(Dimension, size), ...]
# img.shape = (1, 1, 4, 1, 1300, 1900)   # numpy.ndarray

# define helper functions
def norm_by(x, min_, max_):
    norms = np.percentile(x, [min_, max_])
    i2 = np.clip((x - norms[0]) / (norms[1] - norms[0]), 0, 1)
    return i2


def recolor(im):  # transform from rgb to cyan-magenta-yellow
    im_shape = np.array(im.shape)
    color_transform = np.array([[1, 1, 0], [0, 1, 1], [1, 0, 1]]).T
    im_reshape = im.reshape([np.prod(im_shape[0:2]), im_shape[2]]).T
    im_recolored = np.matmul(color_transform.T, im_reshape).T
    im_shape[2] = 3
    im = im_recolored.reshape(im_shape)
    return im


# normalize, combine into RGB and transform to CMY
c1 = (norm_by(img[0, 0, 0, 0, 0:750, 250:1000], 50, 99.8) * 255).astype(np.uint8)
c2 = (norm_by(img[0, 0, 1, 0, 0:750, 250:1000], 50, 99.8) * 255).astype(np.uint8)
c3 = (norm_by(img[0, 0, 2, 0, 0:750, 250:1000], 0, 100) * 255).astype(np.uint8)
rgb = np.stack((c1, c2, c3), axis=2)
cmy = np.clip(recolor(rgb), 0, 255)

# plot using matplotlib¶
plt.figure(figsize=(10, 10))
plt.imshow(cmy)
plt.axis('off')

示例2：读取马赛克文件

import numpy as np
import aicspylibczi
import pathlib
from PIL import Image

mosaic_file = pathlib.Path('mosaic_test.czi')
czi = aicspylibczi.CziFile(mosaic_file)

# Get the shape of the data
dimensions = czi.dims  # 'STCZMYX'

czi.size  # (1, 1, 1, 1, 2, 624, 924)

czi.get_dims_shape()  # [{'X': (0, 924), 'Y': (0, 624), 'Z': (0, 1), 'C': (0, 1), 'T': (0, 1), 'M': (0, 2), 'S': (0, 1)}]

czi.is_mosaic()  # True
# Mosaic files ignore the S dimension and use an internal mIndex to reconstruct, the scale factor allows one to generate a manageable image
mosaic_data = czi.read_mosaic(C=0, scale_factor=1)

mosaic_data.shape  # (1, 1, 624, 1756)
# the C channel has been specified S & M are used internally for position so this is (T, Z, Y, X)

normed_mosaic_data = norm_by(mosaic_data[0, 0, :, :], 5, 98) * 255
img = Image.fromarray(normed_mosaic_data.astype(np.uint8))

安装

首选的安装方法是使用pip install。这将安装aicspylibczi Python模块和扩展二进制文件（托管在PyPI上）

pip安装aicspylibczi

如果不起作用：请调查以下内容（通常是Windows问题）

• 您的操作系统是64位 - 我们仅支持64位二进制文件
• 您的Python是64位应用程序（不是32位）
• 您的C++运行库是否最新？ vc_redist.exe

如果您已尝试此方法但仍有困难，请与我们联系，我们将努力帮助您。

文档

文档可在github.io找到。

构建

使用以下步骤在本地构建和安装aicspylibczi

• 克隆包括子模块的存储库（--recurse-submodules）。
• 要求
  • libCZI需要与c++11兼容的编译器。使用clang构建和测试。
  • 开发需求包括为libCZI所需的内容：libpng，zlib
  • 安装包

    pip install .
    pip install -e .[dev] # for development (-e means editable so changes take effect when made)
    pip install .[all] # for everything including jupyter notebook to work with the Example_Usage above
    

  • libCZI作为子模块自动构建，并静态链接到aicspylibczi中。
• 注意：如果在Windows上直接收到以下消息，您需要将PYTHONHOME设置为编译的python.exe所在的文件夹。

EXEC : Fatal Python error : initfsencoding: unable to load the file system codec ...
ModuleNotFoundError: No module named 'encodings'

已知问题

• 在使用read_mosaic时，如果scale_factor不是1.0，Zeiss的libCZI在某些文件中可能会无法渲染复合镶嵌图像中的某些子块。目前尚不清楚这是文件问题还是libCZI的问题。

历史

aicspylibczi最初是Paul Watkins开发的pylibczi的分支，专注于mSEM数据。在尝试将工作扩展到其他领域时，我们转向了pybind11，实现了C++和Python测试，通过github actions添加了持续集成，并添加了读取单个子块和子块堆栈作为numpy.ndarray的功能。还添加了元数据读取，包括特定子块元数据读取。

一旦我们将新的工作与原始工作集成，我们打算将这项工作合并回原始项目。

许可证和致谢

该项目是根据历史部分中所述的pylibczi的分支创建的，Paul Watkins也是我们的仓库开发者。Pylibczi来自欧洲高级研究与学习中心，核心依赖libCZI，受GPLv3许可证的保护。

GPLv3许可证是libCZI导致的，强制执行GPLv3。如果您希望在商业产品中使用libCZI或此衍生产品，您可能需要与蔡司和CAESAR联系。关于GPLv3的讨论。