SimpleITK

SimpleITK is a simplified interface to the Insight Toolkit (ITK) for medical and scientific image analysis. It provides 297+ image filters for registration, segmentation, filtering, and I/O operations with extensive NumPy integration.

Quick Start

Installation

pip install SimpleITK

Basic Usage

import SimpleITK as sitk
import numpy as np

# Read, process, and write an image
image = sitk.ReadImage('input.png')
smoothed = sitk.SmoothingRecursiveGaussian(image, sigma=[2.0, 2.0])
sitk.WriteImage(smoothed, 'output.png')

# NumPy integration
array = sitk.GetArrayFromImage(image)
result = sitk.GetImageFromArray(array * 1.5)
result.CopyInformation(image)  # Preserve metadata

Core Concepts

Image Class

Central data structure for n-dimensional images (2D, 3D, 4D) with pixel data and spatial metadata (origin, spacing, direction).

# Image properties
size = image.GetSize()          # Dimensions
spacing = image.GetSpacing()    # Physical spacing
origin = image.GetOrigin()      # Physical origin

Filter Architecture

Two interfaces for all operations:

• Object-Oriented: FilterNameImageFilter() with SetParameter() and Execute()
• Procedural: FilterName(image, param=value) convenience functions

NumPy Integration

Bidirectional conversion with dimension order reversal: - SimpleITK: (width, height, depth) = (X, Y, Z) - NumPy: (depth, height, width) = (Z, Y, X)

Quick Reference

Common Operations

Pixel Types

sitkUInt8, sitkInt8, sitkUInt16, sitkInt16, sitkUInt32, sitkInt32
sitkFloat32, sitkFloat64
sitkVectorUInt8, sitkVectorFloat32  # Multi-component
sitkLabelUInt8, sitkLabelUInt16     # Segmentation masks

Interpolators

sitkNearestNeighbor  # No interpolation
sitkLinear           # Linear interpolation
sitkBSpline          # Cubic B-spline
sitkGaussian         # Gaussian interpolation

Filter Categories

Core Modules

• Image Class - Image construction, metadata, pixel access
• I/O Operations - File reading/writing, DICOM series, metadata
• NumPy Integration - Array conversion, memory views
• Transforms - Geometric transformations, registration
• Utilities - Version info, display, global settings

Image Processing Filters

• Intensity & Arithmetic - Thresholding, rescaling, statistics
• Smoothing & Denoising - Gaussian, median, bilateral, anisotropic diffusion
• Morphology - Erosion, dilation, opening, closing, watershed
• Edge Detection - Canny, Sobel, gradient computation
• Segmentation - Region growing, level sets, superpixels
• Registration - Metric-based registration, demons algorithms
• Resampling - Cropping, padding, flipping, resampling
• Distance Maps - Signed/unsigned distance transforms
• FFT & Deconvolution - Frequency domain operations
• Label Maps - Connected components, shape statistics
• Mathematical - Pixel-wise operations, operator overloading
• Miscellaneous - Histogram matching, hash computation

Guides

• Quick Start Guide - Getting started with common workflows
• Registration Guide - Image registration workflows
• Segmentation Guide - Segmentation techniques
• NumPy Integration Guide - Working with NumPy arrays

Examples

• Real-World Scenarios - Medical imaging, preprocessing pipelines
• Edge Cases - Handling special cases and corner cases
• Performance Patterns - Optimization techniques

Reference

API Documentation

• Image API - Complete Image class reference
• Core APIs - All core module APIs
• Filter APIs - Comprehensive filter documentation
• Constants & Enums - All enumerations and constants

Advanced Topics

• Architecture - Design philosophy, ITK relationship
• Performance - Threading, memory, optimization
• Error Handling - Exception types, best practices
• Type System - Pixel types, casting, conversions

Design Patterns

Object-Oriented Pattern

gaussian = sitk.DiscreteGaussianImageFilter()
gaussian.SetVariance(2.0)
output = gaussian.Execute(image)

Procedural Pattern

output = sitk.DiscreteGaussian(image, variance=2.0)

Pipeline Pattern

image = sitk.ReadImage('input.dcm')
image = sitk.SmoothingRecursiveGaussian(image, sigma=[1.5, 1.5, 1.5])
image = sitk.RescaleIntensity(image, outputMinimum=0, outputMaximum=255)
image = sitk.Cast(image, sitk.sitkUInt8)
sitk.WriteImage(image, 'output.png')

Progress Monitoring

def progress_callback():
    print(f"Progress: {filter.GetProgress():.1%}")

filter = sitk.DiscreteGaussianImageFilter()
filter.AddCommand(sitk.sitkProgressEvent, progress_callback)
output = filter.Execute(image)

Operator Overloading

# Arithmetic (also available as Add(), Subtract(), etc.)
result = image1 + image2
result = image1 - image2
result = image1 * image2
result = image1 / image2

# In-place operations
image += 10
image *= 1.5

# Logical operations
result = image1 & image2
result = image1 | image2
result = ~image

# Comparison operations
mask = image > threshold
mask = (image >= lower) & (image <= upper)

Key Features

• 297+ Image Filters: Comprehensive image processing operations
• NumPy Integration: Seamless interoperability with scientific Python
• Multiple Interfaces: Object-oriented and procedural APIs
• Spatial Metadata: Origin, spacing, direction preservation
• Type Safety: 26 pixel types with explicit casting
• Multi-threading: Automatic parallelization of filters
• Event System: Progress monitoring and callbacks
• Format Support: DICOM, NIfTI, PNG, JPEG, TIFF, MetaIO, NRRD, and more

Performance Tips

• Use SmoothingRecursiveGaussian() for large sigma values (faster than DiscreteGaussian())
• Use GetArrayViewFromImage() for read-only NumPy access (no copy)
• Set SetGlobalDefaultNumberOfThreads() to control parallelization
• Process large images slice-by-slice to reduce memory
• Use appropriate pixel types (UInt8 vs Float32) for efficiency

Common Pitfalls

• Metadata Loss: Always use CopyInformation() after NumPy processing
• Dimension Order: Remember NumPy reverses dimension order (ZYX vs XYZ)
• Type Mismatches: Use Cast() to convert between pixel types
• Memory Views: Keep image alive when using GetArrayViewFromImage()
• Physical Space: Use spacing/origin for measurements, not just pixel indices

Additional Resources

• Official Documentation: https://simpleitk.readthedocs.io/
• GitHub Repository: https://github.com/SimpleITK/SimpleITK
• Jupyter Notebooks: https://github.com/SimpleITK/SimpleITK-Notebooks
• ITK Documentation: https://itk.org/

Package Information

• Version: 2.5.3
• Language: Python (C++ with SWIG bindings)
• License: Apache 2.0
• Platform: Cross-platform (Linux, macOS, Windows)
• Dependencies: NumPy
• Python Support: 3.7+