Reconstruction module
PyMIALSRTK reconstruction functions.
MialsrtkImageReconstruction
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.inputs.bids_dir = '/my_directory' >>> 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
bids_dir (a string or os.PathLike object referring to an existing directory) – BIDS root directory.
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
)no_reg (a boolean) – Skip slice-to-volume registration.
out_sdi_prefix (a string) – Suffix added to construct output scattered data interpolation filename. (Nipype default value:
SDI_
)out_transf_postfix (a string) – Suffix added to construct output transformation filenames. (Nipype default value:
_transform
)sub_ses (a string) – Subject and session BIDS identifier to construct output filename. (Nipype default value:
x
)- 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.
MialsrtkTVSuperResolution
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 modelH
that relates the low resolution imagesy
to the high resolutionx
to be estimated byy = Hx
, and it solves optimally using convex optimization the inverse (i.e. super-resolution) problem (findingx
) 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 byin_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.inputs.bids_dir = '/my_directory' >>> 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
bids_dir (a string or os.PathLike object referring to an existing directory) – BIDS root directory.
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:
1
)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
)- Outputs
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_out_files = ''
- MialsrtkTVSuperResolution.m_output_dict = {}