Pixel Data Decoder Options

The following applies to the functions and class methods that use the pixels backend for decoding pixel data.

When decoding to a NumPy ndarray:

• The Dataset.pixel_array property (configurable via Dataset.pixel_array_options())

• pixel_array()

• iter_pixels()

• decompress()

• Decoder.as_array()

• Decoder.iter_array()

When decoding to a buffer (such as bytes, bytearray or memoryview):

• Decoder.as_buffer()

• Decoder.iter_buffer()

Image Pixel Options

The following options are required when the decoding source src is not a Dataset and are used to describe the encoded pixel data. They may also be used to override the corresponding element values when src is a Dataset:

Option	Type	Corresponding Element		Description
		Tag	Name
rows	int	(0028,0010)	Rows	The number of rows in src
columns	int	(0028,0011)	Columns	The number of columns in src
number_of_frames	int	(0028,0008)	Number of Frames	The number of frames in src
samples_per_pixel	int	(0028,0002)	Samples Per Pixel	The number of samples per pixel
bits_allocated	int	(0028,0100)	Bits Allocated	The number of bits used to contain each pixel
bits_stored	int	(0028,0101)	Bits Stored	The number of bits actually used by each pixel
photometric_interpretation	str	(0028,0004)	Photometric Interpretation	The color space of the encoded pixel data
pixel_representation	int	(0028,0103)	Pixel Representation	Required if pixel_keyword is 'PixelData', whether the pixels are signed or unsigned
planar_configuration	int	(0028,0006)	Planar Configuration	Required if samples_per_pixel > 1, the pixel encoding order
pixel_keyword	str			Required if src uses a native transfer syntax, the keyword of the element containing the pixel data. One of 'PixelData', 'FloatPixelData', 'DoubleFloatPixelData'

Image Processing Options

The following options may be used with any transfer syntax for controlling the processing applied after decoding to a NumPy ndarray:

• as_rgb: bool - if True (default) then convert pixel data with a YCbCr photometric interpretation such as "YBR_FULL_422" to RGB.

• force_rgb: bool - if True then force a YCbCr to RGB color space conversion on the array (default False).

• force_ybr: bool - if True then force an RGB to YCbCr color space conversion on the array (default False).

Miscellaneous Options

The following options may be used with both native (uncompressed) and encapsulated (compressed) transfer syntaxes when decoding to a NumPy ndarray:

• correct_unused_bits: bool - if True (default) and Bits Stored doesn’t equal Bits Allocated then apply bit-shifting operations to correct for any misinterpretation due to the unused bits. For example, if Bits Stored is 5 and Bits Allocated is 8 then the 3 most significant bits are unused. A raw value of 0b00011001 with a Pixel Representation of 1 would therefore be interpreted as the value 25 if correct_unused_bits is False instead of its correct value of -7. However, in most cases this correction shouldn’t be necessary as the unused bits are typically filled with values that will produce the correct interpretation.

The following options may be used with both native (uncompressed) and encapsulated (compressed) transfer syntaxes when decoding to a NumPy ndarray or buffer-like object:

• allow_excess_frames: bool - if True (default) and src contains more frames of data than given by the value of (0028,0008) Number of Frames then include those extra frames in the returned data, otherwise return only the number of frames given by Number of Frames.

The following options may be used with native (uncompressed) transfer syntaxes when decoding to a NumPy ndarray:

• view_only: bool - if True and src is a Dataset or buffer-like then make a best effort attempt to return an ndarray that’s a view on the original buffer (default False). Note that if the original buffer is immutable then the returned ndarray will be read-only.

The following options may be used with encapsulated (compressed) transfer syntaxes of the corresponding type when decoding to a NumPy ndarray:

• apply_jls_sign_correction: bool - if True (default), src contains JPEG-LS compressed pixel data and the pixel representation is 1, then convert the raw decoded pixel values from unsigned to signed integers.

• apply_j2k_sign_correction: bool - if True (default), src contains JPEG 2000 compressed pixel data and the pixel representation doesn’t match the signedness given in the JPEG 2000 codestream, then convert the raw decoded pixel values to match the pixel representation.

Decoding Plugin Options

The following options are plugin and transfer syntax specific.

RLE Lossless

Plugin name	Option	Description
pydicom	rle_segment_order	">" for big endian segment order (default) or "<" for little endian segment order
pylibjpeg	byteorder