Improve interface for DICOM decoding (#6)

Author: scaramallion

README.md

@@ -10,6 +10,13 @@ plugin for [pylibjpeg](http://github.com/pydicom/pylibjpeg).
 Linux, OSX and Windows are all supported.
 
 ### Installation
+#### Dependencies
+[NumPy](http://numpy.org)
+
+#### Installing the current release
+```bash
+pip install pylibjpeg-libjpeg
+```
 #### Installing the development version
 
 Make sure [Python](https://www.python.org/) and [Git](https://git-scm.com/) are installed. For Windows, you also need to install
@@ -20,15 +27,19 @@ python -m pip install pylibjpeg-libjpeg
 ```
 
 ### Supported JPEG Formats
+#### Decoding
 
 | ISO/IEC Standard | ITU Equivalent | JPEG Format |
 | --- | --- | --- |
 | [10918](https://www.iso.org/standard/18902.html) | [T.81](https://www.itu.int/rec/T-REC-T.81/en) | [JPEG](https://jpeg.org/jpeg/index.html)    |
 | [14495](https://www.iso.org/standard/22397.html)   | [T.87](https://www.itu.int/rec/T-REC-T.87/en) | [JPEG-LS](https://jpeg.org/jpegls/index.html) |
 | [18477](https://www.iso.org/standard/62552.html)   | | [JPEG XT](https://jpeg.org/jpegxt/) |
 
-### Supported Transfer Syntaxes
+#### Encoding
+Encoding of JPEG images is not currently supported
 
+### Supported Transfer Syntaxes
+#### Decoding
 | UID | Description |
 | --- | --- |
 | 1.2.840.10008.1.2.4.50 | JPEG Baseline (Process 1) |
@@ -40,7 +51,6 @@ python -m pip install pylibjpeg-libjpeg
 
 ### Usage
 #### With pylibjpeg and pydicom
-Assuming you already have *pylibjpeg* and *pydicom* installed:
 
 ```python
 from pydicom import dcmread

libjpeg/__init__.py

@@ -2,8 +2,9 @@
 
 import sys
 
+from ._config import DICOM_ENCODERS, DICOM_DECODERS
 from ._version import __version__
-from .utils import decode, get_parameters
+from .utils import decode, decode_pixel_data, get_parameters
 
 
 # Add the testing data to libjpeg (if available)

libjpeg/_config.py

@@ -0,0 +1,32 @@
+
+from libjpeg.utils import decode_pixel_data
+
+
+DICOM_DECODERS = {
+     # JPEG Baseline (Process 1)
+    '1.2.840.10008.1.2.4.50' : decode_pixel_data,
+    # JPEG Extended (Processes 2 and 4)
+    '1.2.840.10008.1.2.4.51' : decode_pixel_data,
+    # JPEG Lossless (Process 14)
+    '1.2.840.10008.1.2.4.57' : decode_pixel_data,
+    # JPEG Lossless (Process 14, Selection Value 1)
+    '1.2.840.10008.1.2.4.70' : decode_pixel_data,
+     # JPEG-LS Lossless
+    '1.2.840.10008.1.2.4.80' : decode_pixel_data,
+     # JPEG-LS Near Lossless
+    '1.2.840.10008.1.2.4.81' : decode_pixel_data,
+}
+"""A :class:`dict` of the DICOM (0002,0010) *Transfer Syntax UID* values
+that specify the encoding of the (7FE0,0010) *Pixel Data* that can be decoded
+using this library. The format of the ``dict`` is  ``{UID: callable}``, where
+`callable` the function to use for decoding as
+``callable(arr, photometric_interpretation)``.
+"""
+
+
+DICOM_ENCODERS = {}
+"""A :class:`dict` of the DICOM (0002,0010) *Transfer Syntax UID* values
+that specify the encoding of the (7FEO,0010) *Pixel Data* to be encoded using
+this library. The format of the ``dict`` is ``{UID: callable}``, where
+`callable` the function to use for encoding as ``callable(arr)``.
+"""

libjpeg/_version.py

@@ -1,4 +1,4 @@
-"""Version information for pynetdicom based on PEP396 and 440."""
+"""Version information based on PEP396 and 440."""
 
 import re
 
@@ -41,11 +41,15 @@
 def is_canonical(version):
     """Return True if `version` is a PEP440 conformant version."""
     match = re.match(
-        r'^([1-9]\d*!)?(0|[1-9]\d*)'
-        r'(\.(0|[1-9]\d*))'
-        r'*((a|b|rc)(0|[1-9]\d*))'
-        r'?(\.post(0|[1-9]\d*))'
-        r'?(\.dev(0|[1-9]\d*))?$', version)
+        (
+            r'^([1-9]\d*!)?(0|[1-9]\d*)'
+            r'(\.(0|[1-9]\d*))'
+            r'*((a|b|rc)(0|[1-9]\d*))'
+            r'?(\.post(0|[1-9]\d*))'
+            r'?(\.dev(0|[1-9]\d*))?$'
+        ),
+        version
+    )
 
     return match is not None
 

libjpeg/tests/pydicom_handler.py

@@ -25,7 +25,7 @@
     JPEGLSLossy,
 )
 
-from libjpeg import decode
+from libjpeg import decode_pixel_data
 
 
 HANDLER_NAME = 'libjpeg-test'
@@ -138,6 +138,6 @@ def get_pixeldata(ds):
     for frame, offset in zip(generate_frames, generate_offsets):
         # Encoded JPG data to be sent to the decoder
         frame = np.frombuffer(frame, np.uint8)
-        arr[offset:offset + frame_len] = decode(frame, p_interp, reshape=False)
+        arr[offset:offset + frame_len] = decode_pixel_data(frame, p_interp)
 
     return arr.view(pixel_dtype(ds))

libjpeg/tests/test_decode.py

@@ -10,13 +10,14 @@
 try:
     import pydicom
     from pydicom.encaps import generate_pixel_data_frame
+    from pydicom.pixel_data_handlers.util import reshape_pixel_array
     from . import handler
     HAS_PYDICOM = True
 except ImportError:
     HAS_PYDICOM = False
 
 from . import add_handler, remove_handler
-from libjpeg import decode
+from libjpeg import decode, decode_pixel_data
 from libjpeg.data import get_indexed_datasets, JPEG_DIRECTORY
 
 
@@ -100,11 +101,11 @@ def test_invalid_colourspace_warns():
     ds = index['JPEGBaseline_1s_1f_u_08_08.dcm']['ds']
     nr_frames = ds.get('NumberOfFrames', 1)
     frame = next(generate_pixel_data_frame(ds.PixelData, nr_frames))
-    msg = (
-        r""
-    )
+    msg = r"no colour transformation will be applied"
     with pytest.warns(UserWarning, match=msg):
-        arr = decode(np.frombuffer(frame, 'uint8'), colourspace='ANY')
+        arr = decode_pixel_data(np.frombuffer(frame, 'uint8'), 'ANY')
+
+    arr = reshape_pixel_array(ds, arr)
 
     assert arr.flags.writeable
     assert 'uint8' == arr.dtype

libjpeg/utils.py

@@ -52,17 +52,20 @@
 }
 
 
-def decode(arr, colourspace='YBR_FULL', reshape=True):
+def decode(arr, colour_transform=0, reshape=True):
     """Return the decoded JPEG data from `arr` as a :class:`numpy.ndarray`.
 
     Parameters
     ----------
     arr : numpy.ndarray or bytes
         A 1D array of ``np.uint8``, or a Python :class:`bytes` object
         containing the encoded JPEG image.
-    colourspace : str, optional
-        One of ``'MONOCHROME1'``, ``'MONOCHROME2'``, ``'RGB'``, ``'YBR_FULL'``,
-        ``'YBR_FULL_422'``.
+    colour_transform : int, optional
+        The colour transform used, one of:
+        | ``0`` : No transform applied (default)
+        | ``1`` : RGB to YCbCr
+        | ``2`` : JPEG-LS pseudo RCT or RCT
+        | ``3`` : Freeform
     reshape : bool, optional
         Reshape and review the output array so it matches the image data
         (default), otherwise return a 1D array of ``np.uint8``.
@@ -77,28 +80,10 @@ def decode(arr, colourspace='YBR_FULL', reshape=True):
     RuntimeError
         If the decoding failed.
     """
-    colours = {
-        'MONOCHROME1': 0,
-        'MONOCHROME2' : 0,
-        'RGB' : 1,
-        'YBR_FULL' : 0,
-        'YBR_FULL_422' : 0,
-        -1 : -1,  # For unit testing only
-    }
-
-    try:
-        transform = colours[colourspace]
-    except KeyError:
-        warnings.warn(
-            "Unsupported colour space '{}', no colour transform will "
-            "be applied".format(colourspace)
-        )
-        transform = 0
-
     if isinstance(arr, bytes):
         arr = np.frombuffer(arr, 'uint8')
 
-    status, out, params = _libjpeg.decode(arr, transform)
+    status, out, params = _libjpeg.decode(arr, colour_transform)
     status = status.decode("utf-8")
     code, msg = status.split("::::")
     code = int(code)
@@ -128,6 +113,49 @@ def decode(arr, colourspace='YBR_FULL', reshape=True):
     )
 
 
+def decode_pixel_data(arr, photometric_interp):
+    """Return the decoded JPEG data from `arr` as a :class:`numpy.ndarray`.
+
+    Parameters
+    ----------
+    arr : numpy.ndarray or bytes
+        A 1D array of ``np.uint8``, or a Python :class:`bytes` object
+        containing the encoded JPEG image.
+    photometric_interp : str
+        The (0028,0004) *Photometric Interpretation* of the pixel data, one of
+        ``'MONOCHROME1'``, ``'MONOCHROME2'``, ``'RGB'``, ``'YBR_FULL'``,
+        ``'YBR_FULL_422'``.
+
+    Returns
+    -------
+    numpy.ndarray
+        A 1D array of ``numpy.uint8`` containing the decoded image data.
+
+    Raises
+    ------
+    RuntimeError
+        If the decoding failed.
+    """
+    colours = {
+        'MONOCHROME1': 0,
+        'MONOCHROME2' : 0,
+        'RGB' : 1,
+        'YBR_FULL' : 0,
+        'YBR_FULL_422' : 0,
+    }
+
+    try:
+        transform = colours[photometric_interp]
+    except KeyError:
+        warnings.warn(
+            "Unsupported (0028,0004) Photometric Interpretation '{}', no "
+            "colour transformation will be applied".format(photometric_interp)
+        )
+        transform = 0
+
+    return decode(arr, transform, reshape=False)
+
+
 def get_parameters(arr):
     """Return a :class:`dict` containing JPEG image parameters.