This project provides a setup.py script to build ITK Python binary
packages and infrastructure to build ITK external module Python
packages.
The Insight Toolkit (ITK) is an open-source, cross-platform system that provides developers with an extensive suite of software tools for image analysis. More information is available on the ITK website or at the ITK GitHub homepage.
- Using ITK Python Packages
- Building with ITKPythonPackage
- Frequently Asked Questions
- Additional Information
ITKPythonPackage scripts can be used to produce Python packages for ITK and ITK external modules. The resulting packages can be hosted on the Python Package Index (PyPI) for easy distribution.
To install baseline ITK Python packages:
> pip install itkTo install ITK external module packages:
> pip install itk-<module_name> import itk
import sys
input_filename = sys.argv[1]
output_filename = sys.argv[2]
image = itk.imread(input_filename)
median = itk.median_image_filter(image, radius=2)
itk.imwrite(median, output_filename)See also the ITK Python Quick Start Guide. There are also many downloadable examples on the ITK examples website.
For more information on ITK's Python wrapping, an introduction is provided in the ITK Software Guide.
ITK reusable workflows are available to build and package Python wheels as part of Continuous Integration (CI) via Github Actions runners. Those workflows can handle the overhead of fetching, configuring, and running ITKPythonPackage build scripts for most ITK external modules. See ITKRemoteModuleBuildTestPackageAction for more information.
For special cases where ITK reusable workflows are not a good fit, ITKPythonPackage scripts can be directly used to build Python wheels to target Windows, Linux, and MacOS platforms. See ITKPythonPackage ReadTheDocs documentation for more information on building wheels by hand.
ITKPythonPackage currently supports building wheels for the following platforms and architectures:
- Windows 10 x86_64 platforms
- Windows 11 x86_64 platforms
- MacOS 10.9+ x86_64 platforms
- MacOS 11.0+ arm64 platforms
- Linux glibc 2.17+ (E.g. Ubuntu 18.04+) x86_64 platforms
- Linux glibc 2.28+ (E.g. Ubuntu 20.04+) aarch64 (ARMv8) platforms
Please open an issue in the ITKPythonPackage issue tracker for discussion, and consider contributing either time or funding to support development. The ITK open source ecosystem is driven through contributions from its community members.
The Insight Toolkit consists of several baseline module groups for image analysis including filtering, I/O, registration, segmentation, and more. Community members can extend ITK by developing an ITK "external" module which stands alone in a separate repository and its independently built and tested. An ITK external module which meets community standards for documentation and maintenance may be included in the ITK build process as an ITK "remote" module to make it easier to retrieve and build.
Visit ITKModuleTemplate to get started creating a new ITK external module.
ITK uses SWIG to wrap C++ filters for use in Python.
See Chapter 9 in the ITK Software Guide
or visit ITKModuleTemplate
to get started on writing .wrap files.
After you've added wrappings for your external module C++ filters you may build and distribute Python packages automatically with ITKRemoteModuleBuildTestPackageAction or manually with ITKPythonPackage scripts.
In order to build an ITK external module you must have first built ITK for the same target platform. However, building ITK modules and wrapping them for Python can take a very long time! To avoid having to rebuild ITK before building every individual external module, artifacts from the ITK build process (headers, source files, wrapper outputs, and more) are packaged and cached as ITKPythonBuilds releases.
In order to build Python wheels for an ITK external module, ITKPythonPackage scripts first fetch the appropriate ITK Python build artifacts along with other necessary tools. Then, the module can be built, packaged, and distributed on PyPI.
Start by consulting the ITKPythonPackage ReadTheDocs documentation and the ITKPythonPackage issue tracker for discussion related to your specific issue.
If you aren't able to find an answer for your specific case, please start a discussion the ITK Discourse forum for help.
- Free software: Apache Software license
- Documentation: http://itkpythonpackage.readthedocs.org
- Source code: https://github.com/InsightSoftwareConsortium/ITKPythonPackage