Apply Sdc

apply_SDC - Susceptibility Distortion Correction for diffusion MRI

Part of the micaflow processing pipeline for neuroimaging data.

This module applies susceptibility distortion correction (SDC) to diffusion MRI images by using a pre-calculated displacement field to unwarp geometric distortions caused by magnetic field inhomogeneities. These distortions occur along the phase-encoding direction, which can be anterior-posterior (AP/PA), left-right (LR/RL), or superior-inferior (SI/IS).

The module works by: 1. Loading a distorted diffusion image (typically after motion correction) 2. Loading a 3D warp field containing displacement values (expected shape: nx, ny, nz) 3. Determining the phase-encoding direction from the provided argument 4. Applying the warp field to each 3D volume independently along the specified direction 5. Using linear interpolation (scipy.ndimage.map_coordinates with order=1) to resample 7. Saving the unwarped image with the specified affine transformation

API Usage:

micaflow apply_SDC

–input <path/to/distorted_image.nii.gz> –warp <path/to/warp_field.nii.gz> –affine <path/to/reference_image.nii.gz> –phase-encoding <ap|pa|lr|rl|si|is> –output <path/to/corrected_output.nii.gz>

Python Usage:

>>> from micaflow.scripts.apply_SDC import apply_SD_correction
>>> apply_SD_correction(
...     motion_corr_path="distorted_image.nii.gz",
...     warp_field=warp_field_array,  # Must be 3D numpy array (nx, ny, nz)
...     moving_affine=affine_matrix,
...     output="corrected_output.nii.gz",
...     ped="ap"  # Phase encoding direction
... )

Command Line Usage

micaflow apply_SDC [options]

Source Code

View the source code: GitHub Repository

Description

This script applies susceptibility distortion correction to diffusion images

using a pre-calculated warp field. It takes a 4D diffusion image (typically motion-corrected) and applies the displacement field to each 3D volume independently along the specified phase-encoding direction.

Full Help

╔════════════════════════════════════════════════════════════════╗
║          APPLY SUSCEPTIBILITY DISTORTION CORRECTION            ║
╚════════════════════════════════════════════════════════════════╝

This script applies susceptibility distortion correction to diffusion images
using a pre-calculated warp field. It takes a 4D diffusion image (typically
motion-corrected) and applies the displacement field to each 3D volume
independently along the specified phase-encoding direction.

────────────────────────── USAGE ──────────────────────────
  micaflow apply_SDC [options]

────────────────── REQUIRED ARGUMENTS ───────────────────
  --input            : Path to the input 4D DWI image (.nii.gz)
                    Typically motion-corrected, but any 4D image is accepted
  --warp             : Path to the 3D warp field (.nii.gz)
                    Contains displacement values along the phase-encoding direction
                    Expected shape after squeezing: (nx, ny, nz)
  --affine           : Path to a reference image (.nii.gz)
                    Used to extract the affine matrix for the output image
  --output           : Output path for the corrected 4D image (.nii.gz)

──────────────── OPTIONAL ARGUMENTS ─────────────────────
  --phase-encoding   : Phase-encoding direction (default: ap)
                    Options: ap, pa, lr, rl, si, is
                    • ap/pa: Anterior-Posterior/Posterior-Anterior (y-axis)
                    • lr/rl: Left-Right/Right-Left (x-axis)
                    • si/is: Superior-Inferior/Inferior-Superior (z-axis)

─────────────────── EXAMPLE USAGE ───────────────────────

# Apply SDC with anterior-posterior phase encoding (default)
micaflow apply_SDC \
  --input motion_corrected_dwi.nii.gz \
  --warp sdc_warpfield.nii.gz \
  --affine original_dwi.nii.gz \
  --output corrected_dwi.nii.gz

# Apply SDC with left-right phase encoding
micaflow apply_SDC \
  --input motion_corrected_dwi.nii.gz \
  --warp sdc_warpfield.nii.gz \
  --affine original_dwi.nii.gz \
  --phase-encoding lr \
  --output corrected_dwi.nii.gz

────────────────────────── NOTES ───────────────────────
• The warp field contains displacement values along the phase-encoding direction
• Phase-encoding direction must match the direction used in SDC warp calculation
• Uses linear interpolation (scipy.ndimage.map_coordinates, order=1)
• Each 3D volume in the 4D input is warped independently
• Output affine is taken from the --affine reference image, not from --input
• Common phase-encoding directions:
          - AP (anterior to posterior): y-axis, posterior distortion
          - PA (posterior to anterior): y-axis, anterior distortion
          - LR (left to right): x-axis, right distortion
          - RL (right to left): x-axis, left distortion