deepmr.io.read_image#
- deepmr.io.read_image(filepath, acqheader=None, device='cpu', verbose=0)[source]#
Read image data from file.
Supported formats are
DICOM
andNIfTI
.- Parameters:
filepath (str) – Path to image file. Supports wildcard (e.g.,
/path-to-dicom-exam/*
,/path-to-BIDS/*.nii
).acqheader (Header, optional) – Acquisition header loaded from trajectory. If not provided, assume Cartesian acquisition and infer from data. The default is
None
.device (str, optional) – Computational device for internal attributes. The default is
cpu
.verbose (int, optional) – Verbosity level
(0=Silent, 1=Less, 2=More)
. The default is0
.
- Returns:
image (torch.tensor) – Complex image data.
head (Header) – Metadata for image reconstruction.
Example
>>> import deepmr
Get the filenames for exemplary DICOM and NIfTI files.
>>> dcmpath = deepmr.testdata("dicom") >>> niftipath = deepmr.testdata("nifti")
Load the file contents.
>>> image_dcm, head_dcm = deepmr.io.read_image(dcmpath) >>> image_nii, head_nii = deepmr.io.read_image(niftipath)
The result is a image/header pair.
Image
contains image-space data. Here, it represents a 2D cartesian acquisition with 3 echoes, 2 slices and 192x192 matrix size.>>> image_dcm.shape torch.Size([3, 2, 192, 192]) >>> image_nii.shape torch.Size([3, 2, 192, 192])
Head
contains the acquisition information. We can inspect the image shape and resolution:>>> head_dcm.shape tensor([ 2, 192, 192]) >>> head_nii.shape tensor([ 2, 192, 192]) >>> head_dcm.ref_dicom.SpacingBetweenSlices '10.5' >>> head_nii.ref_dicom.SpacingBetweenSlices '10.5' >>> head_dcm.ref_dicom.SliceThickness '7.0' >>> head_nii.ref_dicom.SliceThickness '7.0' >>> head_dcm.ref_dicom.PixelSpacing [0.67, 0.67] >>> head_nii.ref_dicom.PixelSpacing [0.67,0.67]
Head
also contains contrast information (for forward simulation and parameter inference):>>> head_dcm.FA 180.0 >>> head_nii.FA 180.0 >>> head_dcm.TE tensor([ 20.0, 40.0, 60.0]) >>> head_nii.TE tensor([ 20.0, 40.0, 60.0]) >>> head_dcm.TR 3000.0 >>> head_nii.TR 3000.0
Notes
The returned
image
tensor contains image space data. Dimensions are defined as following:2D:
(ncontrasts, nslices, ny, nx)
.3D:
(ncontrasts, nz, ny, nx)
.
The returned
head
(deepmr.Header()
) is a structure with the following fields:- shape (torch.Tensor):
This is the expected image size of shape
(nz, ny, nx)
.
- resolution (torch.Tensor):
This is the expected image resolution in mm of shape
(dz, dy, dx)
.
- t (torch.Tensor):
This is the readout sampling time
(0, t_read)
inms
. with shape(nsamples,)
.
- traj (torch.Tensor):
This is the k-space trajectory normalized as
(-0.5, 0.5)
with shape(ncontrasts, nviews, nsamples, ndims)
.
- dcf (torch.Tensor):
This is the k-space sampling density compensation factor with shape
(ncontrasts, nviews, nsamples)
.
- FA (torch.Tensor, float):
This is either the acquisition flip angle in degrees or the list of flip angles of shape
(ncontrasts,)
for each image in the series.
- TR (torch.Tensor, float):
This is either the repetition time in ms or the list of repetition times of shape
(ncontrasts,)
for each image in the series.
- TE (torch.Tensor, float):
This is either the echo time in ms or the list of echo times of shape
(ncontrasts,)
for each image in the series.
- TI (torch.Tensor, float):
This is either the inversion time in ms or the list of inversion times of shape
(ncontrasts,)
for each image in the series.
- user (dict):
User parameters. Some examples are:
- ordering (torch.Tensor):
Indices for reordering (acquisition to reconstruction) of acquired k-space data, shaped
(3, nslices * ncontrasts * nview)
, whose rows arecontrast_index
,slice_index
andview_index
, respectively.
- mode (str):
Acquisition mode (
2Dcart
,3Dcart
,2Dnoncart
,3Dnoncart
).
- separable (bool):
Whether the acquisition can be decoupled by fft along
slice
/readout
directions (3D stack-of-noncartesian / 3D cartesian, respectively) or not (3D noncartesian and 2D acquisitions).
- slice_profile (torch.Tensor):
Flip angle scaling along slice profile of shape
(nlocs,)
.
- basis (torch.Tensor):
Low rank subspace basis for subspace reconstruction of shape
(ncoeff, ncontrasts)
.
- affine (np.ndarray):
Affine matrix describing image spacing, orientation and origin of shape
(4, 4)
.
- ref_dicom (pydicom.Dataset):
Template dicom for image export.