Architecture Reference

Detailed architecture, design philosophy, and internal structure of SimpleITK.

ITK Relationship

SimpleITK is a simplified layer built on top of the Insight Toolkit (ITK):

• ITK: Comprehensive C++ library with 2000+ classes
• SimpleITK: Simplified interface with ~300 most commonly used algorithms
• SWIG Bindings: Automatic Python wrapper generation from C++
• Memory Management: Automatic reference counting, no manual memory management

Design Philosophy

Simplicity

• Reduced API surface compared to ITK
• Intuitive naming conventions
• Automatic memory management
• Default parameters for common use cases

Consistency

• All filters follow same patterns (OOP and procedural)
• Predictable parameter naming
• Consistent return types
• Uniform error handling

Integration

• Seamless NumPy interoperability
• Python operator overloading
• Compatible with scientific Python ecosystem
• Event system for monitoring

Flexibility

• Multiple interface styles (OOP, procedural)
• Pluggable components (metrics, optimizers, transforms)
• Extensible through ITK
• Cross-platform support

Core Architecture

Image Class

• Immutability: Images use copy-on-write semantics
• Metadata: Origin, spacing, direction always preserved
• Type Safety: Strong typing with explicit casting
• Memory: Smart pointer management, automatic cleanup

Filter Architecture

ProcessObject (base)
    ├── ImageSource
    │   ├── ImageFilter
    │   │   ├── UnaryFunctorImageFilter
    │   │   ├── BinaryFunctorImageFilter
    │   │   └── InPlaceImageFilter
    │   └── ImageSource (generators)
    └── ProcessObject methods

All filters inherit:

• Progress tracking
• Event system
• Threading control
• Debug capabilities

Transform Hierarchy

Transform (base)
    ├── MatrixOffsetTransformBase
    │   ├── AffineTransform
    │   ├── Euler2DTransform
    │   ├── Euler3DTransform
    │   ├── Similarity2DTransform
    │   └── Similarity3DTransform
    ├── BSplineTransform
    ├── DisplacementFieldTransform
    └── CompositeTransform

Type System

26 Pixel Types

• 8 scalar integer types (Int8-Int64, UInt8-UInt64)
• 2 scalar float types (Float32, Float64)
• 2 complex types (ComplexFloat32, ComplexFloat64)
• 10 vector types (VectorUInt8-VectorFloat64)
• 4 label types (LabelUInt8-LabelUInt64)

Type Safety

• Explicit casting required between types
• No automatic type promotion
• Prevents accidental precision loss
• Clear type requirements for filters

Memory Model

Copy-on-Write

• Images share pixel buffers when copied
• Automatic deep copy when modified
• Efficient for passing images
• MakeUnique() forces deep copy

NumPy Integration

• GetArrayFromImage(): Deep copy
• GetArrayViewFromImage(): Zero-copy view
• Dimension order reversal (XYZ ↔ ZYX)
• Type mapping preserved

Threading Model

Multi-Threading Support

• Most filters are thread-safe
• Automatic parallelization
• Global and per-filter thread control
• Thread pool or platform-specific threading

Thread Safety

• Image objects: Thread-safe for reading
• Filters: Independent instances are thread-safe
• Global settings: Not thread-safe (set before parallel work)

Event System

Observer Pattern

• Filters emit events during execution
• Callbacks for progress, iteration, start, end
• Used for monitoring and debugging
• Python callable or Command object

Event Types

• sitkProgressEvent: Progress updates
• sitkIterationEvent: Iteration callbacks
• sitkStartEvent: Execution start
• sitkEndEvent: Execution complete
• sitkMultiResolutionIterationEvent: Multi-resolution level change

Registration Framework

Component Architecture

ImageRegistrationMethod
    ├── Metric (similarity measure)
    ├── Optimizer (parameter search)
    ├── Transform (geometric mapping)
    ├── Interpolator (resampling)
    └── Multi-resolution pyramid

Metric Types

• Mattes Mutual Information (multi-modal)
• Mean Squares (mono-modal)
• Correlation
• ANTs Neighborhood Correlation

Optimizer Types

• Gradient Descent (first-order)
• L-BFGS-B (quasi-Newton)
• Powell (derivative-free)
• Amoeba (simplex)
• Exhaustive (grid search)

Filter Patterns

Procedural Interface

result = sitk.FilterName(input, param1=value1, param2=value2)

• Single function call
• Parameters as keyword arguments
• Returns result directly
• Convenient for simple use

Object-Oriented Interface

filter = sitk.FilterNameImageFilter()
filter.SetParam1(value1)
filter.SetParam2(value2)
result = filter.Execute(input)

• Explicit filter object
• Setter methods for parameters
• Getter methods for outputs
• Allows event callbacks and progress monitoring

Performance Architecture

Streaming

• Some filters support streaming (process in chunks)
• Reduces memory footprint
• Automatic for compatible filters

Multi-Resolution

• Pyramid generation for coarse-to-fine processing
• Used in registration
• Improves convergence and speed

Lazy Evaluation

• Filters don't execute until Execute() called
• Allows pipeline construction
• Parameter validation before execution

Python-Specific Features

Operator Overloading

• Arithmetic: +, -, *, /, %
• Logical: &, |, ^, ~
• Comparison: >, <, >=, <=, ==, !=
• In-place: +=, -=, *=, /=

Pythonic Interfaces

• Bracket notation: image[x, y, z]
• Iterator support (limited)
• Context managers (for some objects)
• Exception handling (RuntimeError)

NumPy Integration

• Bidirectional conversion
• Type mapping
• Dimension order handling
• Memory views

Extensibility

Accessing ITK

# Get underlying ITK object
itk_image = image.GetITKBase()

# Use with ITK directly (advanced)
# Requires ITK Python bindings

Custom Filters

• Can create custom filters in Python
• Inherit from ProcessObject
• Implement Execute() method
• Register with SimpleITK

Platform Support

Operating Systems

• Linux (x86_64, ARM64)
• macOS (x86_64, ARM64/M1)
• Windows (x86_64)

Python Versions

• Python 3.7+
• Pre-built wheels available
• Source build supported

Dependencies

• NumPy (required)
• No other required dependencies
• Optional: Matplotlib (for Show())

Build Configuration

Compile-Time Options

• ITK modules enabled
• File format support (DICOM, NIfTI, etc.)
• Threading backend (TBB, Platform)
• Optimization level

Runtime Configuration

• Thread count
• Coordinate tolerance
• Direction tolerance
• Debug output
• Warning display

See Also

• Performance Reference - Performance details
• Type System Reference - Complete type documentation
• Error Handling Reference - Exception handling