pylibjpeg: JPEG and DICOM RLE Decoder Framework

2.1.0 · active · verified Fri Apr 17

pylibjpeg is a Python framework for decoding JPEG and decoding/encoding DICOM RLE data, primarily designed to support pydicom. It provides a flexible handler system that allows different backend implementations for JPEG and RLE to be used. The current version is 2.1.0, and it follows an infrequent release cadence, often tied to significant architectural changes or `pydicom`'s decoding needs.

Common errors

```
AttributeError: module 'pylibjpeg' has no attribute 'libjpeg'
```
cause Attempting to access `libjpeg` or `rle` directly from the `pylibjpeg` package, which were moved to separate packages in version 2.0.0.

fix Install `pylibjpeg-libjpeg` (and/or `pylibjpeg-rle`) separately using `pip`, then import them as `import pylibjpeg_libjpeg` (and `import pylibjpeg_rle`). Register them with `pylibjpeg.add_handler(pylibjpeg_libjpeg)`.
```
RuntimeError: No pixel data handler could be found for transfer syntax '1.2.840.10008.1.2.4.90' (or similar transfer syntax UUID)
```
cause When using `pydicom` to read a compressed DICOM file, no registered handler (e.g., from `pylibjpeg-libjpeg`) is available for the specified transfer syntax.

fix Install the appropriate `pylibjpeg` backend package (e.g., `pip install pylibjpeg-libjpeg` for JPEG) and ensure you register it in your code using `pylibjpeg.add_handler(pylibjpeg_libjpeg)` before reading the DICOM file.
```
ImportError: No module named 'pylibjpeg_libjpeg'
```
cause You are trying to import `pylibjpeg_libjpeg` (or `pylibjpeg_rle`) but the package has not been installed.

fix Install the missing backend package using pip: `pip install pylibjpeg-libjpeg` (or `pip install pylibjpeg-rle`).

Warnings

breaking Version 2.0.0 introduced a major rewrite of the handler API and moved core decoder modules into separate packages. Direct imports like `pylibjpeg.libjpeg` or `pylibjpeg.rle` are no longer valid and will cause `AttributeError`.
Fix: Install `pylibjpeg-libjpeg` and `pylibjpeg-rle` as separate packages (`pip install pylibjpeg-libjpeg pylibjpeg-rle`), then use `import pylibjpeg_libjpeg` and `import pylibjpeg_rle` for registration, e.g., `pylibjpeg.add_handler(pylibjpeg_libjpeg)`.
gotcha Installing `pylibjpeg` alone does not provide any JPEG or RLE decoding capabilities. `pylibjpeg` is a framework; you must also install at least one backend package (e.g., `pylibjpeg-libjpeg` for JPEG, `pylibjpeg-rle` for RLE) and register its handler(s).
Fix: After `pip install pylibjpeg`, also install `pip install pylibjpeg-libjpeg` and/or `pip install pylibjpeg-rle`, then register them in your code: `pylibjpeg.add_handler(pylibjpeg_libjpeg)`.
gotcha If `pydicom` reports `RuntimeError: No pixel data handler could be found for transfer syntax ...`, it's likely that `pylibjpeg` is installed but the necessary backend handler for the specific compression (e.g., JPEG, RLE) was not installed or not registered via `pylibjpeg.add_handler()`.
Fix: Ensure you have installed the correct backend package (`pylibjpeg-libjpeg` or `pylibjpeg-rle`) and have called `pylibjpeg.add_handler()` with the imported backend module before attempting to read compressed DICOM pixel data.

Install

pip install pylibjpeg Core framework (includes numpy)
pip install pylibjpeg-libjpeg For JPEG decoding support
pip install pylibjpeg-rle For DICOM RLE decoding/encoding support

Imports

add_handler

import pylibjpeg; pylibjpeg.add_handler(...)

libjpeg
wrong:
```
import pylibjpeg.libjpeg
```
correct:
```
import pylibjpeg_libjpeg
```
The actual JPEG handler is now in the separate `pylibjpeg-libjpeg` package.
rle
wrong:
```
import pylibjpeg.rle
```
correct:
```
import pylibjpeg_rle
```
The actual RLE handler is now in the separate `pylibjpeg-rle` package.

Quickstart

This quickstart demonstrates how to install `pylibjpeg` and its necessary backend handlers, then registers them with the `pydicom` library to enable decoding of compressed DICOM pixel data (JPEG, RLE). You must install the `pylibjpeg-libjpeg` and/or `pylibjpeg-rle` packages separately to enable their respective decoding capabilities. The `DICOM_FILE_PATH` environment variable can be set to point to a test DICOM file.

import pydicom
import pylibjpeg
import os

# Ensure you have installed a backend, e.g., 'pip install pylibjpeg-libjpeg'
# and optionally 'pip install pylibjpeg-rle' for RLE support.

try:
    import pylibjpeg_libjpeg
    # Register the JPEG handler. For pydicom, registering the top-level package
    # automatically adds all handlers within it.
    pylibjpeg.add_handler(pylibjpeg_libjpeg)
    print("pylibjpeg_libjpeg handler successfully added.")
except ImportError:
    print("Warning: pylibjpeg-libjpeg is not installed. JPEG decoding will not be available.")

try:
    import pylibjpeg_rle
    pylibjpeg.add_handler(pylibjpeg_rle)
    print("pylibjpeg_rle handler successfully added.")
except ImportError:
    print("Warning: pylibjpeg-rle is not installed. RLE decoding/encoding will not be available.")

print(f"Current active pylibjpeg handlers: {pylibjpeg.get_handlers()}")

# Example: Decode a DICOM file using pydicom (requires a valid DICOM file)
# Set DICOM_FILE_PATH environment variable for testing, e.g., an image with JPEG/RLE compression
dicom_file_path = os.environ.get('DICOM_FILE_PATH', 'path/to/your/compressed_dicom.dcm')

if os.path.exists(dicom_file_path):
    try:
        ds = pydicom.dcmread(dicom_file_path)
        if hasattr(ds, 'pixel_array'):
            pixel_array = ds.pixel_array
            print(f"Successfully decoded pixel data from '{dicom_file_path}' with shape: {pixel_array.shape}")
        else:
            print(f"DICOM file '{dicom_file_path}' does not contain pixel data or could not be decoded by available handlers.")
    except Exception as e:
        print(f"Error reading DICOM file or decoding pixel data: {e}")
else:
    print(f"Skipping DICOM decode example: DICOM_FILE_PATH '{dicom_file_path}' not found or not set.")

view raw JSON →