Merge pull request #320 from ImagingDataCommons/feature/get_frames_method

Add get_frames and get_stored_frames methods

Author: CPBridge

docs/image.rst

@@ -124,6 +124,17 @@ processing unnecessary frames. If you know that you are likely to access frames
 multiple times, you can force caching of the stored values by accessing the
 ``.pixel_array`` property (inherited from ``pydicom.Dataset``).
 
+Additionally, there are two methods for accessing multiple frames at a time:
+
+* :meth:`highdicom.Image.get_stored_frames()`: Returns a stack of multiple
+  stored frames. The first parameter is a list (or other iterable) of frame
+  numbers. If omitted, all frames are returned in the order they are stored in
+  the image.
+* :meth:`highdicom.Image.get_frames()`: Returns a stack of multiple
+  frames with pixel transforms applied. The first parameter is a list (or other
+  iterable) of frame numbers. If omitted, all frames are returned in the order
+  they are stored in the image.
+
 Accessing Total Pixel Matrices
 ------------------------------
 

docs/pixel_transforms.rst

@@ -50,6 +50,7 @@ The :class:`highdicom.Image` class has several methods that return frames or
 arrangements of frames from a DICOM image:
 
 * :meth:`highdicom.Image.get_frame()`
+* :meth:`highdicom.Image.get_frames()`
 * :meth:`highdicom.Image.get_volume()`
 * :meth:`highdicom.Image.get_total_pixel_matrix()`
 

docs/seg.rst

@@ -345,8 +345,6 @@ segmentation type.
 
 .. code-block:: python
 
-    import numpy as np
-
     from pydicom.sr.codedict import codes
     from pydicom.data import get_testdata_file
 
@@ -355,13 +353,8 @@ segmentation type.
     # Load an enhanced (multiframe) CT image
     source_image = hd.imread(get_testdata_file('eCT_Supplemental.dcm'))
 
-    # Stack all the frames of the image
-    image_array = np.stack(
-        [
-            source_image.get_frame(i + 1)
-            for i in range(source_image.number_of_frames)
-        ]
-    )
+    # Get a stack of all the frames of the image
+    image_array = source_image.get_frames()
 
     # Create a segmentation by thresholding the CT image at 0 HU
     mask = image_array > 0