Complete support for WADO-RS

* Add methods for WADO-RS Retrieve Rendered Transaction actions
  (``retrieve_series_rendered()``, ``retrieve_instance_rendered()`` and
  ``retrieve_instance_frames_rendered()``).
* Add ``media_types`` parameter to methods for
  WADO-RS RetrieveStudy, RetrieveSeries, and RetrieveInstance actions
  (``retrieve_study()``, ``retrieve_series()`` and ``retrieve_instance()``) to
  allow users to specify acceptable media type ranges (including transfer
  syntaxes).
* Change ``image_format`` parameter of method ``retrieve_instance_frames()``
  to ``media_types`` for compatibility with other WADO-RS methods and to allow
  users to accept other non-image media types, e.g., to retrieve frames in
  video formats.

Author: hackermd

docs/usage.rst

@@ -321,7 +321,7 @@ Retrieve a set of frames with default transfer syntax ("application/octet-stream
 
 .. code-block:: python
 
-    frames = client.retrieve_frames(
+    frames = client.retrieve_instance_frames(
         study_instance_uid='1.2.826.0.1.3680043.8.1055.1.20111103111148288.98361414.79379639'
         series_instance_uid='1.2.826.0.1.3680043.8.1055.1.20111103111208937.49685336.24517034'
         sop_instance_uid='1.2.826.0.1.3680043.8.1055.1.20111103111208937.40440871.13152534'
@@ -332,7 +332,7 @@ Retrieve a set of frames of a given instances as JPEG compressed image:
 
 .. code-block:: python
 
-    frames = client.retrieve_frames(
+    frames = client.retrieve_instance_frames(
         study_instance_uid='1.2.826.0.1.3680043.8.1055.1.20111103111148288.98361414.79379639'
         series_instance_uid='1.2.826.0.1.3680043.8.1055.1.20111103111208937.49685336.24517034'
         sop_instance_uid='1.2.826.0.1.3680043.8.1055.1.20111103111208937.40440871.13152534'
@@ -344,7 +344,7 @@ Retrieve a set of frames of a given instances as compressed image in any availab
 
 .. code-block:: python
 
-    frames = client.retrieve_frames(
+    frames = client.retrieve_instance_frames(
         study_instance_uid='1.2.826.0.1.3680043.8.1055.1.20111103111148288.98361414.79379639'
         series_instance_uid='1.2.826.0.1.3680043.8.1055.1.20111103111208937.49685336.24517034'
         sop_instance_uid='1.2.826.0.1.3680043.8.1055.1.20111103111208937.40440871.13152534'
@@ -356,7 +356,7 @@ Retrieve a set of frames of a given instances as either JPEG 2000 or JPEG-LS com
 
 .. code-block:: python
 
-    frames = client.retrieve_frames(
+    frames = client.retrieve_instance_frames(
         study_instance_uid='1.2.826.0.1.3680043.8.1055.1.20111103111148288.98361414.79379639'
         series_instance_uid='1.2.826.0.1.3680043.8.1055.1.20111103111208937.49685336.24517034'
         sop_instance_uid='1.2.826.0.1.3680043.8.1055.1.20111103111208937.40440871.13152534'
@@ -368,7 +368,7 @@ Retrieve a set of frames of a given instances as either JPEG, JPEG 2000 or JPEG-
 
 .. code-block:: python
 
-    frames = client.retrieve_frames(
+    frames = client.retrieve_instance_frames(
         study_instance_uid='1.2.826.0.1.3680043.8.1055.1.20111103111148288.98361414.79379639'
         series_instance_uid='1.2.826.0.1.3680043.8.1055.1.20111103111208937.49685336.24517034'
         sop_instance_uid='1.2.826.0.1.3680043.8.1055.1.20111103111208937.40440871.13152534'
@@ -412,7 +412,7 @@ Retrieve a single frame of a multi-frame image instance rendered as a high-quali
 
 .. code-block:: python
 
-    frames = client.retrieve_frames_rendered(
+    frames = client.retrieve_instance_frames_rendered(
         study_instance_uid='1.2.826.0.1.3680043.8.1055.1.20111103111148288.98361414.79379639'
         series_instance_uid='1.2.826.0.1.3680043.8.1055.1.20111103111208937.49685336.24517034'
         sop_instance_uid='1.2.826.0.1.3680043.8.1055.1.20111103111208937.40440871.13152534'

src/dicomweb_client/api.py

@@ -1903,8 +1903,9 @@ def retrieve_instance_rendered(self, study_instance_uid,
                 'retrieval of rendered instance.'.format(common_media_type)
             )
 
-    def retrieve_frames(self, study_instance_uid, series_instance_uid,
-                        sop_instance_uid, frame_numbers, media_types=None):
+    def retrieve_instance_frames(self, study_instance_uid, series_instance_uid,
+                                 sop_instance_uid, frame_numbers,
+                                 media_types=None):
         '''Retrieves one or more frames of an individual DICOM instance.
 
         Parameters
@@ -1961,9 +1962,12 @@ def retrieve_frames(self, study_instance_uid, series_instance_uid,
                 'retrieval of frames.'.format(common_media_type)
             )
 
-    def retrieve_frames_rendered(self, study_instance_uid,
-                                 series_instance_uid, sop_instance_uid,
-                                 frame_number, media_types=None, params=None):
+    def retrieve_instance_frames_rendered(self, study_instance_uid,
+                                          series_instance_uid,
+                                          sop_instance_uid,
+                                          frame_number,
+                                          media_types=None,
+                                          params=None):
         '''Retrieves one or more server-side rendered frames of an
         individual DICOM instance.
 

src/dicomweb_client/cli.py

@@ -311,26 +311,22 @@ def _get_parser():
     )
     retrieve_instance_full_parser.set_defaults(func=_retrieve_instance)
 
-    retrieve_frames_parser = retrieve_subparsers.add_parser(
+    retrieve_instance_frames_parser = retrieve_instance_subparsers.add_parser(
         'frames', description=(
             'Retrieve one or more frames of the pixel data element of an '
             'invidividual DICOM instance.'
         ),
-        parents=[
-            abstract_required_study_parser, abstract_required_series_parser,
-            abstract_required_instance_parser,
-            abstract_save_parser, abstract_retrieve_parser
-        ]
+        parents=[abstract_save_parser, abstract_retrieve_parser]
     )
-    retrieve_frames_parser.add_argument(
+    retrieve_instance_frames_parser.add_argument(
         '--numbers', metavar='NUM', type=int, nargs='+', dest='frame_numbers',
         help='frame numbers'
     )
-    retrieve_frames_parser.add_argument(
+    retrieve_instance_frames_parser.add_argument(
         '--show', action='store_true',
         help='display retrieved images'
     )
-    retrieve_frames_parser.set_defaults(func=_retrieve_frames)
+    retrieve_instance_frames_parser.set_defaults(func=_retrieve_instance_frames)
 
     # WADO - bulkdata
     retrieve_bulkdata_parser = retrieve_subparsers.add_parser(
@@ -634,7 +630,7 @@ def _retrieve_instance_metadata(args):
         _print_metadata(metadata, args.prettify, args.dicomize)
 
 
-def _retrieve_frames(args):
+def _retrieve_instance_frames(args):
     '''Retrieves frames for an individual instances and either
     writes them to standard output or files on disk or displays them in a GUI
     (depending on the requested content type).
@@ -648,7 +644,7 @@ def _retrieve_frames(args):
         ca_bundle=args.ca_bundle,
         cert=args.cert
     )
-    pixel_data = client.retrieve_frames(
+    pixel_data = client.retrieve_instance_frames(
         args.study_instance_uid, args.series_instance_uid,
         args.sop_instance_uid, args.frame_numbers,
         media_types=args.media_types,

src/dicomweb_client/tests/test_api.py

@@ -367,7 +367,7 @@ def test_retrieve_instance_wrong_mime_type(httpserver, client, cache_dir):
         )
 
 
-def test_retrieve_frames_jpeg(httpserver, client, cache_dir):
+def test_retrieve_instance_frames_jpeg(httpserver, client, cache_dir):
     cache_filename = os.path.join(cache_dir, 'retrieve_instance_pixeldata.jpg')
     with open(cache_filename, 'rb') as f:
         content = f.read()
@@ -380,7 +380,7 @@ def test_retrieve_frames_jpeg(httpserver, client, cache_dir):
     sop_instance_uid = '1.2.5'
     frame_numbers = [114]
     frame_list = ','.join([str(n) for n in frame_numbers])
-    result = client.retrieve_frames(
+    result = client.retrieve_instance_frames(
         study_instance_uid, series_instance_uid, sop_instance_uid,
         frame_numbers, media_types=('image/jpeg', )
     )
@@ -394,8 +394,9 @@ def test_retrieve_frames_jpeg(httpserver, client, cache_dir):
     assert request.accept_mimetypes[0][0][:36] == headers['content-type'][:36]
 
 
-def test_retrieve_frames_jpeg_default_transfer_syntax(httpserver, client,
-                                                      cache_dir):
+def test_retrieve_instance_frames_jpeg_default_transfer_syntax(httpserver,
+                                                               client,
+                                                               cache_dir):
     cache_filename = os.path.join(cache_dir, 'retrieve_instance_pixeldata.jpg')
     with open(cache_filename, 'rb') as f:
         content = f.read()
@@ -407,7 +408,7 @@ def test_retrieve_frames_jpeg_default_transfer_syntax(httpserver, client,
     series_instance_uid = '1.2.4'
     sop_instance_uid = '1.2.5'
     frame_numbers = [114]
-    client.retrieve_frames(
+    client.retrieve_instance_frames(
         study_instance_uid, series_instance_uid, sop_instance_uid,
         frame_numbers, media_types=(
             ('image/jpeg', '1.2.840.10008.1.2.4.50', ),
@@ -417,7 +418,7 @@ def test_retrieve_frames_jpeg_default_transfer_syntax(httpserver, client,
     assert request.accept_mimetypes[0][0][:36] == headers['content-type'][:36]
 
 
-def test_retrieve_frames_jp2(httpserver, client, cache_dir):
+def test_retrieve_instance_frames_jp2(httpserver, client, cache_dir):
     cache_filename = os.path.join(cache_dir, 'retrieve_instance_pixeldata.jp2')
     with open(cache_filename, 'rb') as f:
         content = f.read()
@@ -430,7 +431,7 @@ def test_retrieve_frames_jp2(httpserver, client, cache_dir):
     sop_instance_uid = '1.2.5'
     frame_numbers = [114]
     frame_list = ','.join([str(n) for n in frame_numbers])
-    result = client.retrieve_frames(
+    result = client.retrieve_instance_frames(
         study_instance_uid, series_instance_uid, sop_instance_uid,
         frame_numbers, media_types=('image/jp2', )
     )
@@ -444,7 +445,7 @@ def test_retrieve_frames_jp2(httpserver, client, cache_dir):
     assert request.accept_mimetypes[0][0][:35] == headers['content-type'][:35]
 
 
-def test_retrieve_frames_rendered_jpeg(httpserver, client, cache_dir):
+def test_retrieve_instance_frames_rendered_jpeg(httpserver, client, cache_dir):
     cache_filename = os.path.join(cache_dir, 'retrieve_instance_pixeldata.jpg')
     with open(cache_filename, 'rb') as f:
         content = f.read()
@@ -456,7 +457,7 @@ def test_retrieve_frames_rendered_jpeg(httpserver, client, cache_dir):
     series_instance_uid = '1.2.4'
     sop_instance_uid = '1.2.5'
     frame_numbers = [1]
-    result = client.retrieve_frames_rendered(
+    result = client.retrieve_instance_frames_rendered(
         study_instance_uid, series_instance_uid, sop_instance_uid,
         frame_numbers, media_types=('image/jpeg', )
     )
@@ -472,21 +473,22 @@ def test_retrieve_frames_rendered_jpeg(httpserver, client, cache_dir):
     assert request.accept_mimetypes[0][0][:11] == headers['content-type'][:11]
 
 
-def test_retrieve_frames_rendered_jpeg_transfer_syntax(httpserver, client):
+def test_retrieve_instance_frames_rendered_jpeg_transfer_syntax(httpserver,
+                                                                client):
     study_instance_uid = '1.2.3'
     series_instance_uid = '1.2.4'
     sop_instance_uid = '1.2.5'
     frame_numbers = [1]
     with pytest.raises(TypeError):
-        client.retrieve_frames_rendered(
+        client.retrieve_instance_frames_rendered(
             study_instance_uid, series_instance_uid, sop_instance_uid,
             frame_numbers, media_types=(
                 ('image/jpeg', '1.2.840.10008.1.2.4.50', ),
             )
         )
 
 
-def test_retrieve_frames_rendered_png(httpserver, client, cache_dir):
+def test_retrieve_instance_frames_rendered_png(httpserver, client, cache_dir):
     cache_filename = os.path.join(cache_dir, 'retrieve_instance_pixeldata.png')
     with open(cache_filename, 'rb') as f:
         content = f.read()
@@ -498,7 +500,7 @@ def test_retrieve_frames_rendered_png(httpserver, client, cache_dir):
     series_instance_uid = '1.2.4'
     sop_instance_uid = '1.2.5'
     frame_numbers = [1]
-    result = client.retrieve_frames_rendered(
+    result = client.retrieve_instance_frames_rendered(
         study_instance_uid, series_instance_uid, sop_instance_uid,
         frame_numbers, media_types=('image/png', )
     )

src/dicomweb_client/tests/test_cli.py

@@ -425,14 +425,14 @@ def test_parse_retrieve_instance_metadata_missing_argument_3(parser):
         ])
 
 
-def test_parse_retrieve_frames(parser):
+def test_parse_retrieve_instance_frames(parser):
     args = parser.parse_args([
-        '--url', 'http://localhost:8002', 'retrieve', 'frames',
+        '--url', 'http://localhost:8002', 'retrieve', 'instances',
         '--study', '1.2.3', '--series', '1.2.4', '--instance', '1.2.5',
-        '--numbers', '1'
+        'frames', '--numbers', '1',
     ])
     assert getattr(args, 'method') == 'retrieve'
-    assert getattr(args, 'wado_ie') == 'frames'
+    assert getattr(args, 'wado_ie') == 'instances'
     assert getattr(args, 'study_instance_uid') == '1.2.3'
     assert getattr(args, 'series_instance_uid') == '1.2.4'
     assert getattr(args, 'sop_instance_uid') == '1.2.5'
@@ -446,14 +446,14 @@ def test_parse_retrieve_frames(parser):
         assert getattr(args, 'dicomize')
 
 
-def test_parse_retrieve_frames_multiple(parser):
+def test_parse_retrieve_instance_frames_multiple(parser):
     args = parser.parse_args([
-        '--url', 'http://localhost:8002', 'retrieve', 'frames',
+        '--url', 'http://localhost:8002', 'retrieve', 'instances',
         '--study', '1.2.3', '--series', '1.2.4', '--instance', '1.2.5',
-        '--numbers', '1', '2', '3'
+        'frames', '--numbers', '1', '2', '3',
     ])
     assert getattr(args, 'method') == 'retrieve'
-    assert getattr(args, 'wado_ie') == 'frames'
+    assert getattr(args, 'wado_ie') == 'instances'
     assert getattr(args, 'study_instance_uid') == '1.2.3'
     assert getattr(args, 'series_instance_uid') == '1.2.4'
     assert getattr(args, 'sop_instance_uid') == '1.2.5'
@@ -467,56 +467,56 @@ def test_parse_retrieve_frames_multiple(parser):
         assert getattr(args, 'dicomize')
 
 
-def test_parse_retrieve_frames_show(parser):
+def test_parse_retrieve_instance_frames_show(parser):
     args = parser.parse_args([
-        '--url', 'http://localhost:8002', 'retrieve', 'frames',
+        '--url', 'http://localhost:8002', 'retrieve', 'instances',
         '--study', '1.2.3', '--series', '1.2.4', '--instance', '1.2.5',
-        '--numbers', '1', '--show'
+        'frames', '--numbers', '1', '--show',
     ])
     assert getattr(args, 'show') is True
     assert getattr(args, 'save') is False
     assert getattr(args, 'output_dir') == tempfile.gettempdir()
 
 
-def test_parse_retrieve_frames_save(parser):
+def test_parse_retrieve_instance_frames_save(parser):
     args = parser.parse_args([
-        '--url', 'http://localhost:8002', 'retrieve', 'frames',
+        '--url', 'http://localhost:8002', 'retrieve', 'instances',
         '--study', '1.2.3', '--series', '1.2.4', '--instance', '1.2.5',
-        '--numbers', '1', '--save'
+        'frames', '--numbers', '1', '--save',
     ])
     assert getattr(args, 'show') is False
     assert getattr(args, 'save') is True
     assert getattr(args, 'output_dir') == tempfile.gettempdir()
 
 
-def test_parse_retrieve_frames_show_save(parser):
+def test_parse_retrieve_instance_frames_show_save(parser):
     args = parser.parse_args([
-        '--url', 'http://localhost:8002', 'retrieve', 'frames',
+        '--url', 'http://localhost:8002', 'retrieve', 'instances',
         '--study', '1.2.3', '--series', '1.2.4', '--instance', '1.2.5',
-        '--numbers', '1', '--save', '--show'
+        'frames', '--numbers', '1', '--save', '--show'
     ])
     assert getattr(args, 'show') is True
     assert getattr(args, 'save') is True
     assert getattr(args, 'output_dir') == tempfile.gettempdir()
 
 
-def test_parse_retrieve_frames_save_file(parser):
+def test_parse_retrieve_instance_frames_save_file(parser):
     args = parser.parse_args([
-        '--url', 'http://localhost:8002', 'retrieve', 'frames',
+        '--url', 'http://localhost:8002', 'retrieve', 'instances',
         '--study', '1.2.3', '--series', '1.2.4', '--instance', '1.2.5',
-        '--numbers', '1', '--save', '--output-dir', '/tmp'
+        'frames', '--numbers', '1', '--save', '--output-dir', '/tmp',
     ])
     assert getattr(args, 'show') is False
     assert getattr(args, 'save') is True
     assert getattr(args, 'output_dir') == '/tmp'
 
 
-def test_parse_retrieve_frames_missing_argument(parser):
+def test_parse_retrieve_instance_frames_missing_argument(parser):
     with pytest.raises(SystemExit):
         parser.parse_args([
-            '--url', 'http://localhost:8002', 'retrieve', 'frames',
+            '--url', 'http://localhost:8002', 'retrieve', 'instances',
             '--study', '1.2.3', '--series', '1.2.4', '--instance', '1.2.5',
-            '--numbers'
+            'frames', '--numbers',
         ])