Terminal
Terminal/Skill
Runs structural MRI and CT preprocessing steps like skull stripping, bias correction, registration and intensity normalization.
By Amazon Web Services
Works with
npx skills add awslabs/hcls-agent-skills --skill radiology-preprocessingDeterministic commands for preprocessing structural brain MRI (T1w, T2w, FLAIR) and related volumetric radiology data. Covers the canonical pipeline used by most downstream analyses (segmentation, registration studies, deep-learning training): reorient → bias correction → skull strip → registration → intensity normalization.
Tools used:
bet, flirt, fnirt, fslmaths, fslreorient2std.N4BiasFieldCorrection, antsRegistrationSyNQuick.sh, antsApplyTransforms.mri_convert for resampling/format conversion.All commands operate on NIfTI (.nii / .nii.gz). Run in a POSIX shell with the respective tool on PATH.
Run these steps in order on a single subject volume:
# 1. Reorient to standard (MNI-style RAS orientation)
fslreorient2std input.nii.gz reoriented.nii.gz
# 2. N4 bias field correction (BEFORE skull stripping)
N4BiasFieldCorrection -d 3 \
-i reoriented.nii.gz \
-o [n4.nii.gz,bias_field.nii.gz] \
-s 3 \
-c [50x50x30x20,1e-6] \
-b [300]
# 3. Skull strip with HD-BET
hd-bet -i n4.nii.gz -o brain.nii.gz -device 0 -mode fast -tta 0
# CPU fallback (slower, no CUDA required): -device cpu
# 4. Register to MNI152 template (SyN nonlinear)
antsRegistrationSyNQuick.sh -d 3 \
-f $FSLDIR/data/standard/MNI152_T1_1mm_brain.nii.gz \
-m brain.nii.gz \
-o sub2mni_ \
-t s
# 5. Z-score intensity normalization within brain mask
fslmaths brain.nii.gz -mas brain_mask.nii.gz brain_masked.nii.gz
MEAN=$(fslstats brain_masked.nii.gz -k brain_mask.nii.gz -M)
STD=$(fslstats brain_masked.nii.gz -k brain_mask.nii.gz -S)
fslmaths brain_masked.nii.gz -sub $MEAN -div $STD -mas brain_mask.nii.gz brain_zscore.nii.gz
HD-BET writes brain.nii.gz and brain_mask.nii.gz (mask has _mask suffix by default).
HD-BET defaults to GPU; use -device 0 for first CUDA device. -mode fast -tta 0 disables test-time augmentation for ~5x speedup with minimal quality loss.
hd-bet -i n4.nii.gz -o brain.nii.gz -device 0
Do not narrate the pipeline ordering rationale or preprocessing theory unless explicitly asked — produce the correct commands in sequence with brief parameter justification.
HD-BET (preferred — robust to pathology):
hd-bet -i input.nii.gz -o output_bet.nii.gz -device cpu -mode fast -tta 0
FSL BET (fallback, classical):
bet input.nii.gz output_bet.nii.gz -R -f 0.3 -g 0
-R: robust centre-of-gravity estimation.-f 0.3: fractional intensity threshold (lower = larger brain mask).-g 0: vertical gradient in threshold.Correct low-frequency intensity inhomogeneity from RF coil / B1 field. Always run before skull stripping — the bias field estimate is better with the skull in place, and a skull-stripped input produces artifacts near the brain boundary.
N4BiasFieldCorrection -d 3 \
-i input.nii.gz \
-o [corrected.nii.gz,bias_field.nii.gz] \
-s 3 \
-c [50x50x30x20,1e-6] \
-b [300]
-d 3: 3D image.-s 3: shrink factor (speedup).-c [50x50x30x20,1e-6]: max iterations per level + convergence threshold.-b [300]: B-spline mesh resolution (mm).antsRegistrationSyNQuick.sh is the sensible default wrapper.
# Rigid (6 DOF) — same subject, different timepoint/modality
antsRegistrationSyNQuick.sh -d 3 -f fixed.nii.gz -m moving.nii.gz -o output_ -t r
# Affine (12 DOF) — cross-subject coarse alignment
antsRegistrationSyNQuick.sh -d 3 -f fixed.nii.gz -m moving.nii.gz -o output_ -t a
# SyN (nonlinear) — atlas / MNI registration
antsRegistrationSyNQuick.sh -d 3 -f fixed.nii.gz -m moving.nii.gz -o output_ -t s
Outputs (for -t s):
output_0GenericAffine.mat — affine transform.output_1Warp.nii.gz / output_1InverseWarp.nii.gz — displacement fields.output_Warped.nii.gz — moving resampled into fixed space.Apply the saved transform to another image (e.g., a segmentation):
# For intensity images — Linear interpolation
antsApplyTransforms -d 3 \
-i input.nii.gz \
-r reference.nii.gz \
-o output.nii.gz \
-t output_1Warp.nii.gz \
-t output_0GenericAffine.mat
# For label maps — NearestNeighbor interpolation
antsApplyTransforms -d 3 \
-i labels.nii.gz \
-r reference.nii.gz \
-o labels_in_ref.nii.gz \
-n NearestNeighbor \
-t output_1Warp.nii.gz \
-t output_0GenericAffine.mat
ANTs applies transforms in reverse order: the last -t is applied first. For moving→fixed, the affine is applied before the warp, so the CLI order is -t warp -t affine.
Linear (affine):
flirt -in moving.nii.gz -ref fixed.nii.gz \
-out output.nii.gz -omat affine.mat -dof 12
Nonlinear (requires affine init):
fnirt --in=moving.nii.gz \
--ref=$FSLDIR/data/standard/MNI152_T1_1mm.nii.gz \
--aff=affine.mat \
--cout=warp \
--iout=output.nii.gz
Apply warp to another image:
applywarp -i input.nii.gz -r MNI152_T1_1mm.nii.gz -w warp -o output.nii.gz
# For labels:
applywarp -i labels.nii.gz -r MNI152_T1_1mm.nii.gz -w warp -o labels_mni.nii.gz --interp=nn
Needed before most ML models — raw MRI intensities are arbitrary units and vary across scanners/sessions.
Z-score within brain mask (most common):
MEAN=$(fslstats brain.nii.gz -k brain_mask.nii.gz -M)
STD=$(fslstats brain.nii.gz -k brain_mask.nii.gz -S)
fslmaths brain.nii.gz -sub $MEAN -div $STD -mas brain_mask.nii.gz zscore.nii.gz
White matter normalization (scanner-invariant):
fslstats brain.nii.gz -k wm_mask.nii.gz -M.Histogram matching — match the intensity histogram to a reference subject:
ImageMath 3 out.nii.gz HistogramMatch moving.nii.gz reference.nii.gz.sitk.HistogramMatchingImageFilter().FreeSurfer (preferred for isotropic resampling):
mri_convert --voxel-size 1 1 1 input.nii.gz output_1mm.nii.gz
FSL:
flirt -in input.nii.gz -ref input.nii.gz -applyisoxfm 1 -out output_1mm.nii.gz
# For labels use: -interp nearestneighbour
reorient (fslreorient2std)
→ N4 bias correction
→ skull strip (HD-BET)
→ registration (ANTs SyN or FSL FNIRT)
→ intensity normalization (z-score / WM)
Resampling to isotropic 1 mm is usually done either at reorient time (if input is anisotropic) or implicitly by registration to a 1 mm template.
| Task | Command |
|---|---|
| Reorient to standard | fslreorient2std in.nii.gz out.nii.gz |
| N4 bias correction | N4BiasFieldCorrection -d 3 -i in.nii.gz -o [out.nii.gz,bias.nii.gz] -s 3 -c [50x50x30x20,1e-6] -b [300] |
| Skull strip (HD-BET) | hd-bet -i in.nii.gz -o brain.nii.gz -device cpu -mode fast -tta 0 |
| Skull strip (BET) | bet in.nii.gz brain.nii.gz -R -f 0.3 -g 0 |
| Rigid register (ANTs) | antsRegistrationSyNQuick.sh -d 3 -f fix.nii.gz -m mov.nii.gz -o out_ -t r |
| Affine register (ANTs) | antsRegistrationSyNQuick.sh -d 3 -f fix.nii.gz -m mov.nii.gz -o out_ -t a |
| SyN register (ANTs) | antsRegistrationSyNQuick.sh -d 3 -f fix.nii.gz -m mov.nii.gz -o out_ -t s |
| Apply ANTs transform (image) | antsApplyTransforms -d 3 -i in.nii.gz -r ref.nii.gz -o out.nii.gz -t out_1Warp.nii.gz -t out_0GenericAffine.mat |
| Apply ANTs transform (labels) | Add -n NearestNeighbor |
| FLIRT affine | flirt -in mov.nii.gz -ref fix.nii.gz -out out.nii.gz -omat aff.mat -dof 12 |
| FNIRT nonlinear | fnirt --in=mov.nii.gz --ref=MNI152_T1_1mm.nii.gz --aff=aff.mat --cout=warp --iout=out.nii.gz |
| Z-score normalize | fslmaths in.nii.gz -sub $MEAN -div $STD -mas mask.nii.gz out.nii.gz |
| Histogram match (ANTs) | ImageMath 3 out.nii.gz HistogramMatch mov.nii.gz ref.nii.gz |
| Resample isotropic 1 mm | mri_convert --voxel-size 1 1 1 in.nii.gz out.nii.gz |
$FSLDIR/data/standard/MNI152_T1_1mm.nii.gz — whole-head.$FSLDIR/data/standard/MNI152_T1_1mm_brain.nii.gz — brain-only.$FSLDIR/data/standard/MNI152_T1_2mm_brain.nii.gz — 2 mm for faster registration.Wrong: Running skull stripping before bias field correction Right: Always run N4 bias correction first, then skull strip Why: Bias field estimation needs the full field of view including skull/neck to fit a smooth B-spline; N4 on an already-stripped brain introduces edge artifacts and leaves residual inhomogeneity
Wrong: Using linear/trilinear interpolation when resampling label maps
Right: Use NearestNeighbor (ANTs: -n NearestNeighbor; FSL: --interp=nn) for any discrete label volume
Why: Linear interpolation on integer segmentation labels produces meaningless fractional values and destroys class boundaries
Wrong: Specifying ANTs transforms in forward CLI order (affine then warp)
Right: Use -t output_1Warp.nii.gz -t output_0GenericAffine.mat — warp first in CLI, affine second
Why: antsApplyTransforms composes in reverse CLI order (last -t applied first); reversing them silently produces misregistered output
Wrong: Registering each longitudinal timepoint independently to MNI Right: Build a subject-specific midpoint template, register each timepoint to it, then register the midpoint once to MNI Why: Independent registration introduces asymmetric interpolation bias that corrupts longitudinal measurements (e.g., atrophy)
Wrong: Skipping reorientation at the start of the pipeline
Right: Always run fslreorient2std first on inputs from different scanners/vendors
Why: Inconsistent storage orientations cause downstream tools to misinterpret coordinate frames
Wrong: Computing z-score normalization over the full volume including background
Right: Compute mean/std within the brain mask only (fslstats -k brain_mask.nii.gz)
Why: Including background zeros drags the mean down and inflates the standard deviation, producing incorrect normalization