NiiPrep

A CLI wrapper for TorchIO and ANTsPyX for NIfTI image processing

Overview

NiiPrep is a Python package that provides convenient command-line tools for common neuroimaging preprocessing tasks. It combines the power of TorchIO and ANTsPyX libraries to offer streamlined workflows for NIfTI image manipulation, registration, resampling, and visualization.

Features

Image Resampling: Change voxel spacing with multiple interpolation methods
Image Registration: Rigid, affine, and deformable registration using ANTsPyX
Image Denoising: Non-local means denoising using ANTs, plus MATLAB-based Rice/VST denoising
Bias Field Correction: N4 bias field correction using ANTs, or SPM12-based bias correction
Video Conversion: Convert NIfTI files to MP4 videos for visualization
Image Cropping/Padding: Resize images to specified dimensions or automatically remove empty space
Value Rounding: Round pixel values in NIfTI images
MP2RAGE Denoising: Robust combination processing for MP2RAGE images
3D Patch Parcellation: Split NIfTI volumes into 3D patches and reconstruct, with automatic background filtering

Installation

pip install niiprep

Requirements

Python >= 3.7
TorchIO >= 0.18.0
ANTsPyX >= 0.3.0
NiBabel >= 3.0.0
NumPy >= 1.19.0
OpenCV (for video conversion)
Matplotlib (for MP2RAGE processing)
patchify >= 0.1.0 (for patch parcellation)
MATLAB (for mdenoise)
MATLAB + SPM12 (for mbiascorrect)

Command-Line Tools

After installation, the following commands are available:

1. `resample` - Image Resampling

Resample NIfTI images to specified voxel spacing.

resample -i input.nii.gz -o output.nii.gz -s 1.0 1.0 1.0 --interpolation linear

Parameters:

-i, --input: Path to input NIfTI file
-o, --output: Path to save resampled NIfTI file
-s, --spacing: Target voxel spacing in mm (x y z), default: 1.0 1.0 1.0
--interpolation: Interpolation method (linear, nearest, bspline), default: linear

2. `registernii` - Image Registration

Register moving image to fixed image using ANTsPyX.

registernii -f fixed.nii.gz -m moving.nii.gz -o registered.nii.gz -t syn --interpolation linear
registernii -f fixed.nii.gz -m moving.nii.gz -o registered.nii.gz -t syn --norm

Parameters:

-f, --fixed: Path to fixed/reference NIfTI file
-m, --moving: Path to moving NIfTI file
-o, --output: Path to save registered NIfTI file
-t, --type: Registration type (rigid, affine, syn), default: syn
--interpolation: Interpolation type, default: linear
--norm: Min-max normalize intensities to 0-255 and round before saving (optional)

3. `nii2mp4` - Video Conversion

Convert NIfTI files to MP4 videos for visualization.

nii2mp4 -i input.nii.gz -o output.mp4 -d 2 --fps 10

Parameters:

-i, --input: Path to input NIfTI file
-o, --output: Path to save MP4 file
-d, --dimension: Dimension to slice along (0: sagittal, 1: coronal, 2: axial), default: 2
--fps: Frames per second, default: 10
--no-normalize: Disable intensity normalization

4. `crop` - Image Cropping/Padding

Crop or pad NIfTI images to specified shape.

crop -i input.nii.gz -o output.nii.gz -s 256 256 256

Parameters:

-i, --input: Path to input NIfTI file
-o, --output: Path to save cropped/padded NIfTI file
-s, --shape: Target image shape, default: 256 256 256

5. `roundnii` - Value Rounding

Round pixel values in NIfTI images.

roundnii -i input.nii.gz

Parameters:

-i, --input: Path to input NIfTI file (will be overwritten)

6. `denoise` - Image Denoising

Denoise NIfTI images using ANTs denoising algorithm. Values are rounded before saving, and can optionally be normalized to 0-255 range.

denoise -i input.nii.gz -o denoised.nii.gz
denoise -i input.nii.gz -o denoised.nii.gz --norm

Parameters:

-i, --input: Path to input NIfTI file
-o, --output: Path to save denoised NIfTI file
--norm: Min-max normalize intensities to 0-255 and round before saving (optional)

7. `mdenoise` - MATLAB Image Denoising

Denoise NIfTI images using the bundled MATLAB Rice/VST denoising routine. Requires MATLAB to be installed and available on the system PATH.

mdenoise -i input.nii.gz -o denoised.nii.gz

Parameters:

-i, --input: Path to input NIfTI file
-o, --output: Path to save denoised NIfTI file

Notes:

The command converts the input to a temporary .nii file for MATLAB, runs new_denoising_func_matlab_matrix, and saves the first denoised output.
MATLAB assets are packaged under niiprep/denoise.

8. `biascorrect` - N4 Bias Field Correction

Apply N4 bias field correction using ANTs. Values are rounded before saving, and can optionally be normalized to 0-255 range.

biascorrect -i input.nii.gz -o corrected.nii.gz
biascorrect -i input.nii.gz -o corrected.nii.gz --norm

Parameters:

-i, --input: Path to input NIfTI file
-o, --output: Path to save bias-corrected NIfTI file
--norm: Min-max normalize intensities to 0-255 and round before saving (optional)

9. `denoiseMP2RAGE` - MP2RAGE Denoising

Process MP2RAGE images with robust combination to reduce background noise.

denoiseMP2RAGE --uni uni.nii.gz --inv1 inv1.nii.gz --inv2 inv2.nii.gz -o denoised.nii.gz -r 1.0

Parameters:

--uni: Path to UNI image
--inv1: Path to INV1 image
--inv2: Path to INV2 image
-o, --output: Output path for processed image
-r, --regularization: Noise regularization factor (optional, interactive mode if not specified)

10. `mbiascorrect` - SPM12 Bias Field Correction

Apply SPM12 unified segmentation-based bias field correction. Accepts .nii or .nii.gz inputs. Requires MATLAB and SPM12 to be installed and on the system PATH.

mbiascorrect -i input.nii.gz -o corrected.nii.gz
mbiascorrect -i input.nii.gz -o corrected.nii.gz --save-masks
mbiascorrect -i input.nii.gz -o corrected.nii.gz --spm-path /path/to/spm12

Parameters:

-i, --input: Path to input NIfTI file (.nii or .nii.gz)
-o, --output: Path to save bias-corrected NIfTI file (.nii or .nii.gz)
--spm-path: Path to SPM12 installation (default: /ihome/tibrahim/jil202/spm12)
--window-size: Bias FWHM in mm, controls smoothness of estimated bias field (default: 60)
--sphere-size: Sphere size for brain mask in mm (default: 50)
--include-c3: Include CSF (c3) tissue class in segmentation (optional)
--save-masks: Save SPM tissue segmentation maps (c1–c5) alongside the output (optional)

Notes:

SPM12 saves tissue probability maps for GM (c1), WM (c2), CSF (c3), bone (c4), and soft tissue (c5). These are discarded by default; use --save-masks to keep them.
.mat segmentation parameter files generated by SPM are always discarded.

11. `autocropnii` - Automatic Image Cropping

Automatically crop NIfTI images to remove empty space (based on gradient detection) and optionally pad to a specific shape or multiple.

autocropnii -i input.nii.gz -o output.nii.gz -n 14

Parameters:

-i, --input: Path to input NIfTI file
-o, --output: Path to save cropped/padded NIfTI file
-n: Optional integer. If provided, output dimensions will be padded to be multiples of this value. Default is None (tight crop).
-s, --shape: Optional target shape (x y z). If provided, output will maximize this shape. If used with -n, dimensions are adjusted to the closest smaller multiple of n.

12. `patchifynii` - 3D Patch Parcellation

Split a 3D NIfTI image into overlapping or non-overlapping patches. Each patch is saved as an individual .nii.gz file with a spatially correct affine, alongside a patches_meta.json used for reconstruction. Background and noise patches are automatically skipped using Otsu's threshold.

# Non-overlapping 32³ patches, auto background filtering
patchifynii -i input.nii.gz -o ./patches -p 32 32 32 --norm

# Overlapping patches (step < patch size)
patchifynii -i input.nii.gz -o ./patches -p 64 64 64 -s 32 --norm

# Stricter foreground filter (keep only patches with >20% foreground voxels)
patchifynii -i input.nii.gz -o ./patches -p 32 32 32 --norm --min-nonzero-frac 0.2

Parameters:

-i, --input: Path to input NIfTI file
-o, --output: Output directory for patches and metadata
-p, --patch-size: Patch size in voxels (x y z)
-s, --step: Step size between patches (default: min(patch_size), non-overlapping)
--norm: Normalize image intensities to [0, 1] before patchifying
--min-nonzero-frac: Skip patches where fewer than this fraction of voxels are foreground (default: 0.01)
--min-intensity-range: Skip patches whose max−min intensity ≤ this value (default: 0.0, disabled)
--foreground-threshold: Intensity above which a voxel counts as foreground (default: auto Otsu on the full image)
--no-pad: Raise an error instead of zero-padding when image dimensions are incompatible with patch/step size

Notes:

Images are automatically zero-padded so dimensions satisfy (dim − patch_size) % step == 0. The original shape is stored in metadata and cropped back on reconstruction.
The foreground threshold defaults to Otsu's threshold computed on the full image, so no manual tuning is needed.

13. `unpatchifynii` - Patch Reconstruction

Reconstruct a 3D NIfTI image from patches created by patchifynii. Skipped (background) patches are filled with zeros.

unpatchifynii -i ./patches -o reconstructed.nii.gz

Parameters:

-i, --input: Directory containing patches and patches_meta.json
-o, --output: Path to save reconstructed NIfTI file

Python API

You can also use NiiPrep functions directly in Python:

from niiprep import resample, register, nii_to_mp4, mdenoise
from niiprep.patchify_nii import patchify_nii, unpatchify_nii

# Resample an image
resample(
    input_path='input.nii.gz',
    output_path='output.nii.gz',
    target_spacing=(1.0, 1.0, 1.0),
    interpolation='linear'
)

# Register images
register(
    fixed_path='fixed.nii.gz',
    moving_path='moving.nii.gz',
    output_path='registered.nii.gz',
    reg_type='syn'
)

# Convert to video
nii_to_mp4(
    input_path='input.nii.gz',
    output_path='output.mp4',
    dimension=2,
    fps=10
)

# MATLAB denoise
mdenoise(
    input_path='input.nii.gz',
    output_path='matlab_denoised.nii.gz',
)

# Split into 3D patches (auto background filtering, normalize to [0,1])
patchify_nii(
    input_path='input.nii.gz',
    output_dir='./patches',
    patch_size=(64, 64, 64),
    step=32,          # overlapping; omit for non-overlapping
    norm=True,
    min_nonzero_frac=0.1,
)

# Reconstruct from patches
unpatchify_nii(
    input_dir='./patches',
    output_path='reconstructed.nii.gz',
)

Examples

Basic Preprocessing Pipeline

# 1. Denoise the raw image
denoise -i raw.nii.gz -o denoised.nii.gz

# 2. Apply bias field correction
biascorrect -i denoised.nii.gz -o corrected.nii.gz

# 3. Resample to 1mm isotropic
resample -i corrected.nii.gz -o resampled.nii.gz -s 1.0 1.0 1.0

# 4. Crop to standard size (or use autocrop for automatic sizing)
crop -i resampled.nii.gz -o cropped.nii.gz -s 256 256 256
# OR
autocropnii -i resampled.nii.gz -o cropped.nii.gz -n 14

# 5. Register to template with normalization
registernii -f template.nii.gz -m cropped.nii.gz -o registered.nii.gz -t affine --norm

# 6. Create visualization video
nii2mp4 -i registered.nii.gz -o preview.mp4 --fps 15

Patch-Based Processing Pipeline

# 1. Preprocess
denoise -i raw.nii.gz -o denoised.nii.gz
biascorrect -i denoised.nii.gz -o corrected.nii.gz

# 2. Split into 64³ patches, normalize, skip background
patchifynii -i corrected.nii.gz -o ./patches -p 64 64 64 --norm

# 3. ... process patches (e.g. feed into a model) ...

# 4. Reconstruct
unpatchifynii -i ./patches -o reconstructed.nii.gz

MP2RAGE Processing

# Process MP2RAGE data with automatic noise estimation
denoiseMP2RAGE --uni MP2RAGE_UNI.nii.gz \
               --inv1 MP2RAGE_INV1.nii.gz \
               --inv2 MP2RAGE_INV2.nii.gz \
               -o MP2RAGE_denoised.nii.gz

MATLAB Denoising

# Run the bundled MATLAB Rice/VST denoising routine
mdenoise -i raw.nii.gz -o matlab_denoised.nii.gz

Development

This package is built on top of:

TorchIO: For medical image processing and transformations
ANTsPyX: For advanced image registration
NiBabel: For NIfTI file I/O
OpenCV: For video generation
MATLAB: For the optional MATLAB denoising and SPM12 bias-correction workflows

Author

Jinghang Li
Email: jinghang.li@pitt.edu

License

MIT License

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Changelog

Version 0.2.0

Added patchifynii: split 3D NIfTI volumes into patches with automatic zero-padding, normalization, and Otsu-based background filtering
Added unpatchifynii: reconstruct volumes from patches with automatic crop-back to original shape
Added patchify>=0.1.0 dependency
Added mdenoise: MATLAB-based Rice/VST denoising command and Python API

Version 0.1.0

Initial release
Basic resampling, registration, and conversion tools
MP2RAGE denoising functionality
Command-line interface for all tools

Name		Name	Last commit message	Last commit date
Latest commit History 38 Commits
src/niiprep		src/niiprep
.gitignore		.gitignore
README.md		README.md
setup.py		setup.py

Folders and files

Latest commit

History

Repository files navigation

NiiPrep

Overview

Features

Installation

Requirements

Command-Line Tools

1. resample - Image Resampling

2. registernii - Image Registration

3. nii2mp4 - Video Conversion

4. crop - Image Cropping/Padding

5. roundnii - Value Rounding

6. denoise - Image Denoising

7. mdenoise - MATLAB Image Denoising

8. biascorrect - N4 Bias Field Correction

9. denoiseMP2RAGE - MP2RAGE Denoising

10. mbiascorrect - SPM12 Bias Field Correction

11. autocropnii - Automatic Image Cropping

12. patchifynii - 3D Patch Parcellation

13. unpatchifynii - Patch Reconstruction

Python API

Examples

Basic Preprocessing Pipeline

Patch-Based Processing Pipeline

MP2RAGE Processing

MATLAB Denoising

Development

Author

License

Contributing

Changelog

Version 0.2.0

Version 0.1.0

About

Resources

Stars

Watchers

Forks

Releases

Packages

Used by

Contributors

Languages

1. `resample` - Image Resampling

2. `registernii` - Image Registration

3. `nii2mp4` - Video Conversion

4. `crop` - Image Cropping/Padding

5. `roundnii` - Value Rounding

6. `denoise` - Image Denoising

7. `mdenoise` - MATLAB Image Denoising

8. `biascorrect` - N4 Bias Field Correction

9. `denoiseMP2RAGE` - MP2RAGE Denoising

10. `mbiascorrect` - SPM12 Bias Field Correction

11. `autocropnii` - Automatic Image Cropping

12. `patchifynii` - 3D Patch Parcellation

13. `unpatchifynii` - Patch Reconstruction