diff --git a/README.rst b/README.rst index fb86586..6fbead1 100644 --- a/README.rst +++ b/README.rst @@ -1,3 +1,6 @@ +.. + This file is generated by setup.py + Image transformation, compression, and decompression codecs =========================================================== @@ -5,15 +8,15 @@ 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, +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, Pcodec, 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), +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 @@ -21,7 +24,7 @@ Jenkins lookup3. :Author: `Christoph Gohlke `_ :License: BSD 3-Clause -:Version: 2024.1.1 +:Version: 2024.6.1 :DOI: `10.5281/zenodo.6915978 `_ Quickstart @@ -30,7 +33,7 @@ Quickstart Install the imagecodecs package and all dependencies from the `Python Package Index `_:: - python -m pip install -U imagecodecs[all] + python -m pip install -U "imagecodecs[all]" Imagecodecs is also available in other package repositories such as `Anaconda `_, @@ -50,55 +53,56 @@ Requirements This revision was tested with the following requirements and dependencies (other versions may work): -- `CPython `_ 3.9.13, 3.10.11, 3.11.7, 3.12.1, 64-bit -- `Numpy `_ 1.26.2 +- `CPython `_ 3.9.13, 3.10.11, 3.11.9, 3.12.3, 64-bit +- `Numpy `_ 1.26.4 - `numcodecs `_ 0.12.1 (optional, for Zarr compatible codecs) Build requirements: -- `Cython `_ 3.0.7 +- `Cython `_ 3.0.10 - `brotli `_ 1.1.0 - `brunsli `_ 0.1 - `bzip2 `_ 1.0.8 - `c-blosc `_ 1.21.5 -- `c-blosc2 `_ 2.12.0 +- `c-blosc2 `_ 2.14.4 - `charls `_ 2.4.2 -- `giflib `_ 5.2.1 +- `giflib `_ 5.2.2 - `jetraw `_ 23.03.16.4 - `jxrlib `_ 1.2 - `lcms2 `_ 2.16.0 -- `lerc `_ 4.0.0 -- `libaec `_ 1.1.2 -- `libavif `_ 1.0.3 - (`aom `_ 3.8.0, - `dav1d `_ 1.3.0, - `rav1e `_ 0.6.6, - `svt-av1 `_ 1.8.0) -- `libdeflate `_ 1.19 +- `lerc `_ 4.0.4 +- `libaec `_ 1.1.3 +- `libavif `_ 1.0.4 + (`aom `_ 3.9.0, + `dav1d `_ 1.4.2, + `rav1e `_ 0.7.1, + `svt-av1 `_ 2.1.0) +- `libdeflate `_ 1.20 - `libheif `_ 1.17.6 (`libde265 `_ 1.0.15, - `x265 `_ 3.5) -- `libjpeg-turbo `_ 3.0.1 -- `libjxl `_ 0.9.0 -- `liblzma `_ 5.4.5 -- `libpng `_ 1.6.40 -- `libpng-apng `_ 1.6.40 + `x265 `_ 3.6) +- `libjpeg-turbo `_ 3.0.3 +- `libjxl `_ 0.10.2 +- `liblzma `_ 5.6.2 +- `libpng `_ 1.6.43 +- `libpng-apng `_ 1.6.43 - `libtiff `_ 4.6.0 -- `libwebp `_ 1.3.2 +- `libwebp `_ 1.4.0 - `lz4 `_ 1.9.4 - `lzfse `_ 1.0 - `lzham_codec `_ 1.0 - `lzokay `_ db2df1f - `mozjpeg `_ 4.1.5 -- `openjpeg `_ 2.5.0 -- `snappy `_ 1.1.10 -- `sperr `_ 0.8.0 +- `openjpeg `_ 2.5.2 +- `pcodec `_ 0.2.5, +- `snappy `_ 1.2.1 +- `sperr `_ 0.8.1 - `zfp `_ 1.0.1 -- `zlib `_ 1.3 -- `zlib-ng `_ 2.1.5 +- `zlib `_ 1.3.1 +- `zlib-ng `_ 2.1.6 - `zopfli `_ 1.0.3 -- `zstd `_ 1.5.5 +- `zstd `_ 1.5.6 Vendored requirements: @@ -121,25 +125,33 @@ Vendored requirements: Test requirements: -- `tifffile `_ 2023.12.9 +- `tifffile `_ 2024.5.22 - `czifile `_ 2019.7.2 -- `zarr `_ 2.16.1 +- `zarr `_ 2.18.2 - `python-blosc `_ 1.11.1 -- `python-blosc2 `_ 2.4.0 +- `python-blosc2 `_ 2.6.2 - `python-brotli `_ 1.0.9 -- `python-lz4 `_ 4.3.2 +- `python-lz4 `_ 4.3.3 - `python-lzf `_ 0.2.4 -- `python-snappy `_ 0.6.1 +- `python-snappy `_ 0.7.1 - `python-zstd `_ 1.5.5.1 - `pyliblzfse `_ 0.4.1 -- `zopflipy `_ 1.9 +- `zopflipy `_ 1.10 Revisions --------- +2024.6.1 + +- Pass 7486 tests. +- Fix segfault in sperr_decode. +- Fix segfault when strided-decoding into buffers with unexpected shapes (#98). +- Fix jpeg2k_encoder output buffer too small (#101). +- Add PCODEC codec based on pcodec library. +- Support NumPy 2. + 2024.1.1 -- Pass 7420 tests. - Add 8/24-bit BMP codec. - Add SPERR codec based on SPERR library. - Add LZO decoder based on lzokay library. @@ -188,35 +200,6 @@ Revisions - Fully vendor cfitsio's ricecomp.c. - Drop support for Python 3.8 and numpy < 1.21 (NEP29). -2023.3.16 - -- 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 - - … Refer to the CHANGES file for older revisions. @@ -261,7 +244,8 @@ 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``, and ``manylinux_x86_64``. +``macosx_x86_64``, ``macosx_arm64``, ``manylinux_x86_64``, and +``manylinux_aarch64``. Wheels may not be available for all platforms and all releases. @@ -285,32 +269,25 @@ 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: +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-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`` + ``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`` -Use the ``--lite`` build option to only build extensions without 3rd-party -dependencies. Use the ``--skip-extension`` build options to skip building -specific extensions, for example: +To build and install imagecodecs from source code, run:: - ``python -m pip install imagecodecs --global-option="build_ext" - --global-option="--skip-bitshuffle"`` + python -m pip install . -The ``apng``, ``avif``, ``jetraw``, ``jpegls``, ``jpegxl``, ``lerc``, -``lz4f``, ``lzfse``, ``lzham``, ``lzo``, ``mozjpeg``, ``sperr``, ``zfp``, -and ``zlibng`` extensions are disabled by default when building from source. +Many 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. +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 Python packages and C libraries providing imaging or compression codecs: `Python zlib `_, @@ -358,112 +335,145 @@ Other Python packages and C libraries providing imaging or compression codecs: `Grok `_ (AGPL), `MAFISC `_, -`B3D `_. +`B3D `_, +`libultrahdr `_. Examples -------- Import the JPEG2K codec: ->>> from imagecodecs import ( -... jpeg2k_encode, jpeg2k_decode, jpeg2k_check, jpeg2k_version, JPEG2K -... ) +.. code-block:: python + + >>> 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 +.. code-block:: python + + >>> JPEG2K.available + True Print the version of the JPEG2K codec's underlying OpenJPEG library: ->>> jpeg2k_version() -'openjpeg 2.5.0' +.. code-block:: python + + >>> jpeg2k_version() + 'openjpeg 2.5.2' 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' +.. code-block:: python + + >>> 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 +.. code-block:: python + + >>> jpeg2k_check(encoded) + True Decode the JP2 encoded bytes to a numpy array: ->>> decoded = jpeg2k_decode(encoded) ->>> numpy.array_equal(decoded, array) -True +.. code-block:: python + + >>> 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 +.. code-block:: python + + >>> 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 +.. code-block:: python + + >>> 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) +.. code-block:: python + + >>> 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 +.. code-block:: python + + >>> 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() -... ) - +.. code-block:: python + + >>> 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(), + ... ) + 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>> 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>> 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') - +.. code-block:: python + + >>> 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') + View the image in the JP2 file from the command line:: - $ python -m imagecodecs _test.jp2 + python -m imagecodecs _test.jp2 \ No newline at end of file