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 the tifffile, czifile, and other scientific image input/output modules.

Decode and/or encode functions are implemented for Zlib (DEFLATE), GZIP, ZStandard (ZSTD), Blosc, Brotli, Snappy, LZMA, BZ2, LZ4, LZ4F, LZ4HC, LZW, LZF, ZFP, AEC, LERC, NPY, PNG, GIF, TIFF, WebP, JPEG 8-bit, JPEG 12-bit, Lossless JPEG (LJPEG, SOF3), JPEG 2000, JPEG LS, JPEG XR, JPEG XL, AVIF, PackBits, Packed Integers, Delta, XOR Delta, Floating Point Predictor, Bitorder reversal, Bitshuffle, and Float24 (24-bit floating point).

Author:	Christoph Gohlke
Organization:	Laboratory for Fluorescence Dynamics. University of California, Irvine
License:	BSD 3-Clause
Version:	2021.3.31
Status:	Alpha

Requirements

This release has been tested with the following requirements and dependencies (other versions may work):

• CPython 3.7.9, 3.8.8, 3.9.2 64-bit
• Numpy 1.19.5
• Cython 0.29.22
• zlib 1.2.11
• lz4 1.9.3
• zstd 1.4.9
• blosc 1.21.0
• bzip2 1.0.8
• liblzma 5.2.5
• liblzf 3.6
• libpng 1.6.37
• libwebp 1.2.0
• libtiff 4.2.0
• libjpeg-turbo 2.0.6 (8 and 12-bit)
• libjpeg 9d
• charls 2.2.0
• openjpeg 2.4.0
• jxrlib 1.1
• zfp 0.5.5
• bitshuffle 0.3.5
• libaec 1.0.4
• snappy 1.1.8
• zopfli-1.0.3
• brotli 1.0.9
• brunsli 0.1
• giflib 5.2.1
• lerc 2.2.1
• libdeflate 1.7
• libavif 0.9.0
• dav1d 0.8.2
• rav1e 0.4.0
• aom 2.0.2
• lcms 2.12

Required Python packages for testing (other versions may work):

• tifffile 2021.3.17
• czifile 2019.7.2
• python-blosc 1.10.2
• python-lz4 3.1.3
• python-zstd 1.4.8.1
• python-lzf 0.2.4
• python-brotli 1.0.9
• python-snappy 0.6.0
• zopflipy 1.5
• bitshuffle 0.3.5
• numcodecs 0.7.3
• zarr 2.7

Notes

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

Works on little-endian platforms only.

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

Some codecs are currently decode-only: tiff, lzw, packints, and jpegsof3.

The latest Microsoft Visual C++ Redistributable for Visual Studio 2015, 2017 and 2019 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.

This software includes modified versions of dcm2niix's jpg_0XC3.cpp.

This software includes a copy of liblj92.

Build instructions and wheels for manylinux and macOS courtesy of Grzegorz Bokota.

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

python -m pip install --upgrade pip setuptools

Install imagecodecs using precompiled wheels:

python -m pip install --upgrade imagecodecs

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

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 jpeg12, jpegls, jpegxl, zfp, avif, lz4f, and lerc 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 will be imported and executed during setup. See setup.py for examples.

Other Python packages and C libraries providing imaging or compression codecs:

• numcodecs
• Python zlib
• Python bz2
• Python lzma
• backports.lzma
• python-lzo
• python-lzw
• python-lerc
• packbits
• fpzip
• libmng
• APNG patch for libpng
• OpenEXR
• tinyexr
• pytinyexr
• jpeg-xl
• libjpeg (GPL)
• pylibjpeg
• pylibjpeg-libjpeg (GPL)
• pylibjpeg-openjpeg
• glymur
• pyheif
• libheif (LGPL)

Revisions

2021.3.31

Pass 4964 tests. Add numcodecs compatible codecs for use by Zarr (experimental). Support separate JPEG header in jpeg_decode. Do not decode JPEG LS and XL in jpeg_decode (breaking). Fix ZFP with partial header. Fix JPEG LS tests (#15). Fix LZ4F contentchecksum. Remove blosc Snappy tests. Fix docstrings.

2021.2.26

Support X2 and X4 floating point predictors (found in DNG).

2021.1.28

Add option to return JPEG XR fixed point pixel types as integers. Add LJPEG codec via liblj92 (alternative to JPEGSOF3 codec). Change zopfli header location.

2021.1.11

Fix build issues (#7, #8). Return bytearray instead of bytes on PyPy. Raise TypeError if output provided is bytes (breaking).

2021.1.8

Add float24 codec. Update copyrights.

2020.12.24

Update dependencies and build scripts.

2020.12.22

Add AVIF codec via libavif (WIP). Add DEFLATE/Zlib and GZIP codecs via libdeflate. Add LZ4F codec. Add high compression mode option to lz4_encode. Convert JPEG XR 16 and 32-bit fixed point pixel types to float32. Fix JPEG 2000 lossy encoding. Fix GIF disposal handling. Remove support for Python 3.6 (NEP 29).

2020.5.30

Add LERC codec via ESRI's lerc library. Enable building JPEG extensions with libjpeg >= 8. Enable distributors to modify build settings.

2020.2.18

Fix segfault when decoding corrupted LZW segments. Work around Cython raises AttributeError when using incompatible numpy. Raise ValueError if in-place decoding is not possible (except floatpred).

2020.1.31

Add GIF codec via giflib. Add TIFF decoder via libtiff (WIP). Add codec_check functions (WIP). Fix formatting libjpeg error messages. Use xfail in tests. Load extensions on demand on Python >= 3.7. Add build options to skip building specific extensions. Split imagecodecs extension into individual extensions. Move shared code into shared extension. Rename imagecodecs_lite extension and imagecodecs C library to 'imcd'. Remove support for Python 2.7 and 3.5.

2019.12.31

Fix decoding of indexed PNG with transparency. Last version to support Python 2.7 and 3.5.

2019.12.16

Add Zopfli codec. Add Snappy codec. Rename j2k codec to jpeg2k. Rename jxr codec to jpegxr. Use Debian's jxrlib. Support pathlib and binary streams in imread and imwrite. Move external C declarations to pxd files. Move shared code to pxi file. Update copyright notices.

2019.12.10

Add version functions. Add Brotli codec (WIP). Add optional JPEG XL codec via Brunsli repacker (WIP).

2019.12.3

Sync with imagecodecs-lite.

2019.11.28

Add AEC codec via libaec (WIP). Do not require scikit-image for testing. Require CharLS 2.1.

2019.11.18

Add bitshuffle codec. Fix formatting of unknown error numbers. Fix test failures with official python-lzf.

2019.11.5

Rebuild with updated dependencies.

2019.5.22

Add optional YCbCr chroma subsampling to JPEG encoder. Add default reversible mode to ZFP encoder. Add imread and imwrite helper functions.

2019.4.20

Fix setup requirements.

2019.2.22

Move codecs without 3rd-party C library dependencies to imagecodecs_lite.

2019.2.20

Rebuild with updated dependencies.

2019.1.20

Add more pixel formats to JPEG XR codec. Add JPEG XR encoder.

2019.1.14

Add optional ZFP codec via zfp library (WIP). Add numpy NPY and NPZ codecs. Fix some static codechecker errors.

2019.1.1

...

Refer to the CHANGES file for older revisions.