ITK Numerics

5.4.5 · active · verified Fri Apr 17

The `itk-numerics` package provides Python bindings for the Insight Toolkit's (ITK) Numerics module, offering a suite of algorithms for numerical optimization and cost function evaluation, essential for tasks like image registration and parameter fitting. ITK itself is a powerful, open-source, cross-platform toolkit for N-dimensional scientific image analysis. The current stable version of ITK is 5.4.5, with version 6.0 in active beta development, and releases typically follow a maintenance schedule for stable branches and active development for major versions.

Common errors

```
AttributeError: module 'itk' has no attribute 'GradientDescentOptimizer'
```
cause The `itk-numerics` package, which provides the `GradientDescentOptimizer`, has not been installed alongside the base `itk` package.

fix Ensure both `itk` and `itk-numerics` are installed: `pip install itk itk-numerics`.
```
TypeError: GetValue argument must be itkOptimizerParametersD
```
cause An `itk.OptimizerParameters` object (often templated, e.g., `itk.OptimizerParameters[itk.D]`) was expected for an optimizer method, but a native Python list or NumPy array was provided instead.

fix Convert Python lists or NumPy arrays to `itk.OptimizerParameters` objects using `itk.OptimizerParameters[itk.D].New()` and setting elements, or ensure correct `itk` type is passed.
```
TypeError: New() takes 0 positional arguments but 1 was given
```
cause Attempting to pass arguments directly to the `.New()` factory method, which expects no arguments. Configuration is done via setter methods after instantiation.

fix Instantiate the object with `MyObject.New()` and then use methods like `my_object.SetParameter(value)` to configure it.

Warnings

breaking ITK 6.0 (currently in beta) introduces significant C++ modernization (requiring C++17) and changes to the build system (modern CMake module targets). While Python API breaking changes are not explicitly detailed in beta releases, a major version increment typically implies potential API shifts, especially for low-level or C++-wrapped interfaces. Review release notes carefully when upgrading from 5.x to 6.x.
Fix: Consult the ITK 6.0 release notes and documentation for specific migration guides. Test your code thoroughly in a development environment before deploying 6.x.
gotcha ITK objects, including those from `itk-numerics`, are typically instantiated using a factory method `.New()` (e.g., `itk.GradientDescentOptimizer.New()`) instead of direct Python class instantiation (`itk.GradientDescentOptimizer()`). This is a common C++ pattern ported to Python bindings.
Fix: Always use `.New()` when creating new ITK objects. Arguments are usually passed via setter methods (e.g., `optimizer.SetLearningRate(0.1)`) after instantiation.
gotcha Functionality provided by `itk-numerics` (e.g., optimizers, cost functions) is integrated directly into the main `itk` namespace. There is no separate `itk.numerics` submodule to import from.
Fix: Access numerics components directly under `itk`, e.g., `itk.GradientDescentOptimizer`, after ensuring `itk-numerics` is installed alongside `itk`.
gotcha Many ITK objects, especially images and data containers, are templated on data type and dimension in C++. In Python, this often translates to explicit type and dimension specifications using bracket notation (e.g., `itk.OptimizerParameters[itk.D]` for double parameters, or `itk.Image[itk.F, 3]` for a 3D float image).
Fix: Be mindful of required template parameters. Common types include `itk.D` (double), `itk.F` (float), `itk.SS` (short), `itk.UC` (unsigned char). Dimensions are typically integers.

Install

pip install itk itk-numerics Install itk-numerics with base ITK

Imports

itk
```
import itk
```
All ITK functionality, including numerics components from itk-numerics, is typically accessed via the top-level `itk` module after installation.
itk.GradientDescentOptimizer
wrong:
```
from itk.numerics import GradientDescentOptimizer
```
correct:
```
import itk
optimizer = itk.GradientDescentOptimizer.New()
```
Numerics components integrate directly into the `itk` namespace, not a separate `itk.numerics` submodule.
itk.OptimizerParameters
```
import itk
params = itk.OptimizerParameters[itk.D].New()
```
Parameter containers for optimizers are typically templated with a data type (e.g., `itk.D` for double).

Quickstart

This example demonstrates how to define a custom cost function and use the `GradientDescentOptimizer` to find the minimum of a simple 1D quadratic function. It showcases the typical pattern of instantiating ITK objects with `.New()` and setting parameters.

import itk
import numpy as np

# Define a simple cost function: f(x) = (x-5)^2
# This minimizes to x=5
class MyCostFunction(itk.SingleValuedCostFunction):
    def __init__(self):
        super().__init__()
        self.SetNumberOfParameters(1)

    def GetValue(self, parameters):
        x = parameters.GetElement(0)
        return (x - 5.0)**2

    def GetDerivative(self, parameters, derivative):
        x = parameters.GetElement(0)
        derivative.SetElement(0, 2.0 * (x - 5.0))

# Instantiate the cost function and optimizer
cost_function = MyCostFunction.New()
optimizer = itk.GradientDescentOptimizer.New()

# Configure the optimizer
optimizer.SetCostFunction(cost_function)
optimizer.SetLearningRate(0.1)
optimizer.SetNumberOfIterations(100)

# Set initial position for optimization
initial_position = itk.OptimizerParameters[itk.D].New()
initial_position.SetSize(1)
initial_position.SetElement(0, 0.0) # Start optimization at x=0
optimizer.SetInitialPosition(initial_position)

# Run the optimization
print(f"Initial position: {initial_position.GetElement(0):.2f}")
optimizer.StartOptimization()

final_position = optimizer.GetCurrentPosition()
print(f"Optimized position: {final_position.GetElement(0):.2f}")

view raw JSON →