pydicom.pixels.utils.iter_pixels¶

Yield decoded pixel data frames from src as ndarray.

Added in version 3.0.

Warning

This function requires NumPy and may require the installation of additional packages to perform the actual pixel data decompression. See the pixel data decompression documentation for more information.

Memory Usage

To minimize memory usage src should be the path to the dataset or a file-like object containing the dataset.

Processing

The following processing operations on the raw pixel data are always performed:

Natively encoded bit-packed pixel data for a bits allocated of 1 will be unpacked.
Natively encoded pixel data with a photometric interpretation of "YBR_FULL_422" will have it’s sub-sampling removed.
The output array will be reshaped to the specified dimensions.
JPEG-LS or JPEG 2000 encoded data whose signedness doesn’t match the expected pixel representation will be converted to match.

If raw = False (the default) then the following processing operation will also be performed:

Pixel data with a photometric interpretation of "YBR_FULL" or "YBR_FULL_422" will be converted to "RGB".

Examples

Read a DICOM dataset then iterate through all the pixel data frames:

from pydicom import dcmread
from pydicom.pixels import iter_pixels

ds = dcmread("path/to/dataset.dcm")
for arr in iter_pixels(ds):
    print(arr.shape)

Iterate through all the pixel data frames in a dataset while minimizing memory usage:

from pydicom.pixels import iter_pixels

for arr in iter_pixels("path/to/dataset.dcm"):
    print(arr.shape)

Iterate through the even frames for a dataset with 10 frames:

from pydicom.pixels import iter_pixels

with open("path/to/dataset.dcm", "rb") as f:
    for arr in iter_pixels(f, indices=range(0, 10, 2)):
        print(arr.shape)

Parameters:

src (str | PathLike[str] | file-like | pydicom.dataset.Dataset) –
- str | os.PathLike: the path to a DICOM dataset containing pixel data, or
- file-like: a file-like object in ‘rb’ mode containing the dataset.
- Dataset: a dataset instance
ds_out (pydicom.dataset.Dataset, optional) – A Dataset that will be updated with the non-retired group 0x0028 image pixel module elements and the group 0x0002 file meta information elements from the dataset in src. Only available when `src` is a path or file-like.
specific_tags (list[int | pydicom.tag.BaseTag], optional) – A list of additional tags from the dataset in src to be added to the ds_out dataset.
indices (Iterable[int] | None, optional) – If None (default) then iterate through the entire pixel data, otherwise only iterate through the frames specified by indices.
raw (bool, optional) – If True then yield the decoded pixel data after only minimal processing (see the processing section above). If False (default) then additional processing may be applied to convert the pixel data to it’s most commonly used form (such as converting from YCbCr to RGB).
decoding_plugin (str, optional) – The name of the decoding plugin to use when decoding compressed pixel data. If no decoding_plugin is specified (default) then all available plugins will be tried and the result from the first successful one yielded. For information on the available plugins for each decoder see the API documentation.
**kwargs – Optional keyword parameters for controlling decoding are also available, please see the decoding options documentation for more information.

Yields:

numpy.ndarray – A single frame of decoded pixel data with shape:

(rows, columns) for single sample data
(rows, columns, samples) for multi-sample data

A writeable ndarray is yielded by default. For native transfer syntaxes with view_only=True a read-only ndarray will be yielded.