pyjpegls

1.5.1 verified Fri May 01 auth: no python

Python wrapper for the CharLS C++ library, providing JPEG-LS lossless and near-lossless image compression. Current version 1.5.1, requires Python >=3.9. Active development with occasional releases.

pip install pyjpegls

Common errors

error ValueError: Invalid interleave mode for given image dimensions ↓

cause Using InterleaveMode.NONE for a color (multi-plane) image.

fix

Set interleave_mode=InterleaveMode.SAMPLE for pixel-interleaved color images (shape H,W,3).

error ValueError: Unsupported data type: float32 ↓

cause Input array dtype is not one of uint8, int16, uint16.

fix

Cast image to supported dtype: image = image.astype(np.uint8) or np.int16, np.uint16.

error AttributeError: module 'pyjpegls' has no attribute 'encode' ↓

cause Outdated pyjpegls version (<1.0) or import from wrong module. The encode/decode functions are top-level since v1.0.

fix

Install pyjpegls >=1.0 and use: from pyjpegls import encode. For older versions use: from pyjpegls._core import encode.

error ValueError: can only convert an array of size 1 to a Python scalar ↓

cause Attempting to encode a 2D array with InterleaveMode.SAMPLE (which expects 3D).

fix

Use interleave_mode=InterleaveMode.NONE for grayscale (2D) images.

Warnings

gotcha The library expects numpy arrays in (height, width) order, not (width, height). Misordered dimensions can cause silent incorrect encoding or runtime errors. ↓

fix Ensure your numpy array shape is (height, width, channels) for color or (height, width) for grayscale.

gotcha Supported input dtypes are uint8, int16, and uint16 only (including signed/unsigned). Using other dtypes (e.g., float32) will raise a ValueError. ↓

fix Cast your array to one of the supported types before encoding: image.astype(np.uint8) or np.int16 or np.uint16.

gotcha For color (multi-plane) images, the array should be in (height, width, planes) order and must use InterleaveMode.SAMPLE (pixel interleaved) or InterleaveMode.LINE (line interleaved). InterleaveMode.NONE is for single-plane grayscale only. ↓

fix For RGB images: ensure shape is (H, W, 3) and use InterleaveMode.SAMPLE.

gotcha The decode function returns a numpy array; it does not return a PIL Image or any other object. Converting to PIL requires explicit conversion. ↓

fix Use Image.fromarray(decoded) if you need a PIL Image (after appropriate mode/format conversion).

Imports

encode
```
from pyjpegls import encode
```
Primary encoding function; also available as pyjpegls.encode
decode
```
from pyjpegls import decode
```
Primary decoding function; also available as pyjpegls.decode
ImageFormat
```
from pyjpegls import ImageFormat
```
Enum specifying allowed source array data types

interleave_mode

wrong

from pyjpegls import InterleavMode

correct

from pyjpegls import InterleaveMode

Common misspelling: 'Interleave' not 'Interleav'

JpegLSEncoderInfo
wrong
```
from pyjpegls.encoder import JpegLSEncoderInfo
```
correct
```
from pyjpegls import JpegLSEncoderInfo
```
Encapsulates encoding result metadata, including width/height/compute_lossless

Quickstart

Encode and decode a grayscale image with default lossless settings.

import numpy as np
from pyjpegls import encode, decode, ImageFormat, InterleaveMode

# Create a sample 8-bit grayscale image (height, width)
image = np.random.randint(0, 256, size=(256, 256), dtype=np.uint8)

# Encode (lossless by default)
encoded = encode(image, interleave_mode=InterleaveMode.NONE)
print(f"Encoded size: {len(encoded)} bytes")

# Decode back
decoded = decode(encoded)
print(f"Decoded shape: {decoded.shape}, dtype: {decoded.dtype}")

# Verify lossless reconstruction
assert np.array_equal(image, decoded), "Lossless check failed"