NVIDIA nvJPEG2000 CUDA 12

0.10.0.49 verified Sat May 09 auth: no python

NVIDIA native runtime libraries for JPEG 2000 encoding and decoding using GPU acceleration via CUDA 12. The current version is 0.10.0.49, requires Python >=3. It provides a Python wrapper around the nvJPEG2000 library. Release cadence is linked to NVIDIA driver updates.

pip install nvidia-nvjpeg2k-cu12

Common errors

error ModuleNotFoundError: No module named 'nvjpeg2k' ↓

cause Importing without the 'nvidia' prefix.

fix

Use from nvidia import nvjpeg2k or from nvidia.nvjpeg2k import Jpeg2kDecoder.

error RuntimeError: nvJPEG2K error: Invalid parameter value ↓

cause Invalid image dimensions or quality parameters (e.g., non-integer quality, or image not on GPU memory when required).

fix

Ensure image is a numpy array of uint8, uint16, or float32, and dimensions are multiples of 1 (check encoder docs for specific constraints). For quality, use integer 0-100.

error RuntimeError: nvJPEG2K error: Insufficient memory ↓

cause Image resolution too high for available GPU memory.

fix

Reduce image size or use a GPU with more memory. Alternatively, decode in strips if supported.

Warnings

gotcha Ensure you have a compatible NVIDIA GPU and CUDA 12 driver installed. The library does not include the CUDA driver; it expects a system-wide installation. ↓

fix Verify with `nvidia-smi` that CUDA version >=12.0 and a supported GPU are present.

breaking The import path changed from `import nvjpeg2k` (older versions) to `from nvidia import nvjpeg2k` starting with the nvidia-nvjpeg2k-cu12 package. Direct top-level import will raise ModuleNotFoundError. ↓

fix Use `from nvidia import nvjpeg2k` instead of `import nvjpeg2k`.

gotcha The library expects compressed data as bytes for decoding. Passing a numpy array or file handle without reading binary will fail. ↓

fix Always read file as binary (`open(path, 'rb').read()`) or use bytes object.

deprecated Direct use of `nvjpeg2k.Jpeg2kDecoder` without context manager might cause resource leaks in long-running applications. Consider using context managers or explicit `destroy()`. ↓

fix Wrap decoder usage in `with Jpeg2kDecoder() as decoder:` if available; otherwise call `decoder.destroy()` after use.

Imports

nvjpeg2k
wrong
```
import nvjpeg2k
```
correct
```
from nvidia import nvjpeg2k
```
Top-level import fails; must import from nvidia subpackage.

Jpeg2kDecoder

wrong

from nvjpeg2k import Jpeg2kDecoder

correct

from nvidia.nvjpeg2k import Jpeg2kDecoder

Wrong module path: omit 'nvidia.' prefix.

Jpeg2kEncoder

from nvidia.nvjpeg2k import Jpeg2kEncoder

Correct import path.

Quickstart

Demonstrates basic JPEG2000 decode and encode operations using numpy arrays.

import numpy as np
from nvidia import nvjpeg2k
from nvidia.nvjpeg2k import Jpeg2kDecoder, Jpeg2kEncoder

# Decode a JPEG2000 file
with open('input.j2k', 'rb') as f:
    compressed_data = f.read()

decoder = Jpeg2kDecoder()
decoded = decoder.decode(compressed_data)
print(f"Decoded shape: {decoded.shape}, dtype: {decoded.dtype}")

# Encode an image (e.g., random grayscale)
image = np.random.randint(0, 256, (256, 256), dtype=np.uint8)
encoder = Jpeg2kEncoder()
compressed = encoder.encode(image, quality=95)
print(f"Compressed size: {len(compressed)} bytes")