dbdicom.Series.pixel_values#

Series.pixel_values(dims=('InstanceNumber',), return_coords=False, slice={}, coords={}, **filters) → ndarray[source]#

Return a numpy.ndarray with pixel data.

Parameters:

  • dims (tuple, optional) – Dimensions of the result, as a tuple of valid DICOM tags of any length. If dims is not provided, pixel values are ordered by instance number. Defaults to None.

  • inds (dict, optional) – Dictionary with indices to retrieve a slice of the entire array. Defaults to None.

  • select (dict, optional) – A dictionary of values for DICOM attributes to filter the result. By default the data are not filtered.

  • filters (dict, optional) – keyword arguments to filter the data by value of DICOM attributes.

Returns:

pixel data. The number of dimensions will be 2 plus the number of elements in dim. The first two indices will enumerate (column, row) indices in the slice, the other dimensions are as specified by the dims argument.

The function returns an empty array when no data are found at the specified locations.

Return type:

np.ndarray

Raises:

  • ValueError – Indices must be in the dimensions provided. If ind is set but keys are not part of dims.

  • ValueError – if the images are different shapes.

See also

set_pixel_values

Example

Create a zero-filled array with 3 slice dimensions:

>>> coords = {
...    'SliceLocation': 10*np.arange(4),
...    'FlipAngle': np.array([2, 15, 30]),
...    'RepetitionTime': np.array([2.5, 5.0]),
... }
>>> zeros = db.zeros((128,64,4,3,2), coords)

Retrieve the pixel array of the series:

>>> dims = tuple(coords)
>>> array = zeros.pixel_values(dims)
>>> array.shape
(128, 64, 4, 3, 2)

To retrieve an array containing only the data with flip angle 15:

>>> array = zeros.pixel_values(dims, FlipAngle=15)
>>> array.shape
(128, 64, 4, 1, 2)

If no data fit the requirement, and empty array is returned:

>>> array = zeros.pixel_values(dims, FlipAngle=15)
>>> array.size
0

Multiple possible values can be specified as an array:

>>> array = zeros.pixel_values(dims, FlipAngle=np.array([15,30]))
>>> array.shape
(128, 64, 4, 2, 2)

And multiple filters can be specified by adding keyword arguments. The following returns an array of pixel values with flip angle of 15 or 30, and slice location of 10 or 20:

>>> array = zeros.pixel_values(dims, FlipAngle=np.array([15,30]), SliceLocation=np.array([10,20]))
>>> array.shape
(128, 64, 2, 2, 2)

The filters can be any DICOM attribute:

>>> array = zeros.pixel_values(dims, AcquisitionTime=0)
>>> array.size
0

The filters can also be specified as a dictionary of values:

>>> array = zeros.pixel_values(dims, select={'FlipAngle': 15})
>>> array.shape
(128, 64, 4, 1, 2)

Since keywords need to be strings in python, this is the only way to specify filters with (group, element) tags:

>>> array = zeros.pixel_values(dims, select={(0x0018, 0x1314): 15})
>>> array.shape
(128, 64, 4, 1, 2)

Using the inds argument, the pixel array can be indexed to avoid reading a large array if only a subarray is required:

>>> array = zeros.pixel_values(dims, inds={'FlipAngle': 1})
>>> array.shape
(128, 64, 4, 1, 2)

Note unlike filters defind by value, the indices must be provided in the dimensions of the array. If not, a ValueError is raised:

>>> zeros.pixel_values(dims, inds={'AcquisitionTime':0})
ValueError: Indices must be in the dimensions provided.

Examples using dbdicom.Series.pixel_values#