pydicom / pyjpegls

JPEG-LS for Python via CharLS C++ Library

pydicom

pydicom is a pure Python package for working with DICOM files. It lets you read, modify and write DICOM data in an easy "pythonic" way. As a pure Python package, pydicom can run anywhere Python runs without any other requirements, although if you're working with Pixel Data then we recommend you also install NumPy.

Note that pydicom is a general-purpose DICOM framework concerned with reading and writing DICOM datasets. In order to keep the project manageable, it does not handle the specifics of individual SOP classes or other aspects of DICOM. Other libraries both inside and outside the pydicom organization are based on pydicom and provide support for other aspects of DICOM, and for more specific applications.

Examples are pynetdicom, which is a Python library for DICOM networking, and deid, which supports the anonymization of DICOM files.

Installation

Using pip:

pip install pydicom

Using conda:

conda install -c conda-forge pydicom

For more information, including installation instructions for the development version, see the installation guide.

Documentation

The pydicom user guide, tutorials, examples and API reference documentation is available for both the current release and the development version on GitHub Pages.

Pixel Data

Compressed and uncompressed Pixel Data is always available to be read, changed and written as bytes:

>>> from pydicom import dcmread
>>> from pydicom.data import get_testdata_file
>>> path = get_testdata_file("CT_small.dcm")
>>> ds = dcmread(path)
>>> type(ds.PixelData)
<class 'bytes'>
>>> len(ds.PixelData)
32768
>>> ds.PixelData[:2]
b'\xaf\x00'

If NumPy is installed, Pixel Data can be converted to an ndarray using the Dataset.pixel_array property:

>>> arr = ds.pixel_array
>>> arr.shape
(128, 128)
>>> arr
array([[175, 180, 166, ..., 203, 207, 216],
       [186, 183, 157, ..., 181, 190, 239],
       [184, 180, 171, ..., 152, 164, 235],
       ...,
       [906, 910, 923, ..., 922, 929, 927],
       [914, 954, 938, ..., 942, 925, 905],
       [959, 955, 916, ..., 911, 904, 909]], dtype=int16)

Decompressing Pixel Data

JPEG, JPEG-LS and JPEG 2000

Converting JPEG, JPEG-LS or JPEG 2000 compressed Pixel Data to an ndarray requires installing one or more additional Python libraries. For information on which libraries are required, see the pixel data handler documentation.

RLE

Decompressing RLE Pixel Data only requires NumPy, however it can be quite slow. You may want to consider installing one or more additional Python libraries to speed up the process.

Compressing Pixel Data

Information on compressing Pixel Data using one of the below formats can be found in the corresponding encoding guides. These guides cover the specific requirements for each encoding method and we recommend you be familiar with them when performing image compression.

JPEG-LS, JPEG 2000

Compressing image data from an ndarray or bytes object to JPEG-LS or JPEG 2000 requires installing the following:

• JPEG-LS requires pyjpegls
• JPEG 2000 requires pylibjpeg and the pylibjpeg-openjpeg plugin

RLE

Compressing using RLE requires no additional packages but can be quite slow. It can be sped up by installing pylibjpeg with the pylibjpeg-rle plugin, or gdcm.

Examples

More examples are available in the documentation.

Change a patient's ID

from pydicom import dcmread

ds = dcmread("/path/to/file.dcm")
# Edit the (0010,0020) 'Patient ID' element
ds.PatientID = "12345678"
ds.save_as("/path/to/file_updated.dcm")

Display the Pixel Data

With NumPy and matplotlib

import matplotlib.pyplot as plt
from pydicom import dcmread
from pydicom.data import get_testdata_file

# The path to a pydicom test dataset
path = get_testdata_file("CT_small.dcm")
ds = dcmread(path)
# `arr` is a numpy.ndarray
arr = ds.pixel_array

plt.imshow(arr, cmap="gray")
plt.show()

Contributing

We are all volunteers working on pydicom in our free time. As our resources are limited, we very much value your contributions, be it bug fixes, new core features, or documentation improvements. For more information, please read our contribution guide.

If you have examples or extensions of pydicom that don't belong with the core software, but that you deem useful to others, you can add them to our contribution repository: contrib-pydicom.

pyjpegls's Issues

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)

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.

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

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

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

Add package __version__

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.