Reconstruction module

PyMIALSRTK reconstruction functions.

MialsrtkImageReconstruction

Link to code

Bases: nipype.interfaces.base.core.BaseInterface

Creates a high-resolution image from a set of low resolution images.

It is built on the BTK implementation and implements the method, presented in [Rousseau2006], that iterates between slice-to-volume registration and reconstruction of a high-resolution image using scattered data interpolation. The method converges when the mean square error between the high-resolution images reconstructed in the last two iterations is lower than 1e-6.

It is used to estimate slice motion prior to MialsrtkTVSuperResolution.

References

Rousseau2006

Rousseau et al.; Acad Radiol., 2006. (link to paper)

Example

>>> from pymialsrtk.interfaces.reconstruction import MialsrtkImageReconstruction
>>> srtkImageReconstruction = MialsrtkImageReconstruction()
>>> srtkImageReconstruction.input_images = ['sub-01_ses-01_run-1_T2w.nii.gz',
>>>                                         'sub-01_ses-01_run-2_T2w.nii.gz',
>>>                                         'sub-01_ses-01_run-3_T2w.nii.gz',
>>>                                         'sub-01_ses-01_run-4_T2w.nii.gz']
>>> srtkImageReconstruction.input_masks = ['sub-01_ses-01_run-1_mask.nii.gz',
>>>                                        'sub-01_ses-01_run-2_mask.nii.gz',
>>>                                        'sub-01_ses-01_run-3_mask.nii.gz',
>>>                                        'sub-01_ses-01_run-4_mask.nii.gz']
>>> srtkImageReconstruction.inputs.stacks_order = [3,1,2,4]
>>> srtkImageReconstruction.inputs.sub_ses = 'sub-01_ses-01'
>>> srtkImageReconstruction.inputs.in_roi = 'mask'
>>> srtkImageReconstruction.run()
Mandatory Inputs

  • in_roi (‘mask’ or ‘all’ or ‘box’ or ‘mask’) –

    Define region of interest (required):

    • box: Use intersections for roi calculation

    • mask: Use masks for roi calculation

    • all: Use the whole image FOV.

    (Nipype default value: mask)

  • stacks_order (a list of items which are any value) – List of stack run-id that specify the order of the stacks.

Optional Inputs

  • input_images (a list of items which are a pathlike object or string representing a file) – Input images.

  • input_masks (a list of items which are a pathlike object or string representing a file) – Masks of the input images.

  • input_rad_dilatation (a float) – Radius dilatation used in prior step to construct output filename. (Nipype default value: 1.0)

  • out_prefix (a string) – Prefix added to construct output super-resolution filename. (Nipype default value: SRTV_)

  • out_sdi_prefix (a string) – Suffix added to construct outputscattered data interpolation filename. (Nipype default value: SDI_)

  • out_transf_postfix (a string) – Suffix added to construct output transformation filenames. (Nipype default value: _transform)

  • skip_svr (a boolean) – Skip slice-to-volume registration.

  • sub_ses (a string) – Subject and session BIDS identifier to construct output filename. (Nipype default value: x)

  • verbose (a boolean) – Enable verbosity.

Outputs

  • output_sdi (a pathlike object or string representing a file) – Output scattered data interpolation image file.

  • output_transforms (a list of items which are a pathlike object or string representing a file) – Output transformation files.

MialsrtkSDIComputation

Link to code

Bases: nipype.interfaces.base.core.BaseInterface

Creates a high-resolution image from a set of low resolution images and their slice-by-slicemotion parameters.

Mandatory Inputs

  • input_images (a list of items which are a pathlike object or string representing a file) – Input images.

  • input_masks (a list of items which are a pathlike object or string representing a file) – Masks of the input images.

  • input_reference (a pathlike object or string representing a file) – Input reference image.

  • input_transforms (a list of items which are a pathlike object or string representing a file) – Input transformation files.

  • stacks_order (a list of items which are any value) – List of stack run-id that specify the order of the stacks.

Optional Inputs

  • label_id (an integer) – (Nipype default value: -1)

  • sub_ses (a string) – Subject and session BIDS identifier to construct output filename. (Nipype default value: x)

  • verbose (a boolean) – Enable verbosity.

Outputs

output_sdi (a pathlike object or string representing a file) – Output scattered data interpolation image file.

MialsrtkSDIComputation.get_empty_ref_image(input_ref)[source]

Generate an empty reference image for _run_interface.

MialsrtkTVSuperResolution

Link to code

Bases: nipype.interfaces.base.core.BaseInterface

Apply super-resolution algorithm using one or multiple input images.

It implements the super-resolution algorithm with Total-Variation regularization presented in [Tourbier2015].

Taking as input the list of input low resolution images and the list of slice-by-slice transforms estimated with MialsrtkImageReconstruction, it builds the forward model H that relates the low resolution images y to the high resolution x to be estimated by y = Hx, and it solves optimally using convex optimization the inverse (i.e. super-resolution) problem (finding x) with exact Total-Variation regularization.

The weight of TV regularization is controlled by in_lambda. The lower it is, the lower will be the weight of the data fidelity and so the higher will the regularization. The optimization time step is controlled by in_deltat that defines the time step of the optimizer.

References

Tourbier2015

Tourbier et al.; NeuroImage, 2015. (link to paper)

Example

>>> from pymialsrtk.interfaces.reconstruction import MialsrtkTVSuperResolution
>>> srtkTVSuperResolution = MialsrtkTVSuperResolution()
>>> srtkTVSuperResolution.input_images = ['sub-01_ses-01_run-1_T2w.nii.gz', 'sub-01_ses-01_run-2_T2w.nii.gz',     'sub-01_ses-01_run-3_T2w.nii.gz', 'sub-01_ses-01_run-4_T2w.nii.gz']
>>> srtkTVSuperResolution.input_masks = ['sub-01_ses-01_run-1_mask.nii.gz', 'sub-01_ses-01_run-2_mask.nii.gz',     'sub-01_ses-01_run-3_mask.nii.gz', 'sub-01_ses-01_run-4_mask.nii.gz']
>>> srtkTVSuperResolution.input_transforms = ['sub-01_ses-01_run-1_transform.txt', 'sub-01_ses-01_run-2_transform.txt',     'sub-01_ses-01_run-3_transform.txt', 'sub-01_ses-01_run-4_transform.txt']
>>> srtkTVSuperResolution.input_sdi = 'sdi.nii.gz'
>>> srtkTVSuperResolution.inputs.stacks_order = [3,1,2,4]
>>> srtkTVSuperResolution.inputs.sub_ses = 'sub-01_ses-01'
>>> srtkTVSuperResolution.inputs.in_loop = 10
>>> srtkTVSuperResolution.inputs.in_deltat = 0.01
>>> srtkTVSuperResolution.inputs.in_lambda = 0.75
>>> srtkTVSuperResolution.run()
Mandatory Inputs

  • in_deltat (a float) – Parameter deltat of TV optimizer.

  • in_lambda (a float) – TV regularization factor which weights the data fidelity term in TV optimizer.

  • in_loop (an integer) – Number of loops (SR/denoising).

  • input_sdi (a pathlike object or string representing a file) – Reconstructed image for initialization. Typically the output of MialsrtkImageReconstruction is used.

Optional Inputs

  • deblurring (a boolean) – Flag to set deblurring PSF during SR (double the neighborhood). (Nipype default value: False)

  • in_bregman_loop (an integer) – Number of Bregman loops. (Nipype default value: 3)

  • in_gamma (an integer) – Parameter gamma. (Nipype default value: 10)

  • in_inner_thresh (a float) – Inner loop convergence threshold. (Nipype default value: 1e-05)

  • in_iter (an integer) – Number of inner iterations. (Nipype default value: 50)

  • in_outer_thresh (a float) – Outer loop convergence threshold. (Nipype default value: 1e-06)

  • in_step_scale (an integer) – Parameter step scale. (Nipype default value: 10)

  • input_images (a list of items which are a pathlike object or string representing a file) – Input image filenames for super-resolution.

  • input_masks (a list of items which are a pathlike object or string representing a file) – Masks of input images for super-resolution.

  • input_rad_dilatation (a float) – Radius dilatation used in prior step to construct output filename. (Nipype default value: 1.0)

  • input_transforms (a list of items which are a pathlike object or string representing a file) – Estimated slice-by-slice ITK transforms of input images.

  • out_prefix (a string) – Prefix added to construct output super-resolution filename. (Nipype default value: SRTV_)

  • stacks_order (a list of items which are any value) – List of stack run-id that specify the order of the stacks.

  • sub_ses (a string) – Subject and session BIDS identifier to construct output filename. (Nipype default value: x)

  • use_manual_masks (a boolean) – Use masks of input files. (Nipype default value: False)

  • verbose (a boolean) – Enable verbosity.

Outputs

  • output_TV_parameters (a dictionary with keys which are any value and with values which are any value) – Dictionary of all TV parameters used.

  • output_json_path (a pathlike object or string representing a file) – Output json file where super-resolution reconstruction parameters are summarized.

  • output_sr (a pathlike object or string representing a file) – Output super-resolution image file.

  • output_sr_png (a pathlike object or string representing a file) – Output super-resolution PNG image file for quality assessment.

MialsrtkTVSuperResolution.m_TV_parameters = {}
MialsrtkTVSuperResolution.m_out_files = ''
MialsrtkTVSuperResolution.m_output_dict = {}