pylibjpeg-openjpeg

2.5.0 · active · verified Thu Apr 16

pylibjpeg-openjpeg is a Python wrapper for the OpenJPEG library, specifically designed as a plugin for pylibjpeg. It enables JPEG 2000 (J2K) decoding and encoding for various image data, including DICOM pixel data. The current version is 2.5.0, and releases often coincide with new Python versions or updates to the underlying OpenJPEG library, typically every few months.

Common errors

```
TypeError: encode_pixel_data() got an unexpected keyword argument 'nr_components'
```
cause Using the deprecated `nr_components` parameter in encoding functions after it was renamed to `samples_per_pixel`.

fix Replace `nr_components` with `samples_per_pixel` in your encoding function calls.
```
ImportError: cannot import name 'openjpeg' from 'pylibjpeg_openjpeg' (most likely due to a circular import)
```
cause Attempting to import `openjpeg` directly from the top-level package or a typo.

fix The `openjpeg` functionality is exposed via the `pylibjpeg_openjpeg.openjpeg` submodule. Use `from pylibjpeg_openjpeg import openjpeg`.
```
TypeError: 'bytearray' object cannot be interpreted as a numpy.ndarray
```
cause Attempting to pass a `bytearray` directly to an encoding function after v2.2.1, which no longer accepts it as an image data source.

fix Convert your `bytearray` data to `bytes` or a `numpy.ndarray` before passing it to `encode_pixel_data` or `encode_buffer`.
```
ModuleNotFoundError: No module named 'pylibjpeg'
```
cause While `pylibjpeg-openjpeg` is a standalone package, it's designed to be a plugin for `pylibjpeg`. If you're trying to use its plugin functionality (e.g., via `pylibjpeg.decode`), `pylibjpeg` must also be installed.

fix Install the `pylibjpeg` library: `pip install pylibjpeg`.

Warnings

breaking Support for Python 3.7 was dropped in v2.0.0, and Python 3.8 was dropped in v2.4.0. Ensure your Python environment is 3.9 or higher.
Fix: Upgrade Python to 3.9 or newer, or use an older pylibjpeg-openjpeg version if tied to an older Python.
breaking The `nr_components` parameter in encoding functions was renamed to `samples_per_pixel` in v2.2.0 to align with DICOM terminology.
Fix: Update calls to `encode_pixel_data` or `encode_buffer` to use `samples_per_pixel` instead of `nr_components`.
breaking As of v2.4.0, NumPy version 2.0 or higher is required for Python 3.9 and above. For Python 3.8 (supported only in v2.3.0 and older), NumPy < 2.0 was required.
Fix: Ensure your NumPy installation is `numpy>=2.0` if using pylibjpeg-openjpeg v2.4.0+ with Python 3.9+.
gotcha Using `bytearray` as the image data source for encoding functions (`encode_pixel_data()` and `encode_buffer()`) was removed in v2.2.1. Use `bytes` or `numpy.ndarray` instead.
Fix: Convert `bytearray` data to `bytes` or a `numpy.ndarray` before passing it to encoding functions.
gotcha Fixes were introduced in v2.4.0 for encoding and decoding on big-endian systems, and in v2.5.0 for issues where bits above J2K precision affected encoding results. If experiencing data corruption on big-endian systems or subtle encoding errors, an upgrade is recommended.
Fix: Upgrade to pylibjpeg-openjpeg v2.5.0 or newer to benefit from these fixes.

Install

pip install pylibjpeg-openjpeg Install stable version

Imports

openjpeg
```
from pylibjpeg_openjpeg import openjpeg
```
The core functionality (decode/encode) is exposed via the 'openjpeg' submodule.
register_plugin
wrong:
```
from pylibjpeg_openjpeg import register_plugin
```
correct:
```
from pylibjpeg import register_plugin
register_plugin('openjpeg', 'pylibjpeg_openjpeg')
```
The 'register_plugin' function belongs to pylibjpeg, not pylibjpeg-openjpeg itself. pylibjpeg-openjpeg is the plugin module *name*.

Quickstart

This quickstart demonstrates direct usage of pylibjpeg-openjpeg's `encode_pixel_data` and `decode_pixel_data` functions using NumPy arrays. For DICOM integration, you typically register the plugin with `pylibjpeg` and then use `pylibjpeg.decode()`.

import numpy as np
from pylibjpeg_openjpeg import openjpeg

# Example: Encoding a simple NumPy array to JPEG 2000
# For real use, ensure data matches expected type/shape for J2K
width, height = 128, 128
array_data = np.arange(width * height, dtype=np.uint16).reshape((height, width))

# Encode to JPEG 2000 (lossless example)
encoded_data = openjpeg.encode_pixel_data(
    array_data,
    bits_allocated=16,
    bits_stored=16,
    high_bit=15,
    photometric_interpretation='MONOCHROME2',
    samples_per_pixel=1,
    rows=height,
    columns=width,
    j2k_codec='jp2',
    lossless=True
)

print(f"Encoded data length: {len(encoded_data)} bytes")

# Decode the data back
decoded_array, image_format = openjpeg.decode_pixel_data(
    encoded_data,
    rows=height,
    columns=width,
    bits_allocated=16,
    bits_stored=16,
    high_bit=15,
    photometric_interpretation='MONOCHROME2',
    samples_per_pixel=1
)

print(f"Decoded array shape: {decoded_array.shape}, dtype: {decoded_array.dtype}")
assert np.array_equal(array_data, decoded_array)
print("Original and decoded arrays are equal (lossless encoding verified).")

view raw JSON →