pydicom.pixels.pixel_array¶
- pydicom.pixels.pixel_array(src: str | PathLike[str] | BinaryIO, *, ds_out: Dataset | None = None, specific_tags: list[int] | None = None, index: int | None = None, raw: bool = False, decoding_plugin: str = '', **kwargs: Any) np.ndarray [source]¶
Return decoded pixel data from src as
ndarray
while minimizing memory usage.Warning
This function requires NumPy
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
Return the entire pixel data from a dataset:
arr = pixel_array("path/to/dataset.dcm")
Return the 3rd frame of a dataset containing at least 3 frames:
with open("path/to/dataset.dcm", "rb") as f: arr = pixel_array(f, index=2) # 'index' starts at 0
- Parameters:
src (str | PathLike[str] | file-like) –
str
|os.PathLike
: the path to a DICOM dataset containing pixel data, orfile-like: a file-like object in ‘rb’ mode containing the dataset.
ds_out (pydicom.dataset.Dataset, optional) – A
Dataset
that will be updated with the non-retired group0x0028
image pixel module elements and the group0x0002
file meta information elements from the dataset in src .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.
index (int | None, optional) – If
None
(default) then return an array containing all the frames in the pixel data, otherwise return only the frame from the specified index, which starts at 0 for the first frame.raw (bool, optional) – If
True
then return the decoded pixel data after only minimal processing (see the processing section above). IfFalse
(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 returned. For information on the available plugins for each decoder see the API documentation.
**kwargs – Optional keyword parameters for controlling decoding, please see the decoding options documentation for more information.
- Returns:
The decoded and reshaped pixel data, with shape:
(rows, columns) for single frame, single plane data
(rows, columns, planes) for single frame, multi-plane data
(frames, rows, columns) for multi-frame, single plane data
(frames, rows, columns, planes) for multi-frame, multi-plane data
A writeable
ndarray
is returned by default. For native transfer syntaxes withview_only=True
a read-onlyndarray
will be returned.- Return type: