{"id":9842,"library":"itk-numerics","title":"ITK Numerics","description":"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.","status":"active","version":"5.4.5","language":"en","source_language":"en","source_url":"https://github.com/InsightSoftwareConsortium/ITK","tags":["image processing","numerical methods","optimization","medical imaging","scientific computing"],"install":[{"cmd":"pip install itk itk-numerics","lang":"bash","label":"Install itk-numerics with base ITK"}],"dependencies":[{"reason":"Provides the core Insight Toolkit functionality that itk-numerics extends.","package":"itk","optional":false},{"reason":"Commonly used with ITK for array manipulation and data interchange, though not strictly required for all numerics operations.","package":"numpy","optional":true}],"imports":[{"note":"All ITK functionality, including numerics components from itk-numerics, is typically accessed via the top-level `itk` module after installation.","symbol":"itk","correct":"import itk"},{"note":"Numerics components integrate directly into the `itk` namespace, not a separate `itk.numerics` submodule.","wrong":"from itk.numerics import GradientDescentOptimizer","symbol":"itk.GradientDescentOptimizer","correct":"import itk\noptimizer = itk.GradientDescentOptimizer.New()"},{"note":"Parameter containers for optimizers are typically templated with a data type (e.g., `itk.D` for double).","symbol":"itk.OptimizerParameters","correct":"import itk\nparams = itk.OptimizerParameters[itk.D].New()"}],"quickstart":{"code":"import itk\nimport numpy as np\n\n# Define a simple cost function: f(x) = (x-5)^2\n# This minimizes to x=5\nclass MyCostFunction(itk.SingleValuedCostFunction):\n    def __init__(self):\n        super().__init__()\n        self.SetNumberOfParameters(1)\n\n    def GetValue(self, parameters):\n        x = parameters.GetElement(0)\n        return (x - 5.0)**2\n\n    def GetDerivative(self, parameters, derivative):\n        x = parameters.GetElement(0)\n        derivative.SetElement(0, 2.0 * (x - 5.0))\n\n# Instantiate the cost function and optimizer\ncost_function = MyCostFunction.New()\noptimizer = itk.GradientDescentOptimizer.New()\n\n# Configure the optimizer\noptimizer.SetCostFunction(cost_function)\noptimizer.SetLearningRate(0.1)\noptimizer.SetNumberOfIterations(100)\n\n# Set initial position for optimization\ninitial_position = itk.OptimizerParameters[itk.D].New()\ninitial_position.SetSize(1)\ninitial_position.SetElement(0, 0.0) # Start optimization at x=0\noptimizer.SetInitialPosition(initial_position)\n\n# Run the optimization\nprint(f\"Initial position: {initial_position.GetElement(0):.2f}\")\noptimizer.StartOptimization()\n\nfinal_position = optimizer.GetCurrentPosition()\nprint(f\"Optimized position: {final_position.GetElement(0):.2f}\")","lang":"python","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":"6.0b01+"},{"fix":"Always use `.New()` when creating new ITK objects. Arguments are usually passed via setter methods (e.g., `optimizer.SetLearningRate(0.1)`) after instantiation.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Access numerics components directly under `itk`, e.g., `itk.GradientDescentOptimizer`, after ensuring `itk-numerics` is installed alongside `itk`.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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).","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-17T00:00:00.000Z","next_check":"2026-07-16T00:00:00.000Z","problems":[{"fix":"Ensure both `itk` and `itk-numerics` are installed: `pip install itk itk-numerics`.","cause":"The `itk-numerics` package, which provides the `GradientDescentOptimizer`, has not been installed alongside the base `itk` package.","error":"AttributeError: module 'itk' has no attribute 'GradientDescentOptimizer'"},{"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.","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.","error":"TypeError: GetValue argument must be itkOptimizerParametersD"},{"fix":"Instantiate the object with `MyObject.New()` and then use methods like `my_object.SetParameter(value)` to configure it.","cause":"Attempting to pass arguments directly to the `.New()` factory method, which expects no arguments. Configuration is done via setter methods after instantiation.","error":"TypeError: New() takes 0 positional arguments but 1 was given"}]}