Imagecodecs is a Python library that provides block-oriented, in-memory buffer transformation, compression, and decompression functions for use in Tifffile, Czifile, Zarr 2, kerchunk, and other scientific image input/output packages.
Decode and/or encode functions are implemented for Zlib (DEFLATE), GZIP, LZMA, ZStandard (ZSTD), Blosc, Brotli, Snappy, BZ2, LZ4, LZ4F, LZ4HC, LZ4H5, LZW, LZO, LZF, LZFSE, LZHAM, PGLZ (PostgreSQL LZ), RCOMP (Rice), ZFP, SZ3, Pcodec, SPERR, AEC, SZIP, LERC, EER, NPY, BCn, DDS, BMP, PNG, APNG, GIF, TIFF, WebP, JPEG (2 to 16-bit), Lossless JPEG (LJPEG, LJ92, JPEGLL), JPEG 2000 (JP2, J2K), JPEG LS, JPEG XL, JPEG XS, JPEG XR (WDP, HD Photo), Ultra HDR (JPEG_R), MOZJPEG, AVIF, HEIF, QOI, 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 Gohlke <https://www.cgohlke.com>_
:License: BSD 3-Clause
:Version: 2024.12.30
:DOI: 10.5281/zenodo.6915978 <https://doi.org/10.5281/zenodo.6915978>_
Install the imagecodecs package and all dependencies from the
Python Package Index <https://pypi.org/project/imagecodecs/>_::
python -m pip install -U "imagecodecs[all]"
Imagecodecs is also available in other package repositories such as
Anaconda <https://anaconda.org/conda-forge/imagecodecs>,
MSYS2 <https://packages.msys2.org/base/mingw-w64-python-imagecodecs>, and
MacPorts <https://ports.macports.org/port/py-imagecodecs/summary>_.
See Requirements_ and Notes_ for building from source.
See Examples_ for using the programming interface.
Source code and support are available on
GitHub <https://github.com/cgohlke/imagecodecs>_.
This revision was tested with the following requirements and dependencies (other versions may work):
CPython <https://www.python.org>_ 3.10.11, 3.11.9, 3.12.8, 3.13.1 64-bitNumpy <https://pypi.org/project/numpy>_ 2.1.3numcodecs <https://pypi.org/project/numcodecs/>_ 0.14.1
(optional, for Zarr 2 compatible codecs)Build requirements:
Cython <https://github.com/cython/cython>_ 3.0.11brotli <https://github.com/google/brotli>_ 1.1.0brunsli <https://github.com/google/brunsli>_ 0.1bzip2 <https://gitlab.com/bzip2/bzip2>_ 1.0.8c-blosc <https://github.com/Blosc/c-blosc>_ 1.21.6c-blosc2 <https://github.com/Blosc/c-blosc2>_ 2.15.2charls <https://github.com/team-charls/charls>_ 2.4.2giflib <https://sourceforge.net/projects/giflib/>_ 5.2.2jetraw <https://github.com/Jetraw/Jetraw>_ 23.03.16.4jxrlib <https://github.com/cgohlke/jxrlib>_ 1.2lcms2 <https://github.com/mm2/Little-CMS>_ 2.16lerc <https://github.com/Esri/lerc>_ 4.0.4libaec <https://gitlab.dkrz.de/k202009/libaec>_ 1.1.3libavif <https://github.com/AOMediaCodec/libavif>_ 1.1.1
(aom <https://aomedia.googlesource.com/aom>_ 3.11.0,
dav1d <https://github.com/videolan/dav1d>_ 1.5.0,
rav1e <https://github.com/xiph/rav1e>_ 0.7.1,
svt-av1 <https://gitlab.com/AOMediaCodec/SVT-AV1>_ 2.3.0
libyuv <https://chromium.googlesource.com/libyuv/libyuv>_ main)libdeflate <https://github.com/ebiggers/libdeflate>_ 1.23libheif <https://github.com/strukturag/libheif>_ 1.19.5
(libde265 <https://github.com/strukturag/libde265>_ 1.0.15,
x265 <https://bitbucket.org/multicoreware/x265_git/src/master/>_ 3.6)libjpeg-turbo <https://github.com/libjpeg-turbo/libjpeg-turbo>_ 3.1.0libjxl <https://github.com/libjxl/libjxl>_ 0.11.1libjxs <https://jpeg.org/jpegxs/software.html>_ 2.0.2liblzma <https://github.com/tukaani-project/xz>_ 5.6.3libpng <https://github.com/glennrp/libpng>_ 1.6.44libpng-apng <https://sourceforge.net/projects/libpng-apng/>_ 1.6.44libtiff <https://gitlab.com/libtiff/libtiff>_ 4.7.0libultrahdr <https://github.com/google/libultrahdr>_ 1.3.0libwebp <https://github.com/webmproject/libwebp>_ 1.5.0lz4 <https://github.com/lz4/lz4>_ 1.10.0lzfse <https://github.com/lzfse/lzfse/>_ 1.0lzham_codec <https://github.com/richgel999/lzham_codec/>_ 1.0lzokay <https://github.com/AxioDL/lzokay>_ db2df1fmozjpeg <https://github.com/mozilla/mozjpeg>_ 4.1.5openjpeg <https://github.com/uclouvain/openjpeg>_ 2.5.3pcodec <https://github.com/mwlon/pcodec>_ 0.3.1 (0.4.0 crashes)snappy <https://github.com/google/snappy>_ 1.2.1sperr <https://github.com/NCAR/SPERR>_ 0.8.2sz3 <https://github.com/szcompressor/SZ3>_ 3.1.8 (3.2.x crashes)zfp <https://github.com/LLNL/zfp>_ 1.0.1zlib <https://github.com/madler/zlib>_ 1.3.1zlib-ng <https://github.com/zlib-ng/zlib-ng>_ 2.2.2zopfli <https://github.com/google/zopfli>_ 1.0.3zstd <https://github.com/facebook/zstd>_ 1.5.6Vendored requirements:
bcdec.h <https://github.com/iOrange/bcdec>_ 963c5e5bitshuffle <https://github.com/kiyo-masui/bitshuffle>_ 0.5.2cfitsio ricecomp.c <https://heasarc.gsfc.nasa.gov/fitsio/>_ modifiedh5checksum.c <https://github.com/HDFGroup/hdf5/>_ modifiedjpg_0XC3.cpp <https://github.com/rordenlab/dcm2niix/blob/master/console/jpg_0XC3.cpp>_
modifiedliblj92 <https://bitbucket.org/baldand/mlrawviewer/src/master/liblj92/>_ modifiedliblzf <http://oldhome.schmorp.de/marc/liblzf.html>_ 3.6libspng <https://github.com/randy408/libspng>_ 0.7.4nc4var.c <https://github.com/Unidata/netcdf-c/blob/main/libsrc4/nc4var.c>_
modifiedpg_lzcompress.c <https://github.com/postgres/postgres>_ modifiedqoi.h <https://github.com/phoboslab/qoi/>_ 36190ebrgbe.c <https://www.graphics.cornell.edu/~bjw/rgbe/rgbe.c>_ modifiedTest requirements:
tifffile <https://github.com/cgohlke/tifffile>_ 2024.12.12czifile <https://github.com/cgohlke/czifile>_ 2019.7.2zarr <https://github.com/zarr-developers/zarr-python>_ 2.18.4python-blosc <https://github.com/Blosc/python-blosc>_ 1.11.2python-blosc2 <https://github.com/Blosc/python-blosc2>_ 2.7.1python-brotli <https://github.com/google/brotli/tree/master/python>_ 1.0.9python-lz4 <https://github.com/python-lz4/python-lz4>_ 4.3.3python-lzf <https://github.com/teepark/python-lzf>_ 0.2.6python-snappy <https://github.com/andrix/python-snappy>_ 0.7.2python-zstd <https://github.com/sergey-dryabzhinsky/python-zstd>_ 1.5.5.1pyliblzfse <https://github.com/ydkhatri/pyliblzfse>_ 0.4.1zopflipy <https://github.com/hattya/zopflipy>_ 1.102024.12.30
2024.9.22
2024.6.1
2024.1.1
2023.9.18
Refer to the CHANGES file for older revisions.
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 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:
Accessing parts of large data segments and reading metadata from segments are out of the scope of this library.
This 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 are win_amd64, win_arm64, win32,
macosx_x86_64, macosx_arm64, manylinux_x86_64, and
manylinux_aarch64.
Wheels may not be available for all platforms and all releases.
Only the win_amd64 wheels include all features.
The tiff, bcn, dds, dicomrle, eer, lzo, packints,
and jpegsof3 codecs are currently decode-only.
The heif, jetraw, and jpegxs 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 <https://docs.microsoft.com/en-US/cpp/windows/latest-supported-vc-redist>_
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.
Update pip and setuptools to the latest version before installing imagecodecs::
python -m pip install -U pip setuptools wheel Cython
Before building imagecodecs from source code, install required tools and libraries. For example, on latest Ubuntu Linux distributions:
``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``
To build and install imagecodecs from source code, run::
python -m pip install .
Many extensions are disabled by default when building from source.
To define which extensions are built, or to modify 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 pre-defined customize_build functions.
Other projects providing imaging or compression codecs:
Python zlib <https://docs.python.org/3/library/zlib.html>,
Python bz2 <https://docs.python.org/3/library/bz2.html>,
Python lzma <https://docs.python.org/3/library/lzma.html>,
backports.lzma <https://github.com/peterjc/backports.lzma>,
python-lzo <https://bitbucket.org/james_taylor/python-lzo-static>,
python-lzw <https://github.com/joeatwork/python-lzw>,
python-lerc <https://pypi.org/project/lerc/>,
wavpack-numcodecs <https://github.com/AllenNeuralDynamics/wavpack-numcodecs>,
packbits <https://github.com/psd-tools/packbits>,
isa-l.igzip <https://github.com/intel/isa-l>,
fpzip <https://github.com/seung-lab/fpzip>,
libmng <https://sourceforge.net/projects/libmng/>,
OpenEXR <https://github.com/AcademySoftwareFoundation/openexr>_
(EXR, PIZ, PXR24, B44, DWA),
pyJetraw <https://github.com/Jetraw/pyJetraw>,
tinyexr <https://github.com/syoyo/tinyexr>,
pytinyexr <https://github.com/syoyo/pytinyexr>,
pyroexr <https://github.com/dragly/pyroexr>,
JasPer <https://github.com/jasper-software/jasper>,
libjpeg <https://github.com/thorfdbg/libjpeg> (GPL),
pylibjpeg <https://github.com/pydicom/pylibjpeg>,
pylibjpeg-libjpeg <https://github.com/pydicom/pylibjpeg-libjpeg> (GPL),
pylibjpeg-openjpeg <https://github.com/pydicom/pylibjpeg-openjpeg>,
pylibjpeg-rle <https://github.com/pydicom/pylibjpeg-rle>,
glymur <https://github.com/quintusdias/glymur>,
pyheif <https://github.com/carsales/pyheif>,
pyrus-cramjam <https://github.com/milesgranger/pyrus-cramjam>,
PyLZHAM <https://github.com/Galaxy1036/pylzham>,
BriefLZ <https://github.com/jibsen/brieflz>,
QuickLZ <http://www.quicklz.com/> (GPL),
LZO <http://www.oberhumer.com/opensource/lzo/>_ (GPL),
nvJPEG <https://developer.nvidia.com/nvjpeg>,
nvJPEG2K <https://developer.nvidia.com/nvjpeg>,
PyTurboJPEG <https://github.com/lilohuang/PyTurboJPEG>,
CCSDS123 <https://github.com/drowzie/CCSDS123-Issue-2>,
LPC-Rice <https://sourceforge.net/projects/lpcrice/>,
CompressionAlgorithms <https://github.com/glampert/compression-algorithms>,
Compressonator <https://github.com/GPUOpen-Tools/Compressonator>,
Wuffs <https://github.com/google/wuffs>,
TinyDNG <https://github.com/syoyo/tinydng>,
OpenJPH <https://github.com/aous72/OpenJPH>,
Grok <https://github.com/GrokImageCompression/grok>_ (AGPL),
MAFISC <https://wr.informatik.uni-hamburg.de/research/projects/icomex/mafisc>,
B3D <https://github.com/balintbalazs/B3D>,
fo-dicom.Codecs <https://github.com/Efferent-Health/fo-dicom.Codecs>,
jpegli <https://github.com/google/jpegli>,
hdf5plugin <https://github.com/silx-kit/hdf5plugin>_.
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.3'
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 2 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 2 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
FAQs
Image transformation, compression, and decompression codecs
We found that imagecodecs demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Socket and Seal Security collaborate to fix a critical npm overrides bug, resolving a three-year security issue in the JavaScript ecosystem's most popular package manager.
Security News
TypeScript is porting its compiler to Go, delivering 10x faster builds, lower memory usage, and improved editor performance for a smoother developer experience.
Research
Security News
The Socket Research Team has discovered six new malicious npm packages linked to North Korea’s Lazarus Group, designed to steal credentials and deploy backdoors.