deepmr.cartesian3D

Contents

deepmr.cartesian3D#

deepmr.cartesian3D(shape, accel_type='PI', accel=(1, 1, 1), shift=0, acs_shape=None)[source]#

Design a 3D (+t) cartesian encoding scheme.

This function regular undersampling along both phase encoding directions, with Parallel Imaging (including CAIPIRINHA shift), Partial Fourier acceleration and rectangular FOV. In addition, variable density Poisson disk sampling for Compressed Sensing is supported. In the former case, sampling pattern is assumed constant for each contrast in multi-contrast acquisitions; in the latter, sampling pattern is unique for each contrast.

For multi-echo acquisitions, sampling pattern is assumed constant along the echo train for both Parallel Imaging and Poisson Disk sampling.

Parameters:
  • shape (Iterable[int]) – Matrix shape (y, z, contrast=1, echoes=1).

  • accel_type (str, optional) – Acceleration type. Can be either PI (Parallel Imaging) or CS (Compressed Sensing). In the former case, undersampling is regular and equal for each contrast. In the latter, build unique variable density Poisson-disk sampling for each contrast. The default is PI.

  • accel (Iterable[int], optional) – Acceleration factor. For accel_type = PI, it is defined as (Ry, Rz, Pf), ranging from (1, 1, 1) (fully sampled) to (ny, nz, 0.75). For accel_type = CS, ranges from 1 (fully sampled) to ny * nz. The default is (1, 1, 1).

  • shift (int, optional) – CAIPIRINHA shift between ky and kz. The default is 0 (standard Parallel Imaging).

  • acs_shape (int, optional) – Matrix size for calibration regions ACSy. The default is None.

Returns:

  • mask (torch.Tensor) – Binary mask indicating the sampled k-space locations of shape (ncontrasts, nz, ny).

  • head (Header) – Acquisition header corresponding to the generated sampling pattern.

Example

>>> import deepmr

We can create a 3D Cartesian sampling mask of (128, 128) pixels with Parallel Imaging factor (Ry, Rz) = (2, 2) by:

>>> mask, head = deepmr.cartesian3D(128, accel=(2, 2))

The undersampling along ky and kz can be shifted as in a CAIPIRINHA sampling by specifying the shift argument:

>>> mask, head = deepmr.cartesian3D(128, accel=(1, 3), shift=2)

Partial Fourier acceleration can be enabled by passing a 3-element tuple as the accel argument:

>>> mask, head = deepmr.cartesian3D(128, accel=(2, 2, 0.8))

Instead of regular undersampling, variable density Poisson disk sampling can be obtained by passing accel_type = CS:

>>> mask, head = deepmr.cartesian3D(128, accel_type="CS", accel=4) # 4 is the overall acceleration factor.

A rectangular matrix can be specified by passing a tuple as the shape argument:

>>> mask, head = deepmr.cartesian3D((128, 96), accel=(2, 2))
>>> mask.shape
torch.Size([96, 128])

Autocalibration region width can be specified via the acs_shape argument:

>>> mask, head = deepmr.cartesian2D(128, accel=2, acs_shape=32)

The generated mask will have an inner (32, 32) fully sampled (kz, ky) k-space square for coil sensitivity estimation.

Multiple contrasts with different sampling (e.g., for T1-T2 Shuffling) can be achieved by providing a 3-element tuple of ints as the shape argument:

>>> mask, head = deepmr.cartesian3D((128, 128, 96), accel_type="CS", accel=4)
>>> mask.shape
torch.Size([96, 128, 128])

corresponding to 96 different contrasts, each sampled with a different undersampled (kz, ky) pattern. Similarly, multiple echoes (with fixed sampling) can be specified using a 4-element tuple as:

>>> mask, head = deepmr.cartesian3D((128, 128, 1, 8), accel=(2, 2))
>>> mask.shape
torch.Size([128, 128])
>>> head.TE.shape
torch.Size([8])

corresponding to a 8-echoes undersampled k-spaces.

Notes

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). Matrix is assumed squared (i.e., nx = ny).

  • t (torch.Tensor):

    This is the readout sampling time (0, t_read) in ms. with shape (nx,). K-space raster time of 1 us is assumed.

  • TE (torch.Tensor):

    This is the Echo Times array. Assumes a k-space raster time of 1 us and minimal echo spacing.