niimetric 0.1.5

Evaluate image quality metrics (SSIM, MAE, LPIPS, PSNR) for NIfTI images

NiiMetric

A Python CLI tool for evaluating image quality metrics between NIfTI (.nii/.nii.gz) medical images.

Features

• PSNR - Peak Signal-to-Noise Ratio
• SSIM - Structural Similarity Index (slice-based with configurable dimension)
• MAE - Mean Absolute Error
• LPIPS - Learned Perceptual Image Patch Similarity (slice-based)
• Auto-cropping - Automatically crops to brain region based on reference image (30% mean threshold)
• Foreground masking - Evaluates only on non-air regions (excludes background)
• Configurable slice dimension - Evaluate on sagittal, coronal, or axial slices
• CSV output - Save results to CSV file
• Mask export - Optionally save the foreground mask as NIfTI

Installation

pip install niimetric

Usage

Basic Usage

# Single metric
niimetric -a reference.nii.gz -b image.nii.gz --ssim -o output.csv
niimetric -a reference.nii.gz -b image.nii.gz --psnr -o output.csv
niimetric -a reference.nii.gz -b image.nii.gz --mae -o output.csv
niimetric -a reference.nii.gz -b image.nii.gz --lpips -o output.csv

# All metrics at once
niimetric -a reference.nii.gz -b image.nii.gz --all -o output.csv

Slice Dimension Selection

# Evaluate on axial slices (default)
niimetric -a reference.nii.gz -b image.nii.gz --all --dim 2 -o output.csv

# Evaluate on sagittal slices
niimetric -a reference.nii.gz -b image.nii.gz --all --dim 0 -o output.csv

# Evaluate on coronal slices
niimetric -a reference.nii.gz -b image.nii.gz --all --dim 1 -o output.csv

Save Foreground Mask

niimetric -a reference.nii.gz -b image.nii.gz --all -o output.csv --save-mask mask.nii.gz

Arguments

Argument	Description
-a, --reference	Path to reference NIfTI image (used for cropping boundaries)
-b, --image	Path to comparison NIfTI image
-o, --output	Path to output CSV file
--ssim	Calculate Structural Similarity Index
--psnr	Calculate Peak Signal-to-Noise Ratio
--mae	Calculate Mean Absolute Error
--lpips	Calculate Learned Perceptual Image Patch Similarity
--all	Calculate all metrics
--dim	Dimension for slice-based evaluation: 0=sagittal, 1=coronal, 2=axial (default: 2)
--save-mask	Path to save the foreground mask as NIfTI file

Output Format

Results are saved in CSV format:

reference,image,metric,value
reference.nii.gz,image.nii.gz,PSNR,25.432100
reference.nii.gz,image.nii.gz,SSIM,0.921500
reference.nii.gz,image.nii.gz,MAE,0.045200
reference.nii.gz,image.nii.gz,LPIPS,0.032100

How It Works

1. Load both NIfTI images
2. Auto-crop based on reference image (30% mean threshold per slice)
3. Normalize both images to 0-1 range
4. Create foreground mask from reference (10% intensity threshold)
5. Compute metrics only on foreground regions
6. Save results to CSV

Dependencies

• nibabel - NIfTI file I/O
• numpy - Array operations
• scikit-image - SSIM, PSNR calculations
• torch - LPIPS backend
• lpips - Perceptual similarity metric

Python API

You can also use niimetric as a Python library:

from niimetric import load_nifti, compute_ssim, compute_psnr, compute_mae, compute_lpips
from niimetric import auto_crop_volumes
from niimetric.metrics import create_foreground_mask
from niimetric.utils import normalize_to_range

# Load images
ref = load_nifti("reference.nii.gz")
img = load_nifti("image.nii.gz")

# Auto-crop
ref_cropped, img_cropped, bbox = auto_crop_volumes(ref, img)

# Normalize
ref_norm = normalize_to_range(ref_cropped, 0, 1)
img_norm = normalize_to_range(img_cropped, 0, 1)

# Create mask
mask = create_foreground_mask(ref_norm)

# Compute metrics
psnr = compute_psnr(ref_norm, img_norm, mask=mask)
ssim = compute_ssim(ref_norm, img_norm, mask=mask, dim=2)
mae = compute_mae(ref_norm, img_norm, mask=mask)
lpips = compute_lpips(ref_norm, img_norm, mask=mask, dim=2)

License

MIT License - see LICENSE for details.

Contributing

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