# 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`