reconstruct

Use the NeSVoR algorithm to reconstuct a high-quality and coherent 3D volume from multiple stacks of 2D slices. This command can be applied to both rigid (e.g., brain) and non-rigid (e.g. uterus) motion. It also includes several optional preprocessing stpes:

1. ROI masking/segmentation from each input stack with a CNN (only for fetal brain);

2. N4 bias filed correction for each stack;

3. Quality and motion assessment of each stack, which can be used to rank and filter the data;

4. Motion correction with SVoRT (only for fetal brain) or stack-to-stack registration.

usage: nesvor reconstruct [--input-stacks str [str ...]]
                          [--thicknesses float [float ...]]
                          [--input-slices str] [--stack-masks str [str ...]]
                          [--volume-mask str] [--stacks-intersection]
                          [--background-threshold float] [--otsu-thresholding]
                          [--output-volume str] [--output-slices str]
                          [--simulated-slices str] [--output-model str]
                          [--output-json str] [--output-resolution float]
                          [--output-intensity-mean float]
                          [--inference-batch-size int]
                          [--n-inference-samples int]
                          [--output-psf-factor float]
                          [--sample-orientation str] [--sample-mask str]
                          [--segmentation] [--batch-size-seg int]
                          [--no-augmentation-seg]
                          [--dilation-radius-seg float]
                          [--threshold-small-seg float]
                          [--bias-field-correction] [--n-proc-n4 int]
                          [--shrink-factor-n4 int] [--tol-n4 float]
                          [--spline-order-n4 int] [--noise-n4 float]
                          [--n-iter-n4 int] [--n-levels-n4 int]
                          [--n-control-points-n4 int] [--n-bins-n4 int]
                          [--metric str] [--filter-method str]
                          [--cutoff float] [--batch-size-assess int]
                          [--no-augmentation-assess] [--registration str]
                          [--svort-version str] [--scanner-space]
                          [--n-features-per-level int]
                          [--log2-hashmap-size int] [--level-scale float]
                          [--coarsest-resolution float]
                          [--finest-resolution float] [--n-levels-bias int]
                          [--depth int] [--width int] [--n-features-z int]
                          [--n-features-slice int]
                          [--no-transformation-optimization]
                          [--no-slice-scale] [--no-pixel-variance]
                          [--no-slice-variance] [--deformable]
                          [--n-features-deform int]
                          [--n-features-per-level-deform int]
                          [--level-scale-deform float]
                          [--coarsest-resolution-deform float]
                          [--finest-resolution-deform float]
                          [--weight-transformation float]
                          [--weight-bias float] [--image-regularization str]
                          [--weight-image float] [--delta float]
                          [--img-reg-autodiff] [--weight-deform float]
                          [--learning-rate float] [--gamma float]
                          [--milestones float [float ...]] [--n-iter int]
                          [--n-epochs int] [--batch-size int]
                          [--n-samples int] [--single-precision]
                          [--device int] [--verbose int] [--output-log str]
                          [--seed int] [--debug]

inputs

--input-stacks

Type: str [str ...]

Paths to the input stacks (NIfTI).

--thicknesses

Type: float [float ...]

Slice thickness of each input stack. If not provided, use the slice gap of the input stack. If only a single number is provided, Assume all input stacks have the same thickness.

--input-slices

Type: str

Folder of the input slices. i.e., the motion corrected slices generated by nesvor register. If input-slices are provided and input-stacks will be ignored.

input stacks masking

--stack-masks

Type: str [str ...]

Paths to masks of input stacks.

--volume-mask

Type: str

Paths to a 3D mask which will be applied to each input stack.

--stacks-intersection

Only consider the region defined by the intersection of input stacks. Will be ignored if --volume-mask is provided.

--background-threshold

Type: float

Default: 0

pixels with value <= this threshold will be ignored.

--otsu-thresholding

Apply Otsu thresholding to each input stack.

outputs

--output-volume

Type: str

Paths to the reconstructed volume

--output-slices

Type: str

Folder to save the motion corrected slices

--simulated-slices

Type: str

Folder to save the simulated (extracted) slices from the reconstructed volume

--output-model

Type: str

Path to save the output model (.pt)

--output-json

Type: str

Path to a json file for saving the inputs and results of the command.

outputs sampling

--output-resolution

Type: float

Default: 0.8

Isotropic resolution of the reconstructed volume

--output-intensity-mean

Type: float

Default: 700.0

mean intensity of the output volume

--inference-batch-size

Type: int

batch size for inference

--n-inference-samples

Type: int

number of sample for PSF during inference

--output-psf-factor

Type: float

Default: 1.0

Determind the psf for generating output volume: FWHM = output-resolution * output-psf-factor

--sample-orientation

Type: str

Path to a nii file. The sampled volume will be reoriented according to the transformatio in this file.

--sample-mask

Type: str

3D Mask for sampling INR. If not provided, will use a mask esitmated from the input data.

fetal brain masking

--segmentation

Perform 2D fetal brain segmentation/masking for each input stack.

--batch-size-seg

Type: int

Default: 16

Batch size for segmentation

--no-augmentation-seg

Disable inference data augmentation in segmentation

--dilation-radius-seg

Type: float

Default: 1.0

Dilation radius for segmentation mask in millimeter.

--threshold-small-seg

Type: float

Default: 0.1

Threshold for removing small segmetation mask (between 0 and 1). A mask will be removed if its area < threshold * max area in the stack.

N4 bias field correction

--bias-field-correction

Perform bias field correction using the N4 algorithm.

--n-proc-n4

Type: int

Default: 8

number of workers for the N4 algorithm.

--shrink-factor-n4

Type: int

Default: 2

The shrink factor used to reduce the size and complexity of the image.

--tol-n4

Type: float

Default: 0.001

The convergence threshold in N4.

--spline-order-n4

Type: int

Default: 3

The order of B-spline.

--noise-n4

Type: float

Default: 0.01

The noise estimate defining the Wiener filter.

--n-iter-n4

Type: int

Default: 50

The maximum number of iterations specified at each fitting level.

--n-levels-n4

Type: int

Default: 4

The maximum number of iterations specified at each fitting level.

--n-control-points-n4

Type: int

Default: 4

The control point grid size in each dimension. The B-spline mesh size is equal to the number of control points in that dimension minus the spline order.

--n-bins-n4

Type: int

Default: 200

The number of bins in the log input intensity histogram.

stack assessment

--metric

Possible choices: ncc, matrix-rank, volume, iqa2d, iqa3d, none

Default: none

Metric for assessing input stacks.

1. ncc (↑): cross correlaiton between adjacent slices;

2. matrix-rank (↓): motion metric based on the rank of the data matrix;

3. volume (↑): volume of the masked ROI;

4. iqa2d (↑): image quality score generated by a 2D CNN (only for fetal brain), the score of a stack is the average score of the images in it;

5. iqa3d (↑): image quality score generated by a 3D CNN (only for fetal brain);

6. none: no metric used for assessment.

Note: (↑) means a stack with a higher score will have a better rank.

--filter-method

Possible choices: top, bottom, threshold, percentage, none

Default: none

Method to remove low-quality stacks.

1. top: keep the top C stacks;

2. bottom: remove the bottom C stacks;

3. threshold: remove a stack if the metric is worse than C;

4. percentatge: remove the bottom (num_stack * C) stacks;

5. none: no filtering.

The value of C is specified by --cutoff.

--cutoff

Type: float

The cutoff value for filtering, i.e., the value C in --filter-method

--batch-size-assess

Type: int

Default: 8

Batch size for IQA network

--no-augmentation-assess

Disable inference data augmentation in IQA network

rigid registration

--registration

Possible choices: svort, svort-only, svort-stack, stack, none

Default: svort

The type of registration method applied before reconstruction.

1. svort: try SVoRT and stack-to-stack registration and choose the one with better NCC;

2. svort-only: only apply the SVoRT model;

3. svort-stack: only apply the stack transformations of SVoRT;

4. stack: stack-to-stack rigid registration;

5. none: no rigid registration.

Note: The SVoRT model can be only applied to fetal brain data.

--svort-version

Possible choices: v1, v2

Default: v2

Version of SVoRT model

--scanner-space

Perform registration in the scanner space. Default: register the data to the atlas space when svort or svort-stack are used.

model architecture

--n-features-per-level

Type: int

Default: 2

Length of the feature vector at each level.

--log2-hashmap-size

Type: int

Default: 19

Max log2 size of the hash grid per level.

--level-scale

Type: float

Default: 1.3819

Scaling factor between two levels.

--coarsest-resolution

Type: float

Default: 16.0

Resolution of the coarsest grid in millimeter.

--finest-resolution

Type: float

Default: 0.5

Resolution of the finest grid in millimeter.

--n-levels-bias

Type: int

Default: 0

Number of levels used for bias field estimation.

--depth

Type: int

Default: 1

Number of hidden layers in MLPs.

--width

Type: int

Default: 64

Number of neuron in each hidden layer.

--n-features-z

Type: int

Default: 15

Length of the intermediate feature vector z.

--n-features-slice

Type: int

Default: 16

Length of the slice embedding vector e.

--no-transformation-optimization

Disable optimization for rigid slice transfromation, i.e., the slice transformations are fixed

--no-slice-scale

Disable adaptive scaling for slices.

--no-pixel-variance

Disable pixel-level variance.

--no-slice-variance

Disable slice-level variance.

model architecture (deformable part)

--deformable

Enable implicit deformation field.

--n-features-deform

Type: int

Default: 8

Length of the deformation embedding vector.

--n-features-per-level-deform

Type: int

Default: 4

Length of the feature vector at each level (deformation field).

--level-scale-deform

Type: float

Default: 1.3819

Scaling factor between two levels (deformation field).

--coarsest-resolution-deform

Type: float

Default: 32.0

Resolution of the coarsest grid in millimeter (deformation field).

--finest-resolution-deform

Type: float

Default: 8.0

Resolution of the finest grid in millimeter (deformation field).

loss and regularization

--weight-transformation

Type: float

Default: 0.1

Weight of transformation regularization.

--weight-bias

Type: float

Default: 100.0

Weight of bias field regularization.

--image-regularization

Possible choices: TV, edge, L2, none

Default: edge

Type of image regularization.

1. TV: total variation (L1 regularization of image gradient);

2. edge: edge-preserving regularization, see --delta.

3. L2: L2 regularization of image gradient;

4. none: no image regularization.

--weight-image

Type: float

Default: 1.0

Weight of image regularization.

--delta

Type: float

Default: 0.2

Parameter to define intensity of an edge in edge-preserving regularization. See --image-regularization.The edge-preserving regularization becomes L1 when delta goes to 0.

--img-reg-autodiff

Use auto diff to compute the image graident in the image regularization. By default, the finite difference is used.

--weight-deform

Type: float

Default: 0.1

Weight of deformation regularization

training

--learning-rate

Type: float

Default: 0.005

Learning rate of Adam optimizer.

--gamma

Type: float

Default: 0.33

Multiplicative factor of learning rate decay.

--milestones

Type: float [float ...]

Default: [0.5, 0.75, 0.9]

List of milestones of learning rate decay. Must be in (0, 1) and increasing.

--n-iter

Type: int

Default: 6000

Number of iterations for training.

--n-epochs

Type: int

Number of epochs for training. If provided, will ignore --n-iter

--batch-size

Type: int

Default: 4096

Batch size for training.

--n-samples

Type: int

Default: 256

Number of sample for PSF during training.

--single-precision

use float32 training (default: float16/float32 mixed trainig)

miscellaneous

--device

Type: int

Default: 0

Id of the device to use. Use GPU if it is nonnegative and use CPU if it is negative.

--verbose

Possible choices: 0, 1, 2

Default: 1

Level of verbosity: (0: warning/error, 1: info, 2: debug)

--output-log

Type: str

Path to the output log file

--seed

Type: int

Random seed

--debug

Debug mode.