tessl/pypi-itk

Insight Toolkit for N-dimensional image processing, segmentation, and registration in medical and scientific applications

—

Pending

Overview

Eval results

Files

Registration Framework

Name: tessl/pypi-itk
Author: tessl

Image registration frameworks for aligning images using transforms, metrics, and optimizers. Includes both classic and modern (v4) registration methods.

Capabilities

Registration Method v4 (Modern Framework)

class ImageRegistrationMethodv4:
    """
    Modern registration framework (v4) supporting multi-resolution and various transform types.
    
    Template parameters:
    - fixed_image_type: Fixed image type
    - moving_image_type: Moving image type
    - output_transform_type: Output transform type (optional)
    """
    
    def SetFixedImage(self, image):
        """
        Set the fixed (reference) image.
        
        Parameters:
        - image: itk.Image - Fixed image
        """
    
    def SetMovingImage(self, image):
        """
        Set the moving (to be aligned) image.
        
        Parameters:
        - image: itk.Image - Moving image
        """
    
    def SetMetric(self, metric):
        """
        Set the similarity metric.
        
        Parameters:
        - metric: ImageToImageMetricv4 - Metric for comparing images
        """
    
    def SetOptimizer(self, optimizer):
        """
        Set the optimizer.
        
        Parameters:
        - optimizer: ObjectToObjectOptimizerBase - Optimizer
        """
    
    def SetInitialTransform(self, transform):
        """
        Set the initial transform.
        
        Parameters:
        - transform: itk.Transform - Initial transformation
        """
    
    def SetMovingInitialTransform(self, transform):
        """Set initial transform for moving image."""
    
    def SetFixedInitialTransform(self, transform):
        """Set initial transform for fixed image."""
    
    def SetNumberOfLevels(self, levels):
        """
        Set the number of multi-resolution levels.
        
        Parameters:
        - levels: int - Number of levels
        """
    
    def SetSmoothingSigmasPerLevel(self, sigmas):
        """
        Set Gaussian smoothing sigmas for each level.
        
        Parameters:
        - sigmas: list of float - Sigma for each level
        """
    
    def SetShrinkFactorsPerLevel(self, factors):
        """
        Set shrink factors for each level.
        
        Parameters:
        - factors: list of int - Shrink factors for each level
        """
    
    def Update(self):
        """Execute registration."""
    
    def GetTransform(self):
        """
        Get the resulting transform.
        
        Returns:
        itk.Transform - Optimized transform
        """
    
    def GetMetricValue(self):
        """Get the final metric value."""
    
    def GetOptimizerStopConditionDescription(self):
        """Get description of why optimizer stopped."""

Registration Metrics v4

class MattesMutualInformationImageToImageMetricv4:
    """
    Mattes mutual information metric for registration.
    
    Template parameters:
    - fixed_image_type: Fixed image type
    - moving_image_type: Moving image type
    """
    
    def SetNumberOfHistogramBins(self, bins):
        """
        Set the number of histogram bins.
        
        Parameters:
        - bins: int - Number of bins (typically 50-200)
        """
    
    def SetUseMovingImageGradientFilter(self, use):
        """Enable precomputed moving image gradient."""
    
    def SetUseFixedImageGradientFilter(self, use):
        """Enable precomputed fixed image gradient."""

class MeanSquaresImageToImageMetricv4:
    """
    Mean squares metric for registration.
    
    Template parameters:
    - fixed_image_type: Fixed image type
    - moving_image_type: Moving image type
    """

class CorrelationImageToImageMetricv4:
    """
    Correlation metric for registration.
    
    Template parameters:
    - fixed_image_type: Fixed image type
    - moving_image_type: Moving image type
    """

class ANTSNeighborhoodCorrelationImageToImageMetricv4:
    """
    ANTs neighborhood correlation metric.
    
    Template parameters:
    - fixed_image_type: Fixed image type
    - moving_image_type: Moving image type
    """
    
    def SetRadius(self, radius):
        """
        Set the neighborhood radius.
        
        Parameters:
        - radius: int or itk.Size - Radius for neighborhood
        """

class DemonsImageToImageMetricv4:
    """
    Demons metric for deformable registration.
    
    Template parameters:
    - fixed_image_type: Fixed image type
    - moving_image_type: Moving image type
    """

Optimizers v4

class GradientDescentOptimizerv4:
    """
    Gradient descent optimizer for registration.
    
    Template parameter:
    - scalar_type: Scalar type (typically double)
    """
    
    def SetLearningRate(self, learning_rate):
        """
        Set the learning rate.
        
        Parameters:
        - learning_rate: float - Step size for gradient descent
        """
    
    def SetNumberOfIterations(self, iterations):
        """
        Set the number of iterations.
        
        Parameters:
        - iterations: int - Maximum number of iterations
        """
    
    def SetMinimumConvergenceValue(self, value):
        """Set minimum convergence threshold."""
    
    def SetConvergenceWindowSize(self, size):
        """Set convergence window size."""

class RegularStepGradientDescentOptimizerv4:
    """
    Regular step gradient descent optimizer.
    
    Template parameter:
    - scalar_type: Scalar type (typically double)
    """
    
    def SetLearningRate(self, learning_rate):
        """Set initial learning rate."""
    
    def SetMinimumStepLength(self, length):
        """Set minimum step length."""
    
    def SetNumberOfIterations(self, iterations):
        """Set maximum number of iterations."""
    
    def SetRelaxationFactor(self, factor):
        """Set relaxation factor for step length reduction."""

class ConjugateGradientLineSearchOptimizerv4:
    """
    Conjugate gradient line search optimizer.
    
    Template parameter:
    - scalar_type: Scalar type (typically double)
    """
    
    def SetLearningRate(self, learning_rate):
        """Set learning rate."""
    
    def SetNumberOfIterations(self, iterations):
        """Set maximum number of iterations."""

class LBFGSOptimizerv4:
    """
    Limited-memory BFGS optimizer.
    
    Template parameter:
    - scalar_type: Scalar type (typically double)
    """
    
    def SetNumberOfIterations(self, iterations):
        """Set maximum number of iterations."""
    
    def SetMaximumNumberOfFunctionEvaluations(self, evaluations):
        """Set maximum function evaluations."""
    
    def SetGradientConvergenceTolerance(self, tolerance):
        """Set gradient convergence tolerance."""

Usage Examples

Basic Registration

import itk

# Load images
fixed = itk.imread('fixed.png', itk.F)
moving = itk.imread('moving.png', itk.F)

# Set up registration
ImageType = itk.Image[itk.F, 2]
TransformType = itk.TranslationTransform[itk.D, 2]

registration = itk.ImageRegistrationMethodv4[ImageType, ImageType].New()
registration.SetFixedImage(fixed)
registration.SetMovingImage(moving)

# Create and set initial transform
initial_transform = TransformType.New()
registration.SetInitialTransform(initial_transform)

# Set metric
metric = itk.MattesMutualInformationImageToImageMetricv4[ImageType, ImageType].New()
metric.SetNumberOfHistogramBins(50)
registration.SetMetric(metric)

# Set optimizer
optimizer = itk.GradientDescentOptimizerv4Template[itk.D].New()
optimizer.SetLearningRate(1.0)
optimizer.SetNumberOfIterations(100)
registration.SetOptimizer(optimizer)

# Run registration
registration.Update()

# Get result
transform = registration.GetTransform()
print(f"Final metric value: {registration.GetMetricValue()}")

# Apply transform to moving image
resampled = itk.resample_image_filter(
    moving,
    transform=transform,
    size=itk.size(fixed),
    output_spacing=itk.spacing(fixed),
    output_origin=itk.origin(fixed)
)
itk.imwrite(resampled, 'registered.png')

Multi-Resolution Registration

import itk

fixed = itk.imread('fixed.png', itk.F)
moving = itk.imread('moving.png', itk.F)

ImageType = itk.Image[itk.F, 2]
registration = itk.ImageRegistrationMethodv4[ImageType, ImageType].New()

# Set images
registration.SetFixedImage(fixed)
registration.SetMovingImage(moving)

# Set multi-resolution parameters
registration.SetNumberOfLevels(3)
registration.SetSmoothingSigmasPerLevel([2.0, 1.0, 0.0])
registration.SetShrinkFactorsPerLevel([4, 2, 1])

# Create transform
transform = itk.AffineTransform[itk.D, 2].New()
registration.SetInitialTransform(transform)

# Set metric
metric = itk.MattesMutualInformationImageToImageMetricv4[ImageType, ImageType].New()
metric.SetNumberOfHistogramBins(50)
registration.SetMetric(metric)

# Set optimizer
optimizer = itk.RegularStepGradientDescentOptimizerv4Template[itk.D].New()
optimizer.SetLearningRate(1.0)
optimizer.SetMinimumStepLength(0.001)
optimizer.SetNumberOfIterations(200)
registration.SetOptimizer(optimizer)

# Run
registration.Update()
final_transform = registration.GetTransform()

3D Rigid Registration

import itk

fixed = itk.imread('fixed.nii.gz', itk.F)
moving = itk.imread('moving.nii.gz', itk.F)

ImageType = itk.Image[itk.F, 3]
TransformType = itk.VersorRigid3DTransform[itk.D]

registration = itk.ImageRegistrationMethodv4[ImageType, ImageType].New()
registration.SetFixedImage(fixed)
registration.SetMovingImage(moving)

# Initialize transform with image centers
transform = TransformType.New()
initializer = itk.CenteredTransformInitializer[
    TransformType,
    ImageType,
    ImageType
].New()
initializer.SetTransform(transform)
initializer.SetFixedImage(fixed)
initializer.SetMovingImage(moving)
initializer.GeometryOn()
initializer.InitializeTransform()

registration.SetInitialTransform(transform)

# Set metric
metric = itk.MattesMutualInformationImageToImageMetricv4[ImageType, ImageType].New()
metric.SetNumberOfHistogramBins(50)
registration.SetMetric(metric)

# Set optimizer
optimizer = itk.GradientDescentOptimizerv4Template[itk.D].New()
optimizer.SetLearningRate(0.5)
optimizer.SetNumberOfIterations(100)
registration.SetOptimizer(optimizer)

# Multi-resolution
registration.SetNumberOfLevels(3)
registration.SetSmoothingSigmasPerLevel([2.0, 1.0, 0.0])
registration.SetShrinkFactorsPerLevel([4, 2, 1])

# Run
registration.Update()
final_transform = registration.GetTransform()

# Apply transform
resampled = itk.resample_image_filter(
    moving,
    transform=final_transform,
    size=itk.size(fixed),
    output_spacing=itk.spacing(fixed),
    output_origin=itk.origin(fixed),
    output_direction=fixed.GetDirection()
)
itk.imwrite(resampled, 'registered_3d.nii.gz')

Install with Tessl CLI

npx tessl i tessl/pypi-itk