dbdicom.Series.ndarray#

Series.ndarray(dims=('InstanceNumber',), coords: dict | None = None, slice: dict | None = None) → 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. Defaults to (‘InstanceNumber’,).
coords (dict, optional) – Dictionary with coordinates to retrieve a slice of the entire array. If coords is provided, the dims argument is ignored.
slice (dict, optional) – Dictionary with coordinates to retrieve a slice of the entire array. If slice is provided, then the dims argument is ignored. The difference with coords is that the dictionary values in slice specify the indices rather than the values of the coordinates.

Returns:

pixel data. The number of dimensions will be 2 plus the number of elements in dim, or the number of entries in slice or islice. The first two indices will enumerate (x,y) coordinates in the slice, the other dimensions are as specified by the dims, slice or islice argument.

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

Return type:

np.ndarray

See also

set_ndarray()

Example

Create a zero-filled array, describing 8 MRI slices (10mm apart) each measured at 3 flip angles and 2 repetition times:

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

To retrieve the array, the dimensions need to be provided:

>>> dims = ('SliceLocation', 'FlipAngle', 'RepetitionTime')
>>> array = zeros.ndarray(dims)
>>> print(array.shape)
(128, 128, 8, 3, 2)

Note the dimensions are the keys of the coordinate dictionary, so this could also have been called as:

>>> array = zeros.ndarray(dims=tuple(coords))
>>> print(array.shape)
(128, 128, 8, 3, 2)

To retrieve a slice of the volume, specify the coordinates of the slice as a dictionary. For instance, to retrieve the pixel data measured with a flip angle of 15:

>>> coords = {
...    'SliceLocation': 10*np.arange(8),
...    'FlipAngle': [15],
...    'RepetitionTime': [2.5, 5.0],
... }

Now pass this as coordinates in the call to ndarray:

>>> array = zeros.ndarray(coords=coords)
>>> print(array.shape)
(128, 128, 8, 1, 2)

A slice can also be specified with indices rather than absolute values of the coordinates:

>>> slice = {
...    'SliceLocation': np.arange(8),
...    'FlipAngle': [1],
...    'RepetitionTime': np.arange(2),
... }

Now pass this as index coordinates in the call to ndarray:

>>> array = zeros.ndarray(slice=slice)
>>> print(array.shape)
(128, 128, 8, 1, 2)