pylibjpeg-libjpeg

2.4.0 · active · verified Thu Apr 16

pylibjpeg-libjpeg is a Python wrapper for the `libjpeg` C library, designed primarily to function as a plugin for the `pylibjpeg` framework, which in turn provides JPEG decoding capabilities for `pydicom`. It enables Python applications to decode various JPEG formats, including JPEG Baseline, Extended, Lossless (Process 14), JPEG-LS Lossless, and Lossy. The library is actively maintained, with the current version being 2.4.0, and typically sees updates for Python version compatibility and `libjpeg` upgrades every few months to a year.

Common errors

```
RuntimeError: Unable to convert the Pixel Data as the 'pylibjpeg-libjpeg' plugin is not installed
```
cause This error typically occurs when pydicom (or pylibjpeg) attempts to decode JPEG pixel data but cannot find or load the pylibjpeg-libjpeg plugin. This can be due to the plugin not being installed, an incorrect Python environment, or platform-specific wheel issues.

fix Ensure `pylibjpeg-libjpeg` is correctly installed in the active Python environment (`pip install pylibjpeg-libjpeg`). Verify that a compatible wheel is available for your OS and Python version.
```
PyInstaller/cx_Freeze fails to bundle or find 'pylibjpeg-libjpeg' in executable: 'No module named 'pylibjpeg-libjpeg' or GDCM handler error.
```
cause Executable creators like PyInstaller or cx_Freeze may have difficulty finding and bundling the underlying C library or `pkg_resources` entry points used by `pylibjpeg-libjpeg`.

fix For PyInstaller, you might need to manually include `pylibjpeg-libjpeg` (and `libjpeg`) as hidden imports or provide custom hooks to ensure it's properly packaged. Consult PyInstaller's documentation on handling plugins and C extensions.
```
AttributeError: partially initialized module 'pydicom' has no attribute 'config' (most likely due to a circular import)
```
cause This can occur due to circular import issues between pydicom and pylibjpeg components, often seen when trying to install development versions or with certain combinations of pydicom/pylibjpeg/pylibjpeg-libjpeg.

fix Ensure all pydicom-related libraries (pydicom, pylibjpeg, pylibjpeg-libjpeg) are installed from stable releases. If trying development versions, perform a clean uninstall of all components before reinstalling.

Warnings

breaking Python 3.9 support was removed in v2.4.0. Python 3.7 support was dropped in v2.0.0. Always verify your Python version compatibility with the installed `pylibjpeg-libjpeg` version.
Fix: Upgrade to a supported Python version (currently >=3.10 and <4.0).
breaking NumPy version requirements changed significantly: v2.3.0 and newer generally require NumPy 2.0+. Older versions (e.g., Python 3.8 with v2.2.0) explicitly required NumPy < 2.0.
Fix: Ensure your NumPy version matches the requirements of your `pylibjpeg-libjpeg` and Python version. For `pylibjpeg-libjpeg` v2.3.0+, install `numpy>=2.0.0`.
deprecated The `utils.reconstruct()` function was removed in v2.0.0.
Fix: Migrate any code using `utils.reconstruct()` to an alternative approach, likely involving direct pixel array manipulation with NumPy.
gotcha Encoding of JPEG images is not currently supported by `pylibjpeg-libjpeg`; it is a decoding-only library.
Fix: Use other libraries if JPEG encoding functionality is required.
gotcha Version 2.3.0 introduced changes to ensure consistency in the endianness of decoded data on big-endian systems. This may subtly affect pixel data interpretation for users on such architectures upgrading from older versions.
Fix: Review image processing pipelines for potential endianness-related side effects if upgrading on a big-endian system.

Install

pip install pylibjpeg-libjpeg Install stable version

Imports

decode
```
from libjpeg import decode
```
For standalone JPEG image decoding to a NumPy array without pydicom.
pydicom
```
import pydicom
```
When used as a pydicom plugin, pylibjpeg-libjpeg is implicitly loaded, so no direct import is usually needed for plugin functionality. Just ensure it's installed alongside pydicom and pylibjpeg.

Quickstart

This quickstart demonstrates the primary use case of `pylibjpeg-libjpeg` as a plugin for `pydicom` to decode JPEG-compressed DICOM pixel data. Once installed, `pydicom` (via `pylibjpeg`) automatically discovers and uses `pylibjpeg-libjpeg` for supported JPEG transfer syntaxes.

import pydicom
from pydicom.data import get_testdata_file
import numpy # pylibjpeg-libjpeg returns numpy arrays

# Ensure pylibjpeg-libjpeg is installed: pip install pylibjpeg-libjpeg
# This makes it available as a plugin for pydicom through pylibjpeg

# Load a DICOM file with JPEG-compressed pixel data
# Requires 'pydicom-data' for test files, or use your own DICOM file
# If you don't have test files, uncomment: pydicom.data.fetch_data_files()
dicom_file_path = get_testdata_file('JPEG-LL.dcm') # Example: JPEG Lossless

ds = pydicom.dcmread(dicom_file_path)

# Accessing .pixel_array will trigger decoding via pylibjpeg-libjpeg
# if the transfer syntax is supported by the plugin.
pixel_array = ds.pixel_array

print(f"DICOM file loaded: {dicom_file_path}")
print(f"Transfer Syntax UID: {ds.file_meta.TransferSyntaxUID}")
print(f"Pixel array shape: {pixel_array.shape}")
print(f"Pixel array dtype: {pixel_array.dtype}")
print(f"Type of decoded data: {type(pixel_array)}")

view raw JSON →