{"id":10108,"library":"pylibjpeg","title":"pylibjpeg: JPEG and DICOM RLE Decoder Framework","description":"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.","status":"active","version":"2.1.0","language":"en","source_language":"en","source_url":"https://github.com/pylibjpeg/pylibjpeg","tags":["DICOM","JPEG","RLE","image-processing","pydicom","medical-imaging"],"install":[{"cmd":"pip install pylibjpeg","lang":"bash","label":"Core framework (includes numpy)"},{"cmd":"pip install pylibjpeg-libjpeg","lang":"bash","label":"For JPEG decoding support"},{"cmd":"pip install pylibjpeg-rle","lang":"bash","label":"For DICOM RLE decoding/encoding support"}],"dependencies":[{"reason":"Required for internal image data processing and array manipulation.","package":"numpy","optional":false},{"reason":"Provides the actual JPEG image decoding backend; required for JPEG functionality.","package":"pylibjpeg-libjpeg","optional":true},{"reason":"Provides the actual DICOM RLE decoding/encoding backend; required for RLE functionality.","package":"pylibjpeg-rle","optional":true}],"imports":[{"symbol":"add_handler","correct":"import pylibjpeg; pylibjpeg.add_handler(...)"},{"note":"The actual JPEG handler is now in the separate `pylibjpeg-libjpeg` package.","wrong":"import pylibjpeg.libjpeg","symbol":"libjpeg","correct":"import pylibjpeg_libjpeg"},{"note":"The actual RLE handler is now in the separate `pylibjpeg-rle` package.","wrong":"import pylibjpeg.rle","symbol":"rle","correct":"import pylibjpeg_rle"}],"quickstart":{"code":"import pydicom\nimport pylibjpeg\nimport os\n\n# Ensure you have installed a backend, e.g., 'pip install pylibjpeg-libjpeg'\n# and optionally 'pip install pylibjpeg-rle' for RLE support.\n\ntry:\n    import pylibjpeg_libjpeg\n    # Register the JPEG handler. For pydicom, registering the top-level package\n    # automatically adds all handlers within it.\n    pylibjpeg.add_handler(pylibjpeg_libjpeg)\n    print(\"pylibjpeg_libjpeg handler successfully added.\")\nexcept ImportError:\n    print(\"Warning: pylibjpeg-libjpeg is not installed. JPEG decoding will not be available.\")\n\ntry:\n    import pylibjpeg_rle\n    pylibjpeg.add_handler(pylibjpeg_rle)\n    print(\"pylibjpeg_rle handler successfully added.\")\nexcept ImportError:\n    print(\"Warning: pylibjpeg-rle is not installed. RLE decoding/encoding will not be available.\")\n\nprint(f\"Current active pylibjpeg handlers: {pylibjpeg.get_handlers()}\")\n\n# Example: Decode a DICOM file using pydicom (requires a valid DICOM file)\n# Set DICOM_FILE_PATH environment variable for testing, e.g., an image with JPEG/RLE compression\ndicom_file_path = os.environ.get('DICOM_FILE_PATH', 'path/to/your/compressed_dicom.dcm')\n\nif os.path.exists(dicom_file_path):\n    try:\n        ds = pydicom.dcmread(dicom_file_path)\n        if hasattr(ds, 'pixel_array'):\n            pixel_array = ds.pixel_array\n            print(f\"Successfully decoded pixel data from '{dicom_file_path}' with shape: {pixel_array.shape}\")\n        else:\n            print(f\"DICOM file '{dicom_file_path}' does not contain pixel data or could not be decoded by available handlers.\")\n    except Exception as e:\n        print(f\"Error reading DICOM file or decoding pixel data: {e}\")\nelse:\n    print(f\"Skipping DICOM decode example: DICOM_FILE_PATH '{dicom_file_path}' not found or not set.\")\n","lang":"python","description":"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."},"warnings":[{"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)`.","message":"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`.","severity":"breaking","affected_versions":">=2.0.0"},{"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)`.","message":"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).","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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()`.","severity":"gotcha","affected_versions":"All versions when used with pydicom"}],"env_vars":null,"last_verified":"2026-04-17T00:00:00.000Z","next_check":"2026-07-16T00:00:00.000Z","problems":[{"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)`.","cause":"Attempting to access `libjpeg` or `rle` directly from the `pylibjpeg` package, which were moved to separate packages in version 2.0.0.","error":"AttributeError: module 'pylibjpeg' has no attribute 'libjpeg'"},{"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.","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.","error":"RuntimeError: No pixel data handler could be found for transfer syntax '1.2.840.10008.1.2.4.90' (or similar transfer syntax UUID)"},{"fix":"Install the missing backend package using pip: `pip install pylibjpeg-libjpeg` (or `pip install pylibjpeg-rle`).","cause":"You are trying to import `pylibjpeg_libjpeg` (or `pylibjpeg_rle`) but the package has not been installed.","error":"ImportError: No module named 'pylibjpeg_libjpeg'"}]}