pylibjpeg 1.1.0

A Python framework for decoding JPEG files, with a focus on supporting pydicom

pylibjpeg

A Python 3.6+ framework for decoding JPEG images, with a focus on providing JPEG support for pydicom.

Installation

Installing the current release

pip install pylibjpeg

Installing the development version

Make sure Git is installed, then

git clone https://github.com/pydicom/pylibjpeg
python -m pip install pylibjpeg

Plugins

One or more plugins are required before pylibjpeg is able to decode JPEG images. To decode a given JPEG format or DICOM Transfer Syntax you first have to install the corresponding package:

JPEG Format

Format	Decode?	Encode?	Plugin	Based on
JPEG, JPEG-LS and JPEG XT	Yes	No	pylibjpeg-libjpeg	libjpeg
JPEG 2000	Yes	No	pylibjpeg-openjpeg	openjpeg

DICOM Transfer Syntax

UID	Description	Plugin
1.2.840.10008.1.2.4.50	JPEG Baseline (Process 1)	pylibjpeg-libjpeg
1.2.840.10008.1.2.4.51	JPEG Extended (Process 2 and 4)	pylibjpeg-libjpeg
1.2.840.10008.1.2.4.57	JPEG Lossless, Non-Hierarchical (Process 14)	pylibjpeg-libjpeg
1.2.840.10008.1.2.4.70	JPEG Lossless, Non-Hierarchical, First-Order Prediction (Process 14, Selection Value 1)	pylibjpeg-libjpeg
1.2.840.10008.1.2.4.80	JPEG-LS Lossless	pylibjpeg-libjpeg
1.2.840.10008.1.2.4.81	JPEG-LS Lossy (Near-Lossless) Image Compression	pylibjpeg-libjpeg
1.2.840.10008.1.2.4.90	JPEG 2000 Image Compression (Lossless Only)	pylibjpeg-openjpeg
1.2.840.10008.1.2.4.91	JPEG 2000 Image Compression	pylibjpeg-openjpeg
1.2.840.10008.1.2.5	RLE Lossless	Not yet supported

If you're not sure what the dataset's Transfer Syntax UID is, it can be determined with:

>>> from pydicom import dcmread
>>> ds = dcmread('path/to/dicom_file')
>>> ds.file_meta.TransferSyntaxUID.name

Usage

With pydicom

Assuming you already have pydicom v1.4+ and suitable plugins installed:

from pydicom import dcmread
from pydicom.data import get_testdata_file

# Importing the package adds the pixel data handler to pydicom
import pylibjpeg

# With the pylibjpeg-libjpeg plugin
ds = dcmread(get_testdata_file('JPEG-LL.dcm'))
jpg_arr = ds.pixel_array

# With the pylibjpeg-openjpeg plugin
ds = dcmread(get_testdata_file('JPEG2000.dcm'))
j2k_arr = ds.pixel_array

For datasets with multiple frames you can reduce your memory usage by processing each frame separately using the generate_frames() generator function:

from pydicom import dcmread
from pydicom.data import get_testdata_file

from pylibjpeg import generate_frames

ds = dcmread(get_testdata_file('color3d_jpeg_baseline.dcm'))
frames = generate_frames(ds)
arr = next(frames)

Standalone JPEG decoding

You can also just use pylibjpeg to decode JPEG images to a numpy ndarray, provided you have a suitable plugin installed:

from pylibjpeg import decode

# Can decode using the path to a JPG file as str or path-like
arr = decode('filename.jpg')

# Or a file-like...
with open('filename.jpg', 'rb') as f:
    arr = decode(f)

# Or bytes...
with open('filename.jpg', 'rb') as f:
    arr  = decode(f.read())