imagecodecs 2024.9.22

快速入门

从Python软件包索引安装imagecodecs包及其所有依赖项。

python -m pip install -U "imagecodecs[all]"

imagecodecs包也可在其他包存储库中使用，例如Anaconda、MSYS2和MacPorts。

有关从源代码构建的需求和说明，请参阅。

有关使用编程接口的示例，请参阅。

源代码和支持可在GitHub上找到。

需求

此版本与以下需求和依赖项进行了测试（其他版本可能也适用）

• CPython 3.10.11, 3.11.9, 3.12.6, 3.13.0rc2 64位

• Numpy 2.1.1

• numcodecs 0.13.0（可选，用于与Zarr兼容的编解码器）

构建需求

• Cython 3.0.11

• brotli 1.1.0

• brunsli 0.1

• bzip2 1.0.8

• c-blosc 1.21.6

• c-blosc2 2.15.1

• charls 2.4.2

• giflib 5.2.2

• jetraw 23.03.16.4

• jxrlib 1.2

• lcms2 2.16

• lerc 4.0.4

• libaec 1.1.3

• libavif 1.1.1（aom 3.10.0, dav1d 1.4.3, rav1e 0.7.1, svt-av1 2.2.1 libyuv main）

• libdeflate 1.21

• libheif 1.18.2（libde265 1.0.15, x265 3.6）

• libjpeg-turbo 3.0.4

• libjxl 0.11.0

• libjxs 2.0.2

• liblzma 5.6.2

• libpng 1.6.44

• libpng-apng 1.6.44

• libtiff 4.7.0

• libultrahdr 1.2.0

• libwebp 1.4.0

• lz4 1.10.0

• lzfse 1.0

• lzham_codec 1.0

• lzokay db2df1f

• mozjpeg 4.1.5

• openjpeg 2.5.2

• pcodec 0.3.1

• snappy 1.2.1

• sperr 0.8.2

• sz3 3.1.8（3.2.0崩溃）

• zfp 1.0.1

• zlib 1.3.1

• zlib-ng 2.2.2

• zopfli 1.0.3

• zstd 1.5.6

受托需求

• bcdec.h 3b29f8f

• bitshuffle 0.5.1

• cfitsio ricecomp.c 已修改

• h5checksum.c 已修改

• jpg_0XC3.cpp 已修改

• liblj92 已修改

• liblzf 3.6

• libspng 0.7.4

• nc4var.c 已修改

• pg_lzcompress.c 已修改

• qoi.h 36190eb

• rgbe.c 已修改

测试需求

• tifffile 2024.9.20

• czifile 2019.7.2

• zarr 2.18.2

• python-blosc 1.11.2

• python-blosc2 2.7.1

• python-brotli 1.0.9

• python-lz4 4.3.3

• python-lzf 0.2.6

• python-snappy 0.7.2

• python-zstd 1.5.5.1

• pyliblzfse 0.4.1

• zopflipy 1.10

修订

2024.9.22

• 通过7644测试。

• 如果可能，使用libjpeg-turbo处理所有无损JPEG位深度（#105）。

• 修复PackBits编码器无法跳过短复制块的问题（#107）。

• 修复JPEG2K编码器留下随机尾随字节的问题（#104）。

• 修复使用自定义bitspersample编码和解码JPEG XL（#102）。

• 改进lzf_decode中的错误处理（#103）。

• 添加基于libultrahdr库的超高清（JPEG_R）编解码器（#108）。

• 添加基于libjxs库的JPEGXS编解码器（仅源代码）。

• 添加基于SZ3库的SZ3编解码器。

• 弃用Python 3.9，支持Python 3.13。

2024.6.1

• 修复sperr_decode中的段错误。

• 修复在具有意外形状的缓冲区中进行strided解码时的段错误（#98）。

• 修复jpeg2k_encoder输出缓冲区过小的问题（#101）。

• 添加基于pcodec库的PCODEC编解码器。

• 支持NumPy 2。

2024.1.1

• 添加8/24位BMP编解码器。

• 添加基于SPERR库的SPERR编解码器。

• 基于lzokay库添加LZO解码器。

• 添加DICOMRLE解码器。

• 在CMS编解码器中启用float16。

• 启用MCT以支持无损JPEG2K编解码器（#88）。

• 在PackBits解码器中忽略填充字节（#86）。

• 修复heif_write_callback错误消息未设置的问题。

• 需要带有issue-420修复的lcms2 2.16。

• 需要libjxl 0.9、libaec 1.1、Cython 3。

2023.9.18

• 使用更新的依赖关系重新构建以修复CVE-2024-4863。

2023.9.4

• 将avif_encode级别参数映射到质量（破坏性）。

• 支持avif_encode中的单色图像。

• 将numthreads参数添加到avif_decode中（修复AVIF的imread）。

• 通过nc4var.c添加量化过滤器（BitGroom、BitRound、GBR）。

• 添加LZ4H5编解码器。

• 支持更多BCn压缩DDS fourcc类型。

• 需要libavif 1.0。

2023.8.12

• 添加EER（电子事件表示）解码器。

• 添加将初始值传递给crc32和adler32校验和函数的选项。

• 通过HDF5的h5checksum.c添加fletcher32和lookup3校验和函数。

• 为numcodecs添加校验和编解码器。

2023.7.10

• 使用优化的编译标志重新构建。

2023.7.4

• 通过bcdec库添加BCn和DDS解码器。

• 添加将JPEG XL转换为JPEG或从JPEG转换为JPEG XL的功能（#78）。

• 添加解码动画WebP中选择帧的选项。

• 在没有libjpeg-turbo 3的情况下构建时使用传统的JPEG8编解码器（#65）。

• 将blosc2_encode的默认值更改为与blosc2-python匹配（破坏性）。

• 修复在具有超过4个样本的情况下写入JPEG2K时的段错误。

• 修复一些编解码器默认返回bytearray的问题。

• 完全实现cfitsio的ricecomp.c。

• 停止支持Python 3.8和numpy < 1.21（NEP29）。

• ……

有关旧版本，请参阅CHANGES文件。

目标

许多科学图像存储格式，如TIFF、CZI、DICOM、HDF和Zarr，都是容器，包含大量小型数据段（块、瓦片、条纹），这些数据段使用各种压缩和预滤波方法进行编码。通常将所有数据段共有的元数据存储在段之外。

Imagecodecs库的目的是支持Python模块编码和解码此类数据段。具体目标包括：

• 提供用于从和到字节或numpy数组编码和解码内存中小型图像数据段的功能，支持许多压缩和过滤方法。

• 支持Python生态系统中的其他地方不可用的图像格式和压缩方法。

• 减少对大量、大型、不合适或不维护的Python包的运行时依赖。Imagecodecs包仅依赖于numpy。

• 如果存在，则将编解码器作为具有C API和宽松许可协议的第三方库的Cython包装器实现。如果不存在，则使用自己的C库。提供包装C库的Cython定义文件。

• 在扩展的本地/C函数调用期间释放Python全局解释器锁（GIL），以支持多线程使用。

访问大型数据段的部分和从段中读取元数据不在本库的范围内。

说明

此库大部分是正在进行中的工作。

API尚不稳定，可能在版本之间发生变化。

不再支持Python <= 3.8。32位版本已弃用。

仅在小端平台上运行。

支持的平台包括win_amd64、win_arm64、win32、macosx_x86_64、macosx_arm64、manylinux_x86_64和manylinux_aarch64。

某些平台和版本可能没有提供wheel。

仅win_amd64 wheels包含所有功能。

目前仅tiff、bcn、dds、dicomrle、eer、lzo、packints和jpegsof3编解码器支持解码。

由于许可证和可能存在的专利使用问题，heif、jetraw和jpegxs编解码器仅作为源代码分发。

在Windows上需要安装最新的Microsoft Visual C++ Redistributable for Visual Studio 2015-2022。

请参阅imagecodecs/licenses文件夹中的第三方库许可证。

本软件部分基于Independent JPEG Group的工作。

在安装imagecodecs之前，请将pip和setuptools更新到最新版本。

python -m pip install -U pip setuptools wheel Cython

在从源代码构建imagecodecs之前，安装所需的工具和库。例如，在最新的Ubuntu Linux发行版中

sudo apt-get install build-essential python3-dev cython3 python3-pip python3-setuptools python3-wheel python3-numpy libdeflate-dev libjpeg-dev libjxr-dev liblcms2-dev liblz4-dev liblerc-dev liblzma-dev libopenjp2-7-dev libpng-dev libtiff-dev libwebp-dev libz-dev libzstd-dev

要从源代码构建和安装imagecodecs，请运行

python -m pip install .

在从源代码构建时，默认禁用了许多扩展。

要定义构建哪些扩展，或修改如库名称和编译器参数之类的构建设置，提供一个imagecodecs_distributor_setup.customize_build函数，该函数在设置期间导入并执行。请参阅setup.py以获取预定义的customize_build函数。

提供成像或压缩编解码器的其他项目：Python zlib、Python bz2、Python lzma、backports.lzma、python-lzo、python-lzw、python-lerc、wavpack-numcodecs、packbits、isa-l.igzip、fpzip、libmng、OpenEXR (EXR、PIZ、PXR24、B44、DWA)、pyJetraw、tinyexr、pytinyexr、pyroexr、JasPer、libjpeg (GPL)、pylibjpeg、pylibjpeg-libjpeg (GPL)、pylibjpeg-openjpeg、pylibjpeg-rle、glymur、pyheif、pyrus-cramjam、PyLZHAM、BriefLZ、QuickLZ (GPL)、LZO (GPL)、nvJPEG、nvJPEG2K、PyTurboJPEG、CCSDS123、LPC-Rice、CompressionAlgorithms、Compressonator、Wuffs、TinyDNG、OpenJPH、Grok (AGPL)、MAFISC、B3D、fo-dicom.Codecs、jpegli。

示例

导入JPEG2K编解码器

>>> from imagecodecs import (
...     jpeg2k_encode,
...     jpeg2k_decode,
...     jpeg2k_check,
...     jpeg2k_version,
...     JPEG2K,
... )

检查JPEG2K编解码器是否包含在imagecodecs构建中

>>> JPEG2K.available
True

打印JPEG2K编解码器底层OpenJPEG库的版本

>>> jpeg2k_version()
'openjpeg 2.5.2'

使用无损JP2格式编码numpy数组

>>> array = numpy.random.randint(100, 200, (256, 256, 3), numpy.uint8)
>>> encoded = jpeg2k_encode(array, level=0)
>>> bytes(encoded[:12])
b'\x00\x00\x00\x0cjP  \r\n\x87\n'

检查编码的字节很可能包含JPEG 2000流

>>> jpeg2k_check(encoded)
True

将JP2编码的字节解码为numpy数组

>>> decoded = jpeg2k_decode(encoded)
>>> numpy.array_equal(decoded, array)
True

将JP2编码的字节解码到现有的numpy数组中

>>> out = numpy.empty_like(array)
>>> _ = jpeg2k_decode(encoded, out=out)
>>> numpy.array_equal(out, array)
True

并非所有编解码器都已完全实现，运行时可能会抛出异常

>>> from imagecodecs import tiff_encode
>>> tiff_encode(array)
Traceback (most recent call last):
 ...
NotImplementedError: tiff_encode

将numpy数组写入JP2文件

>>> from imagecodecs import imwrite, imread
>>> imwrite('_test.jp2', array)

从JP2文件读取图像作为numpy数组

>>> image = imread('_test.jp2')
>>> numpy.array_equal(image, array)
True

创建JPEG 2000压缩的Zarr数组

>>> import zarr
>>> import numcodecs
>>> from imagecodecs.numcodecs import Jpeg2k
>>> numcodecs.register_codec(Jpeg2k)
>>> zarr.zeros(
...     (4, 5, 512, 512, 3),
...     chunks=(1, 1, 256, 256, 3),
...     dtype='u1',
...     compressor=Jpeg2k(),
... )
<zarr.core.Array (4, 5, 512, 512, 3) uint8>

通过tifffile.FileSequence和dask.array访问一系列JP2文件中的图像数据

>>> import tifffile
>>> import dask.array
>>> def jp2_read(filename):
...     with open(filename, 'rb') as fh:
...         data = fh.read()
...     return jpeg2k_decode(data)
...
>>> with tifffile.FileSequence(jp2_read, '*.jp2') as ims:
...     with ims.aszarr() as store:
...         dask.array.from_zarr(store)
...
dask.array<from-zarr, shape=(1, 256, 256, 3)...chunksize=(1, 256, 256, 3)...

以JSON格式将Zarr存储写入fsspec ReferenceFileSystem，并将其作为Zarr数组打开

>>> store.write_fsspec(
...     'temp.json', url='file://', codec_id='imagecodecs_jpeg2k'
... )
>>> import fsspec
>>> mapper = fsspec.get_mapper(
...     'reference://', fo='temp.json', target_protocol='file'
... )
>>> zarr.open(mapper, mode='r')
<zarr.core.Array (1, 256, 256, 3) uint8 read-only>

从命令行查看JP2文件中的图像

python -m imagecodecs _test.jp2