{"id":9218,"library":"pylibjpeg-openjpeg","title":"pylibjpeg-openjpeg","description":"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.","status":"active","version":"2.5.0","language":"en","source_language":"en","source_url":"https://github.com/pydicom/pylibjpeg-openjpeg","tags":["DICOM","JPEG 2000","image processing","codec","pylibjpeg plugin","OpenJPEG"],"install":[{"cmd":"pip install pylibjpeg-openjpeg","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Required for array handling and image data processing.","package":"numpy","optional":false},{"reason":"This library is designed as a plugin for pylibjpeg, enabling JPEG 2000 support. Required for its intended integration.","package":"pylibjpeg","optional":true}],"imports":[{"note":"The core functionality (decode/encode) is exposed via the 'openjpeg' submodule.","symbol":"openjpeg","correct":"from pylibjpeg_openjpeg import openjpeg"},{"note":"The 'register_plugin' function belongs to pylibjpeg, not pylibjpeg-openjpeg itself. pylibjpeg-openjpeg is the plugin module *name*.","wrong":"from pylibjpeg_openjpeg import register_plugin","symbol":"register_plugin","correct":"from pylibjpeg import register_plugin\nregister_plugin('openjpeg', 'pylibjpeg_openjpeg')"}],"quickstart":{"code":"import numpy as np\nfrom pylibjpeg_openjpeg import openjpeg\n\n# Example: Encoding a simple NumPy array to JPEG 2000\n# For real use, ensure data matches expected type/shape for J2K\nwidth, height = 128, 128\narray_data = np.arange(width * height, dtype=np.uint16).reshape((height, width))\n\n# Encode to JPEG 2000 (lossless example)\nencoded_data = openjpeg.encode_pixel_data(\n    array_data,\n    bits_allocated=16,\n    bits_stored=16,\n    high_bit=15,\n    photometric_interpretation='MONOCHROME2',\n    samples_per_pixel=1,\n    rows=height,\n    columns=width,\n    j2k_codec='jp2',\n    lossless=True\n)\n\nprint(f\"Encoded data length: {len(encoded_data)} bytes\")\n\n# Decode the data back\ndecoded_array, image_format = openjpeg.decode_pixel_data(\n    encoded_data,\n    rows=height,\n    columns=width,\n    bits_allocated=16,\n    bits_stored=16,\n    high_bit=15,\n    photometric_interpretation='MONOCHROME2',\n    samples_per_pixel=1\n)\n\nprint(f\"Decoded array shape: {decoded_array.shape}, dtype: {decoded_array.dtype}\")\nassert np.array_equal(array_data, decoded_array)\nprint(\"Original and decoded arrays are equal (lossless encoding verified).\")\n","lang":"python","description":"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()`."},"warnings":[{"fix":"Upgrade Python to 3.9 or newer, or use an older pylibjpeg-openjpeg version if tied to an older Python.","message":"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.","severity":"breaking","affected_versions":">=2.0.0, >=2.4.0"},{"fix":"Update calls to `encode_pixel_data` or `encode_buffer` to use `samples_per_pixel` instead of `nr_components`.","message":"The `nr_components` parameter in encoding functions was renamed to `samples_per_pixel` in v2.2.0 to align with DICOM terminology.","severity":"breaking","affected_versions":">=2.2.0"},{"fix":"Ensure your NumPy installation is `numpy>=2.0` if using pylibjpeg-openjpeg v2.4.0+ with Python 3.9+.","message":"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.","severity":"breaking","affected_versions":">=2.4.0"},{"fix":"Convert `bytearray` data to `bytes` or a `numpy.ndarray` before passing it to encoding functions.","message":"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.","severity":"gotcha","affected_versions":">=2.2.1"},{"fix":"Upgrade to pylibjpeg-openjpeg v2.5.0 or newer to benefit from these fixes.","message":"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.","severity":"gotcha","affected_versions":"<2.4.0 (big-endian), <2.5.0 (J2K precision)"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Replace `nr_components` with `samples_per_pixel` in your encoding function calls.","cause":"Using the deprecated `nr_components` parameter in encoding functions after it was renamed to `samples_per_pixel`.","error":"TypeError: encode_pixel_data() got an unexpected keyword argument 'nr_components'"},{"fix":"The `openjpeg` functionality is exposed via the `pylibjpeg_openjpeg.openjpeg` submodule. Use `from pylibjpeg_openjpeg import openjpeg`.","cause":"Attempting to import `openjpeg` directly from the top-level package or a typo.","error":"ImportError: cannot import name 'openjpeg' from 'pylibjpeg_openjpeg' (most likely due to a circular import)"},{"fix":"Convert your `bytearray` data to `bytes` or a `numpy.ndarray` before passing it to `encode_pixel_data` or `encode_buffer`.","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.","error":"TypeError: 'bytearray' object cannot be interpreted as a numpy.ndarray"},{"fix":"Install the `pylibjpeg` library: `pip install 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.","error":"ModuleNotFoundError: No module named 'pylibjpeg'"}]}