Image transformation, compression, and decompression codecs

Imagecodecs is a Python library that provides block-oriented, in-memory buffer transformation, compression, and decompression functions for use in Tifffile, Czifile, Zarr, kerchunk, and other scientific image input/output packages.

Decode and/or encode functions are implemented for Zlib (DEFLATE), GZIP, ZStandard (ZSTD), Blosc, Brotli, Snappy, LZMA, BZ2, LZ4, LZ4F, LZ4HC, LZW, LZF, LZFSE, LZHAM, PGLZ (PostgreSQL LZ), RCOMP (Rice), ZFP, AEC, SZIP, LERC, NPY, PNG, APNG, GIF, TIFF, WebP, QOI, JPEG 8-bit, JPEG 12-bit, Lossless JPEG (LJPEG, LJ92, JPEGLL), JPEG 2000 (JP2, J2K), JPEG LS, JPEG XL, JPEG XR (WDP, HD Photo), MOZJPEG, AVIF, HEIF, RGBE (HDR), Jetraw, PackBits, Packed Integers, Delta, XOR Delta, Floating Point Predictor, Bitorder reversal, Byteshuffle, Bitshuffle, CMS (color space transformations), and Float24 (24-bit floating point).

Author:	Christoph Gohlke
License:	BSD 3-Clause
Version:	2023.3.16
DOI:	10.5281/zenodo.6915978

Quickstart

Install the imagecodecs package and all dependencies from the Python Package Index:

python -m pip install -U imagecodecs[all]

Imagecodecs is also available in other package repositories such as Anaconda, MSYS2, and MacPorts.

See Requirements and Notes for building from source.

See Examples for using the programming interface.

Source code and support are available on GitHub.

Requirements

This revision was tested with the following requirements and dependencies (other versions may work):

• CPython 3.8.10, 3.9.13, 3.10.10, 3.11.2, 64-bit
• Numpy 1.23.5

Build requirements:

• Cython 0.29.33
• brotli 1.0.9
• brunsli 0.1
• bzip2 1.0.8
• c-blosc 1.21.3
• c-blosc2 2.7.1
• cfitsio 3.49
• charls 2.4.1
• giflib 5.2.1
• jetraw 22.02.16.1
• jxrlib 1.1
• lcms 2.15
• lerc 4.0.0
• libaec 1.0.6
• libavif 0.11.1 (aom 3.6.0, dav1d 1.1.0, rav1e 0.6.3, svt-av1 1.4.1)
• libdeflate 1.17
• libheif 1.15.1 (libde265 1.0.11, x265 3.5)
• libjpeg-turbo 2.1.91
• libjxl 0.8.1
• libpng 1.6.39
• libpng-apng 1.6.39
• libtiff 4.5.0
• libwebp 1.3.0
• lz4 1.9.4
• lzfse 1.0
• lzham_codec 1.0
• mozjpeg 4.1.1
• openjpeg 2.5.0
• snappy 1.1.10
• xz 5.4.1
• zfp 1.0.0
• zlib 1.2.13
• zlib-ng 2.0.6
• zopfli 1.0.3
• zstd 1.5.4

Vendored requirements:

• bitshuffle 0.5.1
• jpg_0XC3.cpp modified
• liblj92 modified
• liblzf 3.6
• libspng 0.7.3
• pg_lzcompress.c modified
• qoi.h c3dcfe7
• rgbe.c modified

Test requirements:

• tifffile 2023.3.15
• czifile 2019.7.2
• zarr 2.14.2
• numcodecs 0.11.0
• bitshuffle 0.5.1
• python-blosc 1.11.1
• python-blosc2 2.1.1
• python-brotli 1.0.9
• python-lz4 4.3.2
• python-lzf 0.2.4
• python-snappy 0.6.1
• python-zstd 1.5.4.0
• pyliblzfse 0.4.1
• zopflipy 1.8

Revisions

2023.3.16

• Pass 6884 tests.
• Require libjpeg-turbo 2.1.91 (3.0 beta) and c-blosc2 2.7.1.
• Add experimental type hints.
• Add SZIP codec via libaec library.
• Use Zstd streaming API to decode blocks with unknown decompressed size.
• Remove unused level, index, and numthreads parameters (breaking).
• Make AEC and BLOSC constants enums (breaking).
• Capitalize numcodecs class names (breaking).
• Remove JPEG12 codec (breaking; use JPEG8 instead).
• Encode and decode lossless and 12-bit JPEG with JPEG8 codec by default.
• Remove JPEGSOF3 fallback in JPEG codec.
• Fix slow IFD seeking with libtiff 4.5.
• Fixes for Cython 3.0.

2023.1.23

• Require libjxl 0.8.
• Change mapping of level to distance parameter in jpegxl_encode.
• Add option to specify bitspersample in jpegxl_encode.
• Add option to pass de/linearize tables to LJPEG codec.
• Fix lj92 decoder for SSSS=16 (#59).
• Prefer ljpeg over jpegsof3 codec.
• Add option to specify AVIF encoder codec.
• Support LERC with Zstd or Deflate compression.
• Squeeze chunk arrays by default in numcodecs image compression codecs.

2022.12.24

• Pass 6512 tests.
• Fix PNG codec error handling.
• Fix truncated transferfunctions in cms_profile (#57).
• Fix exceptions not raised in cdef functions not returning Python object.

2022.12.22

• Require libtiff 4.5.
• Require libavif 0.11.
• Change jpegxl_encode level parameter to resemble libjpeg quality (breaking).
• Add LZFSE codec via lzfse library.
• Add LZHAM codec via lzham library.
• Fix AttributeError in cms_profile (#52).
• Support gamma argument in cms_profile (#53).
• Raise limit of TIFF pages to 1048576.
• Use libtiff thread-safe error/warning handlers.
• Add option to specify filters and strategy in png_encode.
• Add option to specify integrity check type in lzma_encode.
• Fix DeprecationWarning with NumPy 1.24.
• Support Python 3.11 and win-arm64.

2022.9.26

• Support JPEG XL multi-channel (planar grayscale only) and multi-frame.
• Require libjxl 0.7.
• Switch to Blosc2 API and require c-blosc 2.4 (breaking).
• Return LogLuv encoded TIFF as float32.
• Add RGBE codec via rgbe.c.

2022.8.8

• Drop support for libjpeg.
• Fix encoding JPEG in RGB color space.
• Require ZFP 1.0.

2022.7.31

• Add option to decode WebP as RGBA.
• Add option to specify WebP compression method.
• Use exact lossless WebP encoding.

2022.7.27

• Add LZW encoder.
• Add QOI codec via qoi.h (#37).
• Add HEIF codec via libheif (source only; #33).
• Add JETRAW codec via Jetraw demo (source only).
• Add ByteShuffle codec, a generic version of FloatPred.
• Replace imcd_floatpred by imcd_byteshuffle (breaking).
• Use bool type in imcd (breaking).

2022.2.22

• ...

Refer to the CHANGES file for older revisions.

Objectives

Many scientific image storage formats like TIFF, CZI, DICOM, HDF, and Zarr are containers that hold large numbers of small data segments (chunks, tiles, stripes), which are encoded using a variety of compression and pre-filtering methods. Metadata common to all data segments are typically stored separately.

The purpose of the Imagecodecs library is to support Python modules in encoding and decoding such data segments. The specific aims are:

• Provide functions for encoding and decoding small image data segments in-memory (not in-file) from and to bytes or numpy arrays for many compression and filtering methods.
• Support image formats and compression methods not available elsewhere in the Python ecosystem.
• Reduce the runtime dependency on numerous, large, inapt, or unmaintained Python packages. The imagecodecs package only depends on numpy.
• Implement codecs as Cython wrappers of 3rd party libraries with a C API and permissive license if exists, else use own C library. Provide Cython definition files for the wrapped C libraries.
• Release the Python global interpreter lock (GIL) during extended native/C function calls for multi-threaded use.

Accessing parts of large data segments and reading metadata from segments are out of the scope of this library.

Notes

This library is largely a work in progress.

The API is not stable yet and might change between revisions.

Python <= 3.7 is no longer supported. 32-bit versions are deprecated.

Works on little-endian platforms only.

Only win_amd64 wheels include all features.

The tiff, packints, and jpegsof3 codecs are currently decode-only.

The heif and jetraw codecs are distributed as source code only due to license and possible patent usage issues.

The latest Microsoft Visual C++ Redistributable for Visual Studio 2015-2022 is required on Windows.

Refer to the imagecodecs/licenses folder for 3rd-party library licenses.

This software is based in part on the work of the Independent JPEG Group.

Wheels for macOS may not be available for the latest releases.

Build instructions for manylinux and macOS courtesy of Grzegorz Bokota.

Update pip and setuptools to the latest version before installing imagecodecs:

python -m pip install -U pip setuptools wheel Cython

Install the requirements for building imagecodecs from source code on latest Ubuntu Linux distributions:

sudo apt-get install build-essential python3-dev cython3 python3-setuptools python3-pip python3-wheel python3-numpy python3-zarr python3-pytest python3-blosc python3-brotli python3-snappy python3-lz4 libz-dev libblosc-dev liblzma-dev liblz4-dev libzstd-dev libpng-dev libwebp-dev libbz2-dev libopenjp2-7-dev libjpeg-dev libjxr-dev liblcms2-dev libcharls-dev libaec-dev libbrotli-dev libsnappy-dev libzopfli-dev libgif-dev libtiff-dev libdeflate-dev libavif-dev libheif-dev libcfitsio-dev

Use the --lite build option to only build extensions without 3rd-party dependencies. Use the --skip-extension build options to skip building specific extensions, e.g.:

python -m pip install imagecodecs --global-option="build_ext" --global-option="--skip-bitshuffle"

The apng, avif, jetraw, jpegls, jpegxl, lerc, lz4f, lzfse, lzham, mozjpeg, zfp, and zlibng extensions are disabled by default when building from source.

To modify other build settings such as library names and compiler arguments, provide a imagecodecs_distributor_setup.customize_build function, which is imported and executed during setup. See setup.py for examples.

Other Python packages and C libraries providing imaging or compression codecs: Python zlib, Python bz2, Python lzma, backports.lzma, python-lzo, python-lzw, python-lerc, 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, MAFISC.

Examples

Import the JPEG2K codec:

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

Check that the JPEG2K codec is available in the imagecodecs build:

>>> JPEG2K.available
True

Print the version of the JPEG2K codec's underlying OpenJPEG library:

>>> jpeg2k_version()
'openjpeg 2.5.0'

Encode a numpy array in lossless JP2 format:

>>> 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'

Check that the encoded bytes likely contain a JPEG 2000 stream:

>>> jpeg2k_check(encoded)
True

Decode the JP2 encoded bytes to a numpy array:

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

Decode the JP2 encoded bytes to an existing numpy array:

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

Not all codecs are fully implemented, raising exceptions at runtime:

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

Write the numpy array to a JP2 file:

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

Read the image from the JP2 file as numpy array:

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

Create a JPEG 2000 compressed Zarr array:

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

Access image data in a sequence of JP2 files via tifffile.FileSequence and dask.array:

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

View the image in the JP2 file from the command line:

$ python -m imagecodecs _test.jp2