"""The medical image object.
This module defines :class:`MedicalVolume`, which is a wrapper for nD volumes.
"""
import warnings
from copy import deepcopy
from mmap import mmap
from numbers import Number
from typing import Sequence, Tuple, Union
import nibabel as nib
import numpy as np
import pydicom
from nibabel.spatialimages import SpatialFirstSlicer as _SpatialFirstSlicerNib
from numpy.lib.mixins import NDArrayOperatorsMixin
from packaging import version
from dosma.core import orientation as stdo
from dosma.core.device import Device, cpu_device, get_array_module, get_device, to_device
from dosma.core.io.format_io import ImageDataFormat
from dosma.defaults import SCANNER_ORIGIN_DECIMAL_PRECISION
from dosma.utils import env
if env.sitk_available():
import SimpleITK as sitk
if env.cupy_available():
import cupy as cp
if env.package_available("h5py"):
import h5py
__all__ = ["MedicalVolume"]
# PyTorch version introducing complex tensor support.
_TORCH_COMPLEX_SUPPORT_VERSION = version.Version("1.5.0")
[docs]class MedicalVolume(NDArrayOperatorsMixin):
"""The class for medical images.
Medical volumes use ndarrays to represent medical data. However, unlike standard ndarrays,
these volumes have inherent spatial metadata, such as pixel/voxel spacing, global coordinates,
rotation information, all of which can be characterized by an affine matrix following the
RAS+ coordinate system. The code below creates a random 300x300x40 medical volume with
scanner origin ``(0, 0, 0)`` and voxel spacing of ``(1,1,1)``:
>>> mv = MedicalVolume(np.random.rand(300, 300, 40), np.eye(4))
Medical volumes can also store header information that accompanies pixel data
(e.g. DICOM headers). These headers are used to expose metadata, which can be fetched
and set using :meth:`get_metadata()` and :meth:`set_metadata()`, respectively. Headers are
also auto-aligned, which means that headers will be aligned with the slice(s) of data from
which they originated, which makes Python slicing feasible. Currently, medical volumes
support DICOM headers using ``pydicom`` when loaded with :class:`dosma.DicomReader`.
>>> mv.get_metadata("EchoTime") # Returns EchoTime
>>> mv.set_metadata("EchoTime", 10.0) # Sets EchoTime to 10.0
Standard math and boolean operations are supported with other ``MedicalVolume`` objects,
numpy arrays (following standard broadcasting), and scalars. Boolean operations are performed
elementwise, resulting in a volume with shape as ``self.volume.shape``.
If performing operations between ``MedicalVolume`` objects, both objects must have
the same shape and affine matrix (spacing, direction, and origin). Header information
is not deep copied when performing these operations to reduce computational and memory
overhead. The affine matrix (``self.affine``) is copied as it is lightweight and
often modified.
2D images are also supported when viewed trivial 3D volumes with shape ``(H, W, 1)``:
>>> mv = MedicalVolume(np.random.rand(10,20,1), np.eye(4))
Many operations are in-place and modify the instance directly (e.g. `reformat(inplace=True)`).
To allow chaining operations, operations that are in-place return ``self``.
>>> mv2 = mv.reformat(ornt, inplace=True)
>>> id(mv2) == id(mv)
True
Medical volumes can interface with the gpu using the :mod:`cupy` library.
Volumes can be moved between devices (see :class:`Device`) using the ``.to()`` method.
Only the volume data will be moved to the gpu. Headers and affine matrix will remain on
the cpu. The following code moves a MedicalVolume to gpu 0 and back to the cpu:
>>> from dosma import Device
>>> mv = MedicalVolume(np.random.rand((10,20,30)), np.eye(4))
>>> mv_gpu = mv.to(Device(0))
>>> mv_cpu = mv.cpu()
Note, moving data across devices results in a full copy. Above, ``mv_cpu.volume`` and
``mv.volume`` do not share memory. Saving volumes and converting to other images
(e.g. ``SimpleITK.Image``) are only supported for cpu volumes. Volumes can also only
be compared when on the same device. For example, both commands below will raise a
RuntimeError:
>>> mv_gpu == mv_cpu
>>> mv_gpu.is_identical(mv_cpu)
While CuPy requires the current device be set using ``cp.cuda.Device(X).use()`` or inside
the ``with`` context, ``MedicalVolume`` automatically sets the appropriate context
for performing operations. This means the CuPy current device need to be the same as the
``MedicalVolume`` object. For example, the following still works:
>>> cp.cuda.Device(0).use()
>>> mv_gpu = MedicalVolume(cp.ones((3,3,3)), np.eye(4))
>>> cp.cuda.Device(1).use()
>>> mv_gpu *= 2
MedicalVolumes also have a limited NumPy/CuPy-compatible interface.
Standard numpy/cupy functions that preserve array shapes can be performed
on MedicalVolume objects:
>>> log_arr = np.log(mv)
>>> type(log_arr)
<class 'dosma.io.MedicalVolume'>
>>> exp_arr_gpu = cp.exp(mv_gpu)
>>> type(exp_arr_gpu)
<class 'dosma.io.MedicalVolume'>
**ALPHA**: MedicalVolumes are also interoperable with popular image data structures
with zero-copy, meaning array data will not be copied. Formats currently include the
SimpleITK Image, Nibabel Nifti1Image, and PyTorch tensors:
>>> sitk_img = mv.to_sitk() # Convert to SimpleITK Image
>>> mv_from_sitk = MedicalVolume.from_sitk(sitk_img) # Convert back to MedicalVolume
>>> nib_img = mv.to_nib() # Convert to nibabel Nifti1Image
>>> mv_from_nib = MedicalVolume.from_nib(nib_img)
>>> torch_tensor = mv.to_torch() # Convert to torch tensor
>>> mv_from_tensor = MedicalVolume.from_torch(torch_tensor, affine)
**ALPHA**: MedicalVolumes can also be used with memmapped arrays.
This makes loading much faster and allows interaction with larger-than-memory
arrays. Only when the volume is modified will the volume be loaded
into memory and modified. If you take a slice of the memmaped array, the underlying
array will also remain memmapped:
>>> arr = np.load("/path/to/volume.npy", mmap_mode="r")
>>> mv = MedicalVolume(arr, np.eye(4))
>>> mv.is_mmap # returns True
We also preserve Nibabel's memmapping of certain file types (e.g. ``.nii``):
>>> nib_img = nibabel.load("path/to/volume.nii")
>>> mv = MedicalVolume.from_nib(nib_img, mmap=True)
Args:
volume (array-like): nD medical image.
affine (array-like): 4x4 array corresponding to affine matrix transform in RAS+ coordinates.
Must be on cpu (i.e. no ``cupy.ndarray``).
headers (array-like[pydicom.FileDataset]): Headers for DICOM files.
"""
[docs] def __init__(self, volume, affine, headers=None):
if not isinstance(volume, np.memmap):
xp = get_array_module(volume)
volume = xp.asarray(volume)
self._volume = volume
self._affine = np.array(affine)
self._headers = self._validate_and_format_headers(headers) if headers is not None else None
def save_volume(self, file_path: str, data_format: ImageDataFormat = ImageDataFormat.nifti):
"""Write volumes in specified data format.
Args:
file_path (str): File path to save data. May be modified to follow convention
given by the data format in which the volume will be saved.
data_format (ImageDataFormat): Format to save data.
"""
import dosma.core.io.format_io_utils
device = self.device
if device != cpu_device:
raise RuntimeError(f"MedicalVolume must be on cpu, got {self.device}")
writer = dosma.core.io.format_io_utils.get_writer(data_format)
writer.save(self, file_path)
def reformat(self, new_orientation: Sequence, inplace: bool = False) -> "MedicalVolume":
"""Reorients volume to a specified orientation.
Flipping and transposing the volume array (``self.volume``) returns a view if possible.
Reorientation method:
---------------------
- Axis transpose and flipping are linear operations and therefore can be treated
independently.
- working example: ('AP', 'SI', 'LR') --> ('RL', 'PA', 'SI')
1. Transpose volume and RAS orientation to appropriate column in matrix
eg. ('AP', 'SI', 'LR') --> ('LR', 'AP', 'SI') - transpose_inds=[2, 0, 1]
2. Flip volume across corresponding axes
eg. ('LR', 'AP', 'SI') --> ('RL', 'PA', 'SI') - flip axes 0,1
Reorientation method implementation:
------------------------------------
1. Transpose: Switching (transposing) axes in volume is the same as switching columns
in affine matrix
2. Flipping: Negate each column corresponding to pixel axis to flip (i, j, k) and
reestablish origins based on flipped axes
Args:
new_orientation (Sequence): New orientation.
inplace (bool, optional): If `True`, do operation in-place and return ``self``.
Returns:
MedicalVolume: The reformatted volume. If ``inplace=True``, returns ``self``.
"""
xp = self.device.xp
device = self.device
headers = self._headers
new_orientation = tuple(new_orientation)
if new_orientation == self.orientation:
if inplace:
return self
return self._partial_clone(volume=self._volume)
temp_orientation = self.orientation
temp_affine = np.array(self._affine)
transpose_inds = stdo.get_transpose_inds(temp_orientation, new_orientation)
all_transpose_inds = transpose_inds + tuple(range(3, self._volume.ndim))
with device:
volume = xp.transpose(self.volume, all_transpose_inds)
if headers is not None:
headers = np.transpose(headers, all_transpose_inds)
for i in range(len(transpose_inds)):
temp_affine[..., i] = self._affine[..., transpose_inds[i]]
temp_orientation = tuple([self.orientation[i] for i in transpose_inds])
flip_axs_inds = list(stdo.get_flip_inds(temp_orientation, new_orientation))
with device:
volume = xp.flip(volume, axis=tuple(flip_axs_inds))
if headers is not None:
headers = np.flip(headers, axis=tuple(flip_axs_inds))
a_vecs = temp_affine[:3, :3]
a_origin = temp_affine[:3, 3]
# phi is a vector of 1s and -1s, where 1 indicates no flip, and -1 indicates flip
# phi is used to determine which columns in affine matrix to flip
phi = np.ones([1, len(a_origin)]).flatten()
phi[flip_axs_inds] *= -1
b_vecs = np.array(a_vecs)
for i in range(len(phi)):
b_vecs[:, i] *= phi[i]
# get number of pixels to shift by on each axis.
# Should be 0 when not flipping - i.e. phi<0 mask
vol_shape_vec = (
(np.asarray(volume.shape[:3]) - 1) * (phi < 0).astype(np.float32)
).transpose()
b_origin = np.round(
a_origin.flatten() - np.matmul(b_vecs, vol_shape_vec).flatten(),
SCANNER_ORIGIN_DECIMAL_PRECISION,
)
temp_affine = np.array(self.affine)
temp_affine[:3, :3] = b_vecs
temp_affine[:3, 3] = b_origin
temp_affine[temp_affine == 0] = 0 # get rid of negative 0s
if inplace:
self._affine = temp_affine
self._volume = volume
self._headers = headers
mv = self
else:
mv = self._partial_clone(volume=volume, affine=temp_affine, headers=headers)
assert (
mv.orientation == new_orientation
), f"Orientation mismatch: Expected: {self.orientation}. Got {new_orientation}"
return mv
def reformat_as(self, other, inplace: bool = False) -> "MedicalVolume":
"""Reformat this to the same orientation as ``other``.
Equivalent to ``self.reformat(other.orientation, inplace)``.
Args:
other (MedicalVolume): The result volume has the same orientation as ``other``.
inplace (bool, optional): If `True`, do operation in-place and return ``self``.
Returns:
MedicalVolume: The reformatted volume. If ``inplace=True``, returns ``self``.
"""
return self.reformat(other.orientation, inplace=inplace)
def is_identical(self, mv):
"""Check if another medical volume is identical.
Two volumes are identical if they have the same pixel_spacing, orientation,
scanner_origin, and volume.
Args:
mv (MedicalVolume): Volume to compare with.
Returns:
bool: `True` if identical, `False` otherwise.
"""
if not isinstance(mv, MedicalVolume):
raise TypeError("`mv` must be a MedicalVolume.")
idevice = self.device
odevice = mv.device
if idevice != odevice:
raise RuntimeError(f"Expected device {idevice}, got {odevice}.")
with idevice:
return self.is_same_dimensions(mv) and (mv.volume == self.volume).all()
def _allclose_spacing(self, mv, precision: int = None, ignore_origin: bool = False):
"""Check if spacing between self and another medical volume is within tolerance.
Tolerance is `10 ** (-precision)`.
Args:
mv (MedicalVolume): Volume to compare with.
precision (`int`, optional): Number of significant figures after the decimal.
If not specified, check that affine matrices between two volumes are identical.
Defaults to `None`.
ignore_origin (bool, optional): If ``True``, ignore matching origin in the affine
matrix.
Returns:
bool: `True` if spacing between two volumes within tolerance, `False` otherwise.
"""
if precision is not None:
tol = 10 ** (-precision)
return np.allclose(mv.affine[:3, :3], self.affine[:3, :3], atol=tol) and (
ignore_origin or np.allclose(mv.scanner_origin, self.scanner_origin, rtol=tol)
)
else:
return (mv.affine == self.affine).all() or (
ignore_origin and (mv.affine[:, :3] == self.affine[:, :3]).all()
)
def is_same_dimensions(self, mv, precision: int = None, err: bool = False):
"""Check if two volumes have the same dimensions.
Two volumes have the same dimensions if they have the same pixel_spacing,
orientation, and scanner_origin.
Args:
mv (MedicalVolume): Volume to compare with.
precision (`int`, optional): Number of significant figures after the decimal.
If not specified, check that affine matrices between two volumes are identical.
Defaults to `None`.
err (bool, optional): If `True` and volumes do not have same dimensions,
raise descriptive ValueError.
Returns:
bool: ``True`` if pixel spacing, orientation, and scanner origin
between two volumes within tolerance, ``False`` otherwise.
Raises:
TypeError: If ``mv`` is not a MedicalVolume.
ValueError: If ``err=True`` and two volumes do not have same dimensions.
"""
if not isinstance(mv, MedicalVolume):
raise TypeError("`mv` must be a MedicalVolume.")
is_close_spacing = self._allclose_spacing(mv, precision)
is_same_orientation = mv.orientation == self.orientation
is_same_shape = mv.volume.shape == self.volume.shape
out = is_close_spacing and is_same_orientation and is_same_shape
if err and not out:
tol_str = f" (tol: 1e-{precision})" if precision else ""
if not is_close_spacing:
raise ValueError(
"Affine matrices not equal{}:\n{}\n{}".format(tol_str, self._affine, mv._affine)
)
if not is_same_orientation:
raise ValueError(
"Orientations not equal: {}, {}".format(self.orientation, mv.orientation)
)
if not is_same_shape:
raise ValueError(
"Shapes not equal: {}, {}".format(self._volume.shape, mv._volume.shape)
)
assert False # should not reach here
return out
def match_orientation(self, mv):
"""Reorient another MedicalVolume to orientation specified by self.orientation.
Args:
mv (MedicalVolume): Volume to reorient.
"""
warnings.warn(
"`match_orientation` is deprecated and will be removed in v0.1. "
"Use `mv.reformat_as(self, inplace=True)` instead.",
DeprecationWarning,
)
if not isinstance(mv, MedicalVolume):
raise TypeError("`mv` must be a MedicalVolume.")
mv.reformat(self.orientation, inplace=True)
def match_orientation_batch(self, mvs): # pragma: no cover
"""Reorient a collection of MedicalVolumes to orientation specified by self.orientation.
Args:
mvs (list[MedicalVolume]): Collection of MedicalVolumes.
"""
warnings.warn(
"`match_orientation_batch` is deprecated and will be removed in v0.1. "
"Use `[x.reformat_as(self, inplace=True) for x in mvs]` instead.",
DeprecationWarning,
)
for mv in mvs:
self.match_orientation(mv)
def clone(self, headers=True):
"""Clones the medical volume.
Args:
headers (bool, optional): If `True`, clone headers.
If `False`, headers have shared memory.
Returns:
mv (MedicalVolume): A cloned MedicalVolume.
"""
return MedicalVolume(
self.volume.copy(),
self.affine.copy(),
headers=deepcopy(self._headers) if headers else self._headers,
)
def to(self, device):
"""Move to device.
If on same device, no-op and returns ``self``.
Args:
device: The device to move to.
Returns:
MedicalVolume
"""
device = Device(device)
if self.device == device:
return self
return self._partial_clone(volume=to_device(self._volume, device))
def cpu(self):
"""Move to cpu."""
return self.to("cpu")
def astype(self, dtype, **kwargs):
"""Modifies dtype of ``self._volume``.
Note this operation is done in place. ``self._volume`` is modified, based
on the ``astype`` implementation of the type associated with ``self._volume``.
No new MedicalVolume is created - ``self`` is returned.
Args:
dtype (str or dtype): Typecode or data-type to which the array is cast.
Returns:
self
"""
if (
env.package_available("h5py")
and isinstance(self._volume, h5py.Dataset)
and version.parse(env.get_version(h5py)) < version.parse("3.0.0")
):
raise ValueError("Cannot cast h5py.Dataset to dtype for h5py<3.0.0")
self._volume = self._volume.astype(dtype, **kwargs)
return self
def to_nib(self):
"""Converts to nibabel Nifti1Image.
Returns:
nibabel.Nifti1Image: The nibabel image.
Raises:
RuntimeError: If medical volume is not on the cpu.
Examples:
>>> mv = MedicalVolume(np.ones((10,20,30)), np.eye(4))
>>> mv.to_nib()
<nibabel.nifti1.Nifti1Image>
"""
device = self.device
if device != cpu_device:
raise RuntimeError(f"MedicalVolume must be on cpu, got {self.device}")
return nib.Nifti1Image(self.A, self.affine.copy())
def to_sitk(self, vdim: int = None, transpose_inplane: bool = False):
"""Converts to SimpleITK Image.
SimpleITK Image objects support vector pixel types, which are represented
as an extra dimension in numpy arrays. The vector dimension can be specified
with ``vdim``.
MedicalVolume must be on cpu. Use ``self.cpu()`` to move.
SimpleITK loads DICOM files as individual slices that get stacked in ``(z, x, y)``
order. Thus, ``sitk.GetArrayFromImage`` returns an array in ``(y, x, z)`` order.
To return a SimpleITK Image that will follow this convention, set
``transpose_inplace=True``. If you have been using SimpleITK to load DICOM files,
you will likely want to specify this parameter.
Args:
vdim (int, optional): The vector dimension.
transpose_inplane (bool, optional): If ``True``, transpose inplane axes.
Recommended to be ``True`` for users who are familiar with SimpleITK's
DICOM loading convention.
Returns:
SimpleITK.Image
Raises:
ImportError: If `SimpleITK` is not installed.
RuntimeError: If MedicalVolume is not on cpu.
Note:
Header information is not currently copied.
"""
if not env.sitk_available():
raise ImportError("SimpleITK is not installed. Install it with `pip install simpleitk`")
device = self.device
if device != cpu_device:
raise RuntimeError(f"MedicalVolume must be on cpu, got {self.device}")
arr = self.volume
ndim = arr.ndim
if vdim is not None:
if vdim < 0:
vdim = ndim + vdim
axes = tuple(i for i in range(ndim) if i != vdim)[::-1] + (vdim,)
else:
axes = range(ndim)[::-1]
arr = np.transpose(arr, axes)
affine = self.affine.copy()
affine[:2] = -affine[:2] # RAS+ -> LPS+
origin = tuple(affine[:3, 3])
spacing = self.pixel_spacing
direction = affine[:3, :3] / np.asarray(spacing)
img = sitk.GetImageFromArray(arr, isVector=vdim is not None)
img.SetOrigin(origin)
img.SetSpacing(spacing)
img.SetDirection(tuple(direction.flatten()))
if transpose_inplane:
pa = sitk.PermuteAxesImageFilter()
pa.SetOrder([1, 0, 2])
img = pa.Execute(img)
return img
def to_torch(
self, requires_grad: bool = False, contiguous: bool = False, view_as_real: bool = False
):
"""Zero-copy conversion to torch tensor.
If torch version supports complex tensors (i.e. torch>=1.5.0), complex MedicalVolume
arrays will be converted into complex tensors (torch.complex64/torch.complex128).
Otherwise, tensors will be returned as the real view, where the last dimension has
two channels (`tensor.shape[-1]==2`). `[..., 0]` and `[..., 1]` correspond to the
real/imaginary channels, respectively.
Args:
requires_grad (bool, optional): Set ``.requires_grad`` for output tensor.
contiguous (bool, optional): Make output tensor contiguous before returning.
view_as_real (bool, optional): If ``True`` and underlying array is complex,
returns a real view of a complex tensor.
Returns:
torch.Tensor: The torch tensor.
Raises:
ImportError: If ``torch`` is not installed.
Note:
This method does not convert affine matrices and headers to tensor types.
Examples:
>>> mv = MedicalVolume(np.ones((2,2,2)), np.eye(4)) # zero-copy on CPU
>>> mv.to_torch()
tensor([[[1., 1.],
[1., 1.]],
[[1., 1.],
[1., 1.]]], dtype=torch.float64)
>>> mv_gpu = MedicalVolume(cp.ones((2,2,2)), np.eye(4)) # zero-copy on GPU
>>> mv.to_torch()
tensor([[[1., 1.],
[1., 1.]],
[[1., 1.],
[1., 1.]]], device="cuda:0", dtype=torch.float64)
>>> # view complex array as real tensor
>>> mv = MedicalVolume(np.ones((3,4,5), dtype=np.complex), np.eye(4))
>>> tensor = mv.to_torch(view_as_real)
>>> tensor.shape
(3, 4, 5, 2)
"""
if not env.package_available("torch"):
raise ImportError( # pragma: no cover
"torch is not installed. Install it with `pip install torch`. "
"See https://pytorch.org/ for more information."
)
import torch
from torch.utils.dlpack import from_dlpack
device = self.device
array = self.A
if any(np.issubdtype(array.dtype, dtype) for dtype in (np.complex64, np.complex128)):
torch_version = env.get_version(torch)
supports_cplx = version.Version(torch_version) >= _TORCH_COMPLEX_SUPPORT_VERSION
if not supports_cplx or view_as_real:
with device:
shape = array.shape
array = array.view(dtype=array.real.dtype)
array = array.reshape(shape + (2,))
if device == cpu_device:
tensor = torch.from_numpy(array)
else:
tensor = from_dlpack(array.toDlpack())
tensor.requires_grad = requires_grad
if contiguous:
tensor = tensor.contiguous()
return tensor
def headers(self, flatten=False):
"""Returns headers.
If headers exist, they are currently stored as an array of
pydicom dataset headers, though this is subject to change.
Args:
flatten (bool, optional): If ``True``, flattens header array
before returning.
Returns:
Optional[ndarray[pydicom.dataset.FileDataset]]: Array of headers (if they exist).
"""
if flatten and self._headers is not None:
return self._headers.flatten()
return self._headers
def get_metadata(self, key, dtype=None, default=np._NoValue):
"""Get metadata value from first header.
The first header is defined as the first header in ``np.flatten(self._headers)``.
To extract header information for other headers, use ``self.headers()``.
Args:
key (``str`` or pydicom.BaseTag``): Metadata field to access.
dtype (type, optional): If specified, data type to cast value to.
By default for DICOM headers, data will be in the value
representation format specified by pydicom. See
``pydicom.valuerep``.
default (Any): Default value to return if `key`` not found in header.
If not specified and ``key`` not found in header, raises a KeyError.
Examples:
>>> mv.get_metadata("EchoTime")
'10.0' # this is a number type ``pydicom.valuerep.DSDecimal``
>>> mv.get_metadata("EchoTime", dtype=float)
10.0
>>> mv.get_metadata("foobar", default=0)
0
Raises:
RuntimeError: If ``self._headers`` is ``None``.
KeyError: If ``key`` not found and ``default`` not specified.
Note:
Currently header information is tied to the ``pydicom.FileDataset`` implementation.
This function is synonymous to ``dataset.<key>`` in ``pydicom.FileDataset``.
"""
if self._headers is None:
raise RuntimeError("No headers found. MedicalVolume must be initialized with `headers`")
headers = self.headers(flatten=True)
if key not in headers[0] and default != np._NoValue:
return default
else:
element = headers[0][key]
val = element.value
if dtype is not None:
val = dtype(val)
return val
def set_metadata(self, key, value, force: bool = False):
"""Sets metadata for all headers.
Args:
key (str or pydicom.BaseTag): Metadata field to access.
value (Any): The value.
force (bool, optional): If ``True``, force the header to
set key even if key does not exist in header.
Raises:
RuntimeError: If ``self._headers`` is ``None``.
"""
if self._headers is None:
if not force:
raise ValueError(
"No headers found. To generate headers and write keys, `force` must be True."
)
self._headers = self._validate_and_format_headers([pydicom.Dataset()])
warnings.warn(
"Headers were generated and may not contain all attributes "
"required to save the volume in DICOM format."
)
VR_registry = {float: "DS", int: "IS", str: "LS"}
for h in self.headers(flatten=True):
if force and key not in h:
try:
setattr(h, key, value)
except TypeError:
h.add_new(key, VR_registry[type(value)], value)
else:
h[key].value = value
def materialize(self):
if not self.is_mmap:
return self
def round(self, decimals=0, affine=False) -> "MedicalVolume":
"""Round array (and optionally affine matrix).
Args:
decimals (int, optional): Number of decimals to round to.
affine (bool, optional): The rounded medical volume.
Returns:
MedicalVolume: MedicalVolume with rounded.
"""
from dosma.core.numpy_routines import around
return around(self, decimals, affine)
def sum(
self,
axis=None,
dtype=None,
out=None,
keepdims=False,
initial=np._NoValue,
where=np._NoValue,
) -> "MedicalVolume":
"""Compute the arithmetic sum along the specified axis. Identical to :meth:`sum_np`.
See :meth:`sum_np` for more information.
Args:
axis: Same as :meth:`sum_np`.
dtype: Same as :meth:`sum_np`.
out: Same as :meth:`sum_np`.
keepdims: Same as :meth:`sum_np`.
initial: Same as :meth:`sum_np`.
where: Same as :meth:`sum_np`.
Returns:
Union[Number, MedicalVolume]: If ``axis=None``, returns a number or a scalar type of
the underlying ndarray. Otherwise, returns a medical volume containing sum
values.
"""
from dosma.core.numpy_routines import sum_np
# `out` is required for cupy arrays because of how cupy calls array.
if out is not None:
raise ValueError("`out` must be None")
return sum_np(self, axis=axis, dtype=dtype, keepdims=keepdims, initial=initial, where=where)
def mean(
self, axis=None, dtype=None, out=None, keepdims=False, where=np._NoValue
) -> Union[Number, "MedicalVolume"]:
"""Compute the arithmetic mean along the specified axis. Identical to :meth:`mean_np`.
See :meth:`mean_np` for more information.
Args:
axis: Same as :meth:`mean_np`.
dtype: Same as :meth:`mean_np`.
out: Same as :meth:`mean_np`.
keepdims: Same as :meth:`mean_np`.
initial: Same as :meth:`mean_np`.
where: Same as :meth:`mean_np`.
Returns:
Union[Number, MedicalVolume]: If ``axis=None``, returns a number or a scalar type of
the underlying ndarray. Otherwise, returns a medical volume containing mean
values.
"""
from dosma.core.numpy_routines import mean_np
# `out` is required for cupy arrays because of how cupy calls array.
if out is not None:
raise ValueError("`out` must be None")
return mean_np(self, axis=axis, dtype=dtype, keepdims=keepdims, where=where)
@property
def A(self):
"""The pixel array. Same as ``self.volume``.
Examples:
>>> mv = MedicalVolume([[[1,2],[3,4]]], np.eye(4))
>>> mv.A
array([[[1, 2],
[3, 4]]])
"""
return self.volume
@property
def volume(self):
"""ndarray: ndarray representing volume values."""
return self._volume
@volume.setter
def volume(self, value):
"""
If the volume is of a different shape, the headers are no longer valid,
so delete all reorientations are done as part of MedicalVolume,
so reorientations are permitted.
However, external setting of the volume to a different shape array is not allowed.
"""
if value.ndim != self._volume.ndim:
raise ValueError("New volume must be same as current volume")
if self._volume.shape != value.shape:
self._headers = None
self._volume = value
self._device = get_device(self._volume)
@property
def pixel_spacing(self):
"""tuple[float]: Pixel spacing in order of current orientation."""
vecs = self._affine[:3, :3]
ps = tuple(np.sqrt(np.sum(vecs ** 2, axis=0)))
assert len(ps) == 3, "Pixel spacing must have length of 3"
return ps
@property
def orientation(self):
"""tuple[str]: Image orientation in standard orientation format.
See orientation.py for more information on conventions.
"""
nib_orientation = nib.aff2axcodes(self._affine)
return stdo.orientation_nib_to_standard(nib_orientation)
@property
def scanner_origin(self):
"""tuple[float]: Scanner origin in global RAS+ x,y,z coordinates."""
return tuple(self._affine[:3, 3])
@property
def affine(self):
"""np.ndarray: 4x4 affine matrix for volume in current orientation."""
return self._affine
@property
def shape(self) -> Tuple[int, ...]:
"""The shape of the underlying ndarray."""
return self._volume.shape
@property
def ndim(self) -> int:
"""int: The number of dimensions of the underlying ndarray."""
return self._volume.ndim
@property
def device(self) -> Device:
"""The device the object is on."""
return get_device(self._volume)
@property
def dtype(self):
"""The ``dtype`` of the ndarray. Same as ``self.volume.dtype``."""
return self._volume.dtype
@property
def is_mmap(self) -> bool:
"""bool: Whether the volume is a memory-mapped array."""
# important to check if .base is a python mmap object, since a view of a mmap
# is also a memmap object, but should not be symlinked or copied
return isinstance(self.A, np.memmap) and isinstance(self.A.base, mmap)
@classmethod
def from_nib(
cls, image, affine_precision: int = None, origin_precision: int = None, mmap: bool = False
) -> "MedicalVolume":
"""Constructs MedicalVolume from nibabel images.
Args:
image (nibabel.Nifti1Image): The nibabel image to convert.
affine_precision (int, optional): If specified, rounds the i/j/k coordinate
vectors in the affine matrix to this decimal precision.
origin_precision (int, optional): If specified, rounds the scanner origin
in the affine matrix to this decimal precision.
mmap (bool, optional): If True, memory map the image.
Returns:
MedicalVolume: The medical image.
Examples:
>>> import nibabel as nib
>>> nib_img = nib.Nifti1Image(np.ones((10,20,30)), np.eye(4))
>>> MedicalVolume.from_nib(nib_img)
MedicalVolume(
shape=(10, 20, 30),
ornt=('LR', 'PA', 'IS')),
spacing=(1.0, 1.0, 1.0),
origin=(0.0, 0.0, 0.0),
device=Device(type='cpu')
)
"""
affine = np.array(image.affine) # Make a copy of the affine matrix.
if affine_precision is not None:
affine[:3, :3] = np.round(affine[:3, :3], affine_precision)
if origin_precision:
affine[:3, 3] = np.round(affine[:3, 3], origin_precision)
data = image.dataobj.__array__() if mmap else image.get_fdata()
mv = cls(data, affine)
if mmap and not mv.is_mmap:
raise ValueError(
"Underlying array in the nibabel image is not mem-mapped. " "Please set mmap=False."
)
return mv
@classmethod
def from_sitk(cls, image, copy=False, transpose_inplane: bool = False) -> "MedicalVolume":
"""Constructs MedicalVolume from SimpleITK.Image.
Use ``transpose_inplane=True`` if the SimpleITK image was loaded with SimpleITK's
DICOM reader or if ``transpose_inplace=True`` was used to create the Image
with :meth:`to_sitk`. See the discussion of SimpleITK's data ordering convention
in :meth:`to_sitk` for more information.
If you are getting a segmentation fault, try using ``copy=True``.
Args:
image (SimpleITK.Image): The image.
copy (bool, optional): If ``True``, copies array.
transpose_inplane (bool, optional): If ``True``, transposes the inplane axes.
Set this to ``True`` if the SimpleITK image was loaded with SimpleITK's
DICOM reader. May need to set ``copy=True`` to avoid segmentation fault.
Returns:
MedicalVolume
Note:
Metadata information is not copied.
"""
if not env.sitk_available():
raise ImportError("SimpleITK is not installed. Install it with `pip install simpleitk`")
if len(image.GetSize()) < 3:
raise ValueError("`image` must be 3D.")
is_vector_image = image.GetNumberOfComponentsPerPixel() > 1
if transpose_inplane:
pa = sitk.PermuteAxesImageFilter()
pa.SetOrder([1, 0, 2])
image = pa.Execute(image)
if copy:
arr = sitk.GetArrayFromImage(image)
else:
arr = sitk.GetArrayViewFromImage(image)
ndim = arr.ndim
if is_vector_image:
axes = tuple(range(ndim)[-2::-1]) + (ndim - 1,)
else:
axes = range(ndim)[::-1]
arr = np.transpose(arr, axes)
origin = image.GetOrigin()
spacing = image.GetSpacing()
direction = np.asarray(image.GetDirection()).reshape(-1, 3)
affine = np.zeros((4, 4))
affine[:3, :3] = direction * np.asarray(spacing)
affine[:3, 3] = origin
affine[:2] = -affine[:2] # LPS+ -> RAS+
affine[3, 3] = 1
return cls(arr, affine)
@classmethod
def from_torch(cls, tensor, affine, headers=None, to_complex: bool = None) -> "MedicalVolume":
"""Zero-copy construction from PyTorch tensor.
Args:
tensor (torch.Tensor): A PyTorch tensor where first three dimensions correspond
to spatial dimensions.
affine (np.ndarray): See class parameters.
headers (np.ndarray[pydicom.FileDataset], optional): See class parameters.
to_complex (bool, optional): If ``True``, interprets tensor as real view of complex
tensor and attempts to restructure it as a complex array.
Returns:
MedicalVolume: A medical image.
Raises:
RuntimeError: If ``affine`` is not on the cpu.
ValueError: If ``tensor`` does not have at least three spatial dimensions.
ValueError: If ``to_complex=True`` and shape is not size ``(..., 2)``.
ImportError: If ``tensor`` on GPU and ``cupy`` not installed.
Examples:
>>> import torch
>>> tensor = torch.ones((2,2,2))
>>> MedicalVolume.from_torch(tensor, affine=np.eye(4))
MedicalVolume(
shape=(2, 2, 2),
ornt=('LR', 'PA', 'IS')),
spacing=(1.0, 1.0, 1.0),
origin=(0.0, 0.0, 0.0),
device=Device(type='cpu')
)
>>> tensor = torch.ones((2,2,2), device="cuda") # zero-copy from GPU 0
>>> MedicalVolume.from_torch(tensor, affine=np.eye(4))
MedicalVolume(
shape=(2, 2, 2),
ornt=('LR', 'PA', 'IS')),
spacing=(1.0, 1.0, 1.0),
origin=(0.0, 0.0, 0.0),
device=Device(type='cuda', index=0)
)
>>> tensor = torch.ones((3,4,5,2)) # treat this tensor as view of complex tensor
>>> mv = MedicalVolume.from_torch(tensor, affine=np.eye(4), to_complex=True)
>>> print(mv)
MedicalVolume(
shape=(3,4,5),
ornt=('LR', 'PA', 'IS')),
spacing=(1.0, 1.0, 1.0),
origin=(0.0, 0.0, 0.0),
device=Device(type='cuda', index=0)
)
>>> mv.dtype
np.complex128
"""
if not env.package_available("torch"):
raise ImportError( # pragma: no cover
"torch is not installed. Install it with `pip install torch`. "
"See https://pytorch.org/ for more information."
)
import torch
from torch.utils.dlpack import to_dlpack
torch_version = env.get_version(torch)
supports_cplx = version.Version(torch_version) >= _TORCH_COMPLEX_SUPPORT_VERSION
# Check if tensor needs to be converted to np.complex type.
# If tensor is of torch.complex64 or torch.complex128 dtype, then from_numpy will take
# care of conversion to appropriate numpy dtype, and we do not need to do the to_complex
# logic.
to_complex = to_complex and (
not supports_cplx
or (supports_cplx and tensor.dtype not in (torch.complex64, torch.complex128))
)
if isinstance(affine, torch.Tensor):
if Device(affine.device) != cpu_device:
raise RuntimeError("Affine matrix must be on the cpu")
affine = affine.numpy()
if (not to_complex and tensor.ndim < 3) or (to_complex and tensor.ndim < 4):
raise ValueError(
f"Tensor must have three spatial dimensions. Got shape {tensor.shape}."
)
if to_complex and tensor.shape[-1] != 2:
raise ValueError(
f"tensor.shape[-1] must have shape 2 when to_complex is specified. "
f"Got shape {tensor.shape}."
)
device = Device(tensor.device)
if device == cpu_device:
array = tensor.detach().numpy()
else:
if env.cupy_available():
array = cp.fromDlpack(to_dlpack(tensor))
else:
raise ImportError( # pragma: no cover
"CuPy is required to convert a GPU torch.Tensor to array. "
"Follow instructions at https://docs.cupy.dev/en/stable/install.html to "
"install the correct binary."
)
if to_complex:
with get_device(array):
if array.dtype == np.float32:
array = array.view(np.complex64)
elif array.dtype == np.float64:
array = array.view(np.complex128)
array = array.reshape(array.shape[:-1])
return cls(array, affine, headers=headers)
def _partial_clone(self, **kwargs) -> "MedicalVolume":
"""Copies constructor information from ``self`` if not available in ``kwargs``."""
if kwargs.get("volume", None) is False:
# special use case to not clone volume
kwargs["volume"] = self._volume
for k in ("volume", "affine"):
if k not in kwargs or (kwargs[k] is True):
kwargs[k] = getattr(self, f"_{k}").copy()
if "headers" not in kwargs:
kwargs["headers"] = self._headers
elif isinstance(kwargs["headers"], bool) and kwargs["headers"]:
kwargs["headers"] = deepcopy(self._headers)
return self.__class__(**kwargs)
def _validate_and_format_headers(self, headers):
"""Validate headers are of appropriate shape and format into standardized shape.
Headers are stored an ndarray of dictionary-like objects with explicit dimensions
that match the dimensions of ``self._volume``. If header objects are not
Assumes ``self._volume`` and ``self._affine`` have been set.
"""
headers = np.asarray(headers)
if headers.ndim > self._volume.ndim:
raise ValueError(
f"`headers` has too many dimensions. "
f"Got headers.ndim={headers.ndim}, but volume.ndim={self._volume.ndim}"
)
for dim in range(-headers.ndim, 0)[::-1]:
if headers.shape[dim] not in (1, self._volume.shape[dim]):
raise ValueError(
f"`headers` must follow standard broadcasting shape. "
f"Got headers.shape={headers.shape}, but volume.shape={self._volume.shape}"
)
ndim = self._volume.ndim
shape = (1,) * (ndim - len(headers.shape)) + headers.shape
headers = np.reshape(headers, shape)
return headers
def _extract_input_array_ufunc(self, input, device=None):
if device is None:
device = self.device
device_err = "Expected device {} but got device ".format(device) + "{}"
if isinstance(input, Number):
return input
elif isinstance(input, np.ndarray):
if device != cpu_device:
raise RuntimeError(device_err.format(cpu_device))
return input
elif env.cupy_available() and isinstance(input, cp.ndarray):
if device != input.device:
raise RuntimeError(device_err.format(Device(input.device)))
return input
elif isinstance(input, MedicalVolume):
if device != input.device:
raise RuntimeError(device_err.format(Device(input.device)))
assert self.is_same_dimensions(input, err=True)
return input._volume
else:
return NotImplemented
def _check_reduce_axis(self, axis: Union[int, Sequence[int]]) -> Tuple[int]:
if axis is None:
return None
is_sequence = isinstance(axis, Sequence)
if not is_sequence:
axis = (axis,)
axis = tuple(x if x >= 0 else self.volume.ndim + x for x in axis)
assert all(x >= 0 for x in axis)
if any(x < 3 for x in axis):
raise ValueError("Cannot reduce MedicalVolume along spatial dimensions")
if not is_sequence:
axis = axis[0]
return axis
def _reduce_array(self, func, *inputs, **kwargs) -> "MedicalVolume":
"""
Assumes inputs have been verified.
"""
device = self.device
xp = device.xp
keepdims = kwargs.get("keepdims", False)
reduce_axis = self._check_reduce_axis(kwargs["axis"])
kwargs["axis"] = reduce_axis
if not isinstance(reduce_axis, Sequence):
reduce_axis = (reduce_axis,)
with device:
volume = func(*inputs, **kwargs)
if xp.isscalar(volume) or volume.ndim == 0:
return volume
if self._headers is not None:
headers_slices = tuple(
slice(None) if x not in reduce_axis else slice(0, 1) if keepdims else 0
for x in range(self._headers.ndim)
)
headers = self._headers[headers_slices]
else:
headers = None
return self._partial_clone(volume=volume, headers=headers)
def __getitem__(self, _slice):
if isinstance(_slice, MedicalVolume):
_slice = _slice.reformat_as(self).A
slicer = _SpatialFirstSlicer(self)
try:
_slice = slicer.check_slicing(_slice)
except ValueError as err:
raise IndexError(*err.args)
volume = self._volume[_slice]
if any(dim == 0 for dim in volume.shape):
raise IndexError("Empty slice requested")
headers = self._headers
if headers is not None:
_slice_headers = []
for idx, x in enumerate(_slice):
if headers.shape[idx] == 1 and not isinstance(x, int):
_slice_headers.append(slice(None))
elif headers.shape[idx] == 1 and isinstance(x, int):
_slice_headers.append(0)
else:
_slice_headers.append(x)
headers = headers[_slice_headers]
affine = slicer.slice_affine(_slice)
return self._partial_clone(volume=volume, affine=affine, headers=headers)
def __setitem__(self, _slice, value):
"""
Note:
When ``value`` is a ``MedicalVolume``, the headers from that value
are not copied over. This may be changed in the future.
"""
if isinstance(value, MedicalVolume):
image = self[_slice]
assert value.is_same_dimensions(image, err=True)
value = value._volume
with self.device:
self._volume[_slice] = value
if self.is_mmap and self._volume.mode == "c":
self._volume = np.asarray(self._volume)
def __repr__(self) -> str:
nl = "\n"
nltb = "\n "
return (
f"{self.__class__.__name__}({nltb}shape={self.shape},{nltb}"
f"ornt={self.orientation}),{nltb}spacing={self.pixel_spacing},{nltb}"
f"origin={self.scanner_origin},{nltb}device={self.device}{nl})"
)
def _iops(self, other, op):
"""Helper function for i-type ops (__iadd__, __isub__, etc.)"""
if isinstance(other, MedicalVolume):
assert self.is_same_dimensions(other, err=True)
other = other.volume
if isinstance(op, str):
op = getattr(self._volume, op)
op(other)
if self.is_mmap and self._volume.mode == "c":
self._volume = np.asarray(self._volume)
return self
def __iadd__(self, other):
return self._iops(other, self._volume.__iadd__)
def __ifloordiv__(self, other):
return self._iops(other, self._volume.__ifloordiv__)
def __imul__(self, other):
return self._iops(other, self._volume.__imul__)
def __ipow__(self, other):
return self._iops(other, self._volume.__ipow__)
def __isub__(self, other):
return self._iops(other, self._volume.__isub__)
def __itruediv__(self, other):
return self._iops(other, self._volume.__itruediv__)
def __array__(self):
"""Wrapper for performing numpy operations on MedicalVolume array.
Examples:
>>> a = np.asarray(mv)
>>> type(a)
<class 'numpy.ndarray'>
Note:
This is not valid when ``self.volume`` is a ``cupy.ndarray``.
All CUDA ndarrays must first be moved to the cpu.
"""
try:
return np.asarray(self.volume)
except TypeError:
raise TypeError(
"Implicit conversion to a NumPy array is not allowed. "
"Please use `.cpu()` to move the array to the cpu explicitly "
"before constructing a NumPy array."
)
def __array_ufunc__(self, ufunc, method, *inputs, **kwargs):
def _extract_inputs(inputs, device):
_inputs = []
for input in inputs:
input = self._extract_input_array_ufunc(input, device)
if input is NotImplemented:
return input
_inputs.append(input)
return _inputs
if method not in ["__call__", "reduce"]:
return NotImplemented
device = self.device
_inputs = _extract_inputs(inputs, device)
if _inputs is NotImplemented:
return NotImplemented
if method == "__call__":
with device:
volume = ufunc(*_inputs, **kwargs)
if volume.shape != self._volume.shape:
raise ValueError(
f"{self.__class__.__name__} does not support operations that change shape. "
f"Use operations on `self.volume` to modify array objects."
)
return self._partial_clone(volume=volume)
elif method == "reduce":
return self._reduce_array(ufunc.reduce, *_inputs, **kwargs)
def __array_function__(self, func, types, args, kwargs):
from dosma.core.numpy_routines import _HANDLED_NUMPY_FUNCTIONS
if func not in _HANDLED_NUMPY_FUNCTIONS:
return NotImplemented
# Note: this allows subclasses that don't override
# __array_function__ to handle MedicalVolume objects.
if not all(issubclass(t, (MedicalVolume, self.__class__)) for t in types):
return NotImplemented
return _HANDLED_NUMPY_FUNCTIONS[func](*args, **kwargs)
@property
def __cuda_array_interface__(self):
"""Wrapper for performing cupy operations on MedicalVolume array."""
if self.device == cpu_device:
raise TypeError(
"Implicit conversion to a CuPy array is not allowed. "
"Please use `.to(device)` to move the array to the gpu explicitly "
"before constructing a CuPy array."
)
return self.volume.__cuda_array_interface__
class _SpatialFirstSlicer(_SpatialFirstSlicerNib):
def __init__(self, img):
self.img = img
def __getitem__(self, slicer):
raise NotImplementedError("Slicing should be done by `MedicalVolume`")