niiprep 0.1.1

A CLI wrapper for TorchIO and ANTsPyX for NIfTI image processing

niiprep

A CLI wrapper for TorchIO and ANTsPyX for NIfTI image processing.

Features

• Resample NIfTI images to specified resolution
• Register NIfTI images using ANTsPyX
• Convert NIfTI images to MP4 videos
• Round NIfTI pixel values
• Denoise MP2RAGE images for improved T1w contrast
• Register images using VoxelMorph (deep learning-based registration) with multiple pre-trained models included

Installation

pip install niiprep

With VoxelMorph support:

pip install niiprep[voxelmorph]

For development:

git clone https://github.com/yourusername/niiprep.git
cd niiprep
pip install -e .

Usage

Resampling

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

Registration

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

Convert NIfTI to MP4

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

Round NIfTI pixel values

roundnii -i input.nii.gz

Denoise MP2RAGE images

denoiseMP2RAGE --uni uni.nii.gz --inv1 inv1.nii.gz --inv2 inv2.nii.gz --output denoised.nii.gz --regularization 1.0

VoxelMorph Registration

Requires optional dependency: pip install niiprep[voxelmorph]

# Using the default pre-trained model (T1_BRAIN)
vxmreg -m moving.nii.gz -f fixed.nii.gz -o moved.nii.gz

# Using a specific predefined model
vxmreg -m moving.nii.gz -f fixed.nii.gz -o moved.nii.gz --model-type BRAINS_DICE

# List all available predefined models
vxmreg --list-models

# Or specify a custom model file path
vxmreg -m moving.nii.gz -f fixed.nii.gz -o moved.nii.gz --model path/to/custom/model.pt --warp warp.nii.gz

Included VoxelMorph Models

The package includes the following pre-trained VoxelMorph models:

1. T1_BRAIN: Default model for T1-weighted brain MRI registration with MSE similarity metric. Small and fast.
2. BRAINS_DICE: Specialized brain registration model with Dice similarity and velocity field regularization. Larger but more accurate for brain images.
3. SHAPES_DICE: Generic shapes registration with Dice similarity and velocity field. Versatile for different types of images.

Note: The PyTorch version requires models in .pt format. The package will try to create placeholder models automatically. If this fails, you can create them manually with:

python -m niiprep.convert_models

Note that these are placeholder models without trained weights. The registration will still work, but may not be optimal.

Python API

You can also use niiprep as a Python package:

from niiprep import resample, register, nii_to_mp4

# Resample a NIfTI image
resample(
    input_path="input.nii.gz",
    output_path="resampled.nii.gz",
    target_spacing=(1.0, 1.0, 1.0)
)

# Register a moving image to a fixed image
register(
    fixed_path="fixed.nii.gz",
    moving_path="moving.nii.gz",
    output_path="registered.nii.gz",
    reg_type="syn"
)

# Convert a NIfTI image to MP4
nii_to_mp4(
    input_path="input.nii.gz",
    output_path="output.mp4",
    dimension=2,
    fps=10
)

# Register using VoxelMorph (requires voxelmorph package)
try:
    from niiprep import register_voxelmorph, ModelType
    
    # Using the default pre-trained model (T1_BRAIN)
    register_voxelmorph(
        moving_path="moving.nii.gz",
        fixed_path="fixed.nii.gz",
        moved_path="moved.nii.gz"
    )
    
    # Using a specific predefined model
    register_voxelmorph(
        moving_path="moving.nii.gz",
        fixed_path="fixed.nii.gz",
        moved_path="moved.nii.gz",
        model_type=ModelType.BRAINS_DICE  # Or use the string 'BRAINS_DICE'
    )
    
    # Or specify a custom model
    register_voxelmorph(
        moving_path="moving.nii.gz",
        fixed_path="fixed.nii.gz",
        moved_path="moved.nii.gz",
        model_path="path/to/custom/model.pt",
        warp_path="warp.nii.gz"  # Optional
    )
    
    # List available models
    from niiprep import list_available_models
    available_models = list_available_models()
    for name, desc in available_models.items():
        print(f"{name}: {desc}")
        
except ImportError:
    print("VoxelMorph not installed. Install with: pip install voxelmorph")

License

MIT

Contributing

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