Package: imagecodecs
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, LZ4H5,
LZW, LZO, LZF, LZFSE, LZHAM, PGLZ (PostgreSQL LZ), RCOMP (Rice), ZFP, SPERR,
AEC, SZIP, LERC, EER, NPY, BCn, DDS, BMP, PNG, APNG, GIF, TIFF, WebP, QOI,
JPEG 8 and 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, DICOMRLE, PackBits, Packed Integers, Delta, XOR Delta,
Floating Point Predictor, Bitorder reversal, Byteshuffle, Bitshuffle,
Float24 (24-bit floating point),
Quantize (Scale, BitGroom, BitRound, GranularBR), and
CMS (color space transformations).
Checksum functions are implemented for crc32, adler32, fletcher32, and
Jenkins lookup3.Author:Christoph GohlkeLicense:BSD 3-ClauseVersion:2024.1.1DOI:10.5281/zenodo.6915978QuickstartInstall the imagecodecs package and all dependencies from thePython Package Index:python -m pip install -U imagecodecs[all]Imagecodecs is also available in other package repositories such asAnaconda,MSYS2, andMacPorts.SeeRequirementsandNotesfor building from source.SeeExamplesfor using the programming interface.Source code and support are available onGitHub.RequirementsThis revision was tested with the following requirements and dependencies
(other versions may work):CPython3.9.13, 3.10.11, 3.11.7, 3.12.1, 64-bitNumpy1.26.2numcodecs0.12.1
(optional, for Zarr compatible codecs)Build requirements:Cython3.0.7brotli1.1.0brunsli0.1bzip21.0.8c-blosc1.21.5c-blosc22.12.0charls2.4.2giflib5.2.1jetraw23.03.16.4jxrlib1.2lcms22.16.0lerc4.0.0libaec1.1.2libavif1.0.3
(aom3.8.0,dav1d1.3.0,rav1e0.6.6,svt-av11.8.0)libdeflate1.19libheif1.17.6
(libde2651.0.15,x2653.5)libjpeg-turbo3.0.1libjxl0.9.0liblzma5.4.5libpng1.6.40libpng-apng1.6.40libtiff4.6.0libwebp1.3.2lz41.9.4lzfse1.0lzham_codec1.0lzokaydb2df1fmozjpeg4.1.5openjpeg2.5.0snappy1.1.10sperr0.8.0zfp1.0.1zlib1.3zlib-ng2.1.5zopfli1.0.3zstd1.5.5Vendored requirements:bcdec.h026acf9bitshuffle0.5.1cfitsio ricecomp.cmodifiedh5checksum.cmodifiedjpg_0XC3.cppmodifiedliblj92modifiedliblzf3.6libspng0.7.4nc4var.cmodifiedpg_lzcompress.cmodifiedqoi.h36190ebrgbe.cmodifiedTest requirements:tifffile2023.12.9czifile2019.7.2zarr2.16.1python-blosc1.11.1python-blosc22.4.0python-brotli1.0.9python-lz44.3.2python-lzf0.2.4python-snappy0.6.1python-zstd1.5.5.1pyliblzfse0.4.1zopflipy1.9Revisions2024.1.1Pass 7420 tests.Add 8/24-bit BMP codec.Add SPERR codec based on SPERR library.Add LZO decoder based on lzokay library.Add DICOMRLE decoder.Enable float16 in CMS codec.Enable MCT for lossless JPEG2K encoder (#88).Ignore pad-byte in PackBits decoder (#86).Fix heif_write_callback error message not set.Require lcms2 2.16 with issue-420 fixes.Require libjxl 0.9, libaec 1.1, Cython 3.2023.9.18Rebuild with updated dependencies fixes CVE-2024-4863.2023.9.4Map avif_encode level parameter to quality (breaking).Support monochrome images in avif_encode.Add numthreads parameter to avif_decode (fix imread of AVIF).Add quantize filter (BitGroom, BitRound, GBR) via nc4var.c.Add LZ4H5 codec.Support more BCn compressed DDS fourcc types.Require libavif 1.0.2023.8.12Add EER (Electron Event Representation) decoder.Add option to pass initial value to crc32 and adler32 checksum functions.Add fletcher32 and lookup3 checksum functions via HDF5’s h5checksum.c.Add Checksum codec for numcodecs.2023.7.10Rebuild with optimized compile flags.2023.7.4Add BCn and DDS decoder via bcdec library.Add functions to transcode JPEG XL to/from JPEG (#78).Add option to decode select frames from animated WebP.Use legacy JPEG8 codec when building without libjpeg-turbo 3 (#65).Change blosc2_encode defaults to match blosc2-python (breaking).Fix segfault writing JPEG2K with more than 4 samples.Fix some codecs returning bytearray by default.Fully vendor cfitsio’s ricecomp.c.Drop support for Python 3.8 and numpy < 1.21 (NEP29).2023.3.16Require 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.23Require 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…Refer to the CHANGES file for older revisions.ObjectivesMany 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 separate
from the segments.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.NotesThis library is largely a work in progress.The API is not stable yet and might change between revisions.Python <= 3.8 is no longer supported. 32-bit versions are deprecated.Works on little-endian platforms only.Supported platforms arewin_amd64,win_arm64,win32,macosx_x86_64,macosx_arm64, andmanylinux_x86_64.Wheels may not be available for all platforms and all releases.Only thewin_amd64wheels include all features.Thetiff,bcn,dds,dicomrle,eer,lzo,packints,
andjpegsof3codecs are currently decode-only.Theheifandjetrawcodecs are distributed as source code only due to
license and possible patent usage issues.The latestMicrosoft Visual C++ Redistributable for Visual Studio 2015-2022is 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.Update pip and setuptools to the latest version before installing imagecodecs:python -m pip install -U pip setuptools wheel CythonInstall the requirements for building imagecodecs from source code on
latest Ubuntu Linux distributions:sudoapt-getinstallbuild-essentialpython3-devcython3python3-setuptoolspython3-pippython3-wheelpython3-numpypython3-zarrpython3-pytestpython3-bloscpython3-brotlipython3-snappypython3-lz4libz-devlibblosc-devliblzma-devliblz4-devlibzstd-devlibpng-devlibwebp-devlibbz2-devlibopenjp2-7-devlibjpeg-devlibjxr-devliblcms2-devlibcharls-devlibaec-devlibbrotli-devlibsnappy-devlibzopfli-devlibgif-devlibtiff-devlibdeflate-devlibavif-devlibheif-devUse the--litebuild option to only build extensions without 3rd-party
dependencies. Use the--skip-extensionbuild options to skip building
specific extensions, for example:python-mpip install imagecodecs--global-option="build_ext"--global-option="--skip-bitshuffle"Theapng,avif,jetraw,jpegls,jpegxl,lerc,lz4f,lzfse,lzham,lzo,mozjpeg,sperr,zfp,
andzlibngextensions are disabled by default when building from source.To modify other build settings such as library names and compiler arguments,
provide aimagecodecs_distributor_setup.customize_buildfunction, which
is imported and executed during setup. Seesetup.pyfor 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,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.ExamplesImport 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
TruePrint 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)
TrueDecode the JP2 encoded bytes to a numpy array:>>> decoded = jpeg2k_decode(encoded)
>>> numpy.array_equal(decoded, array)
TrueDecode the JP2 encoded bytes to an existing numpy array:>>> out = numpy.empty_like(array)
>>> _ = jpeg2k_decode(encoded, out=out)
>>> numpy.array_equal(out, array)
TrueNot all codecs are fully implemented, raising exceptions at runtime:>>> from imagecodecs import tiff_encode
>>> tiff_encode(array)
Traceback (most recent call last):
 ...
NotImplementedError: tiff_encodeWrite 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)
TrueCreate 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)...Write the Zarr store to a fsspec ReferenceFileSystem in JSON format
and open it as a Zarr array:>>> 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>View the image in the JP2 file from the command line:$ python -m imagecodecs _test.jp2