medical-image-resampler

name	medical-image-resampler
description	Resample NIfTI medical images to target spacing with configurable interpolation methods and optional anti-aliasing for downsampling.
version	0.1.0
author	Medical AI Team <[e-mail]>
license	MIT
tags	["preprocessing","resampling","spatial","nifti"]
maturity	stable
category	preprocessing
requires_extras	["core"]

Medical Image Resampler

Overview

This skill resamples NIfTI medical images to a target voxel spacing using various interpolation methods. It supports isotropic and anisotropic resampling, with optional anti-aliasing filtering for downsampling operations to prevent aliasing artifacts.

Use this skill when you need to:

• Standardize voxel spacing across a dataset
• Prepare images for algorithms that require isotropic voxels
• Upsample images to higher resolution
• Downsample images for faster processing or memory constraints

Installation

pip install -r requirements.txt

Dependencies:

• nibabel >= 4.0.0
• numpy >= 1.20.0
• scipy >= 1.7.0

Usage

./scripts/main.py [OPTIONS] INPUT_PATH

Arguments

Argument	Required	Description
input_path	Yes	Path to input NIfTI file (.nii or .nii.gz)

Options

Option	Default	Description
--output, -o	stdout	Output file path (required)
--spacing	-	Target spacing: "1.0,1.0,1.0" or single value "1.0"
--interpolation	linear	Interpolation method: linear, nearest, cubic
--anti-aliasing	false	Apply anti-aliasing filter for downsampling
--verbose, -v	false	Enable verbose logging
--version	-	Show version and exit
--help	-	Show help message

Input Schema

File Format: NIfTI-1 or NIfTI-2 (.nii, .nii.gz)

Requirements:

• Valid NIfTI header
• 3D or 4D image data
• Valid affine transformation matrix

Output Schema

JSON Report (stdout)

{
  "success": true,
  "result": {
    "input_path": "string - path to input file",
    "output_path": "string - path to output file",
    "input_spacing": [float, float, float],
    "output_spacing": [float, float, float],
    "input_shape": [int, int, int],
    "output_shape": [int, int, int],
    "interpolation": "string - method used",
    "anti_aliasing": "boolean - whether applied",
    "resampling_factors": [float, float, float]
  },
  "metadata": {
    "timestamp": "ISO 8601 timestamp",
    "duration_ms": 123,
    "version": "0.1.0"
  }
}

Output File

NIfTI file with:

• Resampled image data
• Updated affine matrix reflecting new spacing
• Preserved header metadata where applicable

Exit Codes

Code	Meaning
0	Success
1	Validation error (invalid NIfTI, invalid parameters)
2	Runtime error (file I/O, resampling failure)
3	Usage error (missing required arguments)

Examples

Isotropic resampling to 1mm

./scripts/main.py brain.nii.gz -o brain_1mm.nii.gz --spacing 1.0 --verbose

Output:

{
  "success": true,
  "result": {
    "input_path": "brain.nii.gz",
    "output_path": "brain_1mm.nii.gz",
    "input_spacing": [0.8, 0.8, 1.2],
    "output_spacing": [1.0, 1.0, 1.0],
    "input_shape": [256, 256, 150],
    "output_shape": [205, 205, 125],
    "interpolation": "linear",
    "anti_aliasing": false,
    "resampling_factors": [1.25, 1.25, 0.96]
  },
  "metadata": {
    "timestamp": "2024-01-15T10:30:00",
    "duration_ms": 1250,
    "version": "0.1.0"
  }
}

Anisotropic resampling with cubic interpolation

./scripts/main.py spine.nii.gz -o spine_resampled.nii.gz --spacing "0.5,0.5,2.0" --interpolation cubic

Downsampling with anti-aliasing

./scripts/main.py high_res.nii.gz -o low_res.nii.gz --spacing "2.0,2.0,2.0" --anti-aliasing

Process multiple files (shell loop)

for f in data/*.nii.gz; do
    ./scripts/main.py "$f" -o "resampled/$(basename $f)" --spacing 1.0
done

Interpolation Methods

Method	Description	Use Case
nearest	Nearest neighbor interpolation	Labels/segmentations, preserving discrete values
linear	Trilinear interpolation (default)	General purpose, continuous intensity data
cubic	Tricubic interpolation	High-quality resampling, smooth data

Anti-Aliasing

When downsampling (increasing voxel size), high-frequency content can cause aliasing artifacts. The --anti-aliasing flag applies a Gaussian pre-filter before resampling.

The filter sigma is automatically computed based on the resampling factor:

• σ = 0.5 × (resampling_factor - 1) for each dimension where factor > 1

Assumptions and Limitations

• Input must be a valid NIfTI file
• Affine matrix must be invertible
• Output dimensions must fit in memory
• 4D images: resampling applies to spatial dimensions only

Error Handling

The skill handles the following error cases:

Error	Exit Code	Message
Input file not found	2	"Input file not found: {path}"
Invalid NIfTI format	1	"Invalid NIfTI file: {reason}"
Invalid spacing format	3	"Invalid spacing format: expected 'x,y,z' or single value"
Invalid spacing values	1	"Spacing values must be positive"
Invalid interpolation	3	"Invalid interpolation method"
Output write failure	2	"Failed to write output: {reason}"

References

• references/resampling-guide.md - Detailed algorithm description
• NIfTI Standard - File format specification
• SimpleITK Resampling - Reference implementation

Disclaimer

For research use only. This skill is not intended for clinical use.

Changelog

0.1.0 (2024-01-15)

• Initial release
• Support for NIfTI format
• Linear, nearest, cubic interpolation
• Optional anti-aliasing filter
• JSON report output