pydicom / pyjpegls

JPEG-LS for Python via CharLS C++ Library

pyjpegls

Note
This is a fork of the original CharPyLS repository created to be able to add fixes and adaptions, as that repo is not maintained anymore. The rest of this file is unchanged from the original readme.

JPEG-LS for Python via CharLS C++ Library

I wrote this interface to enable easy access to the awesome JPEG-LS lossless image compression algorithm from within my Python application. I had no need to read/write anyone else's JPEG-LS image files, but rather I needed to compress some data structures internal to my application. This data was similar in nature to greyscale imagery such that it was an easy choice to leverage the existing CharLS C++ library I found on codeplex.com. I did eventually incorporate some basic file I/O functionality for my unit tests, and that's why I list Pillow below as a dependency.

I have tested this code on Windows 7 x64, Windows 8 x64, and Ubuntu x64. Note, even though this package has the odd name "CharPyLS", you will import it into your module as "jpeg_ls". Here is a quick example of using this tool to compress an image to a buffer in memory. For more details, check out the examples included within the source code.

    # Read in an image from an existing PNG file.
    fname_img = 'test/image.png'
    data_image = data_io.read_PIL(fname_img)

    # Compress image data to a sequence of bytes.
    data_buffer = jpeg_ls.encode(data_image)

    # Sizes.
    size_png = os.path.getsize(fname_img)
    print('Size of RGB 8-bit image data:  {:n}'.format(len(data_image.tostring())))
    print('Size of PNG encoded data file: {:n}'.format(size_png))
    print('Size of JPEG-LS encoded data:  {:n}'.format(len(data_buffer)))

    # Decompress.
    data_image_b = jpeg_ls.decode(data_buffer)

    # Compare.
    is_same = (data_image == data_image_b).all()
    print('Restored data is identical to original: {:s}'.format(str(is_same)))

The output generated by the above example should look like the following:

Size of RGB 8-bit image data:  5038848
Size of PNG encoded data file: 2409950
Size of JPEG-LS encoded data:  2088357
Restored data is identical to original: True

About JPEG-LS

• From Wikipedia article: JPEG-LS (ISO-14495-1/ITU-T.87) is an accepted lossless image compression standard derived from the Hewlett Packard LOCO algorithm.
• From CharLS codeplex site: CharLS is an optimized implementation of the JPEG-LS standard for lossless and near-lossless image compression. JPEG-LS is a low-complexity standard that matches JPEG 2000 compression ratios. In terms of speed, CharLS outperforms open source and commercial JPEG LS implementations.

Dependencies

• Numpy
• Cython (only for building and installing, not for everyday use)
• Pillow (friendly fork of PIL, used here for file I/O with the example and during unit tests)
• CharLS (source included as subfolder)

pyjpegls's Issues

Add support for Python 3.12

And drop it for Python 3.7.

The release workflow will need some updates, too.

@mrbean-bremen do you mind inviting me on pypi so I can setup that side of things?

Also, do you want to review any PRs or are you happy for me to move fast and break things (as the saying goes)?

Add package __version__

Add support for decoding a buffer

I'd like to add support for:

• Decoding a buffer-like without having to go through an ndarray
• Returning the decoded image as a bytearray

Also, literally only just realised this already supports encoding (greyscale) to JPEG-LS...

Get tests running

Currently, there are a few tests which do not work anymore because the test data has been removed.
Instead, some test files from the JPEG-LS conformance test have been added, but no automatic test exists for these.
Probably the old tests have to be completely rewritten to work with this test data.

Add support for encoding using bytes as the source

pydicom's encoding backend expects encoders to take bytes rather than ndarray.

def  encode_to_buffer(src: bytes | np.ndarray, lossy_error, interleave_mode, **kwargs) -> bytearray: ...

Required kwargs for bytes: rows, columns, samples_per_pixel, planar_configuration, bits_stored.

Maybe add a separate function instead: encode_pixel_data(src: bytes, lossy_error: int = 0, **kwargs)

Use more current CharLS version

The current version of CharLS used roughly corresponds to version 1.0, released in 2010.
The last released version of the actively manatained project is 2.4.1 from 2023, with many fixes in place.

The API has also changed, so that would also mean to adapt the wrapper code.
A possibility would also to include the CharLS code as a submodule, simliar to openjpeg in pylibjpeg-openjpeg.

Add PyPi release builds in CI

Currently, there is no easy way to create a PyPi release with packages for different targets.
This can probably mostly be borrowed from the release workflow in pylibjpeg-openjpeg and pylibjpeg-libjpeg.
The targets may be the same ones, maybe remove Windows 32 bit, as I don't think it is still needed (though I may be wrong).

Encoding for multi-component images is incorrect

They're ending up a encoded as single component due to the use of interleaving 0, but interleaving 1 and 2 don't work due to an incorrect stride calculation.

Interleaving 0 is for single component, 1 and 2 for multi, so the interleaving value needs to be restricted based on the number of components.