ITK 5.1 Beta 1: NumPy Interface, Part 1

We are happy to announce that the Insight Toolkit (ITK) 5.1 Beta 1 is available for testing! :tada: ITK is an open-source, cross-platform toolkit for N-dimensional scientific image processing, segmentation, and registration.

ITK 5.1 Beta 1 is a pre-release to enable testing of major improvements to ITK’s NumPy interface.

Python Packages

ITK Python packages can be installed by running:

pip install --upgrade --pre itk

The --pre flag will install the beta pre-release.

Library Sources

Testing Data

Unpack optional testing data in the same directory where the Library Source is unpacked.


Pass NumPy Array’s to ITK Image Filters

The Pythonic, functional-like interface to all ITK image-to-image-filters now directly supports operation on NumPy array’s, i.e. numpy.ndarray. If a ndarray is passed as an input, a ndarray is returned as an output.

For example,

smoothed = itk.median_image_filter(array, radius=2)

Previously, explicit conversion to / from an itk.Image was required with itk.array_from_image and itk.image_from_array.

We can now also convert an itk.Image to a numpy.ndarray with the standard np.asarray call.

import numpy as np
import itk

image = itk.imread('/path/to/image.tif')
array = np.asarray(image)

Python 3 Only

ITK 5.1 will be the first Python 3-only release. Consistent with most scientific Python packages and CPython’s 2020 drop in support, Python 2 support and binaries will no longer be available.

clang-format enforced C++ coding style

ITK has adopted a .clang-format coding style configuration file so a consistent coding style can automatically be applied to C++ code with the clang-format binary. A consistent coding style is critical for readability and collaborative development.

clang-format has been applied to the entire codebase. The Whitesmiths style of brace indentation, previously part of the ITK Coding Style Guidelines, is not supported by clang-format, so it has been replaced by a brace style consistent with VTK’s current style.

A Git commit hook will automatically apply clang-format to changed C++ code. We are refining the related documentation and improving automated application of the style.

Point Set Registration Parallelism

ITK provides a powerful registration framework for point-set registration, offering information-theoretic similarity metrics, labeled point-set metrics, and spatial transformation models that range from affine to b-spline to dense displacement fields. ITK 5.1 features enhanced parallelism in point-set metric computation, leveraging the native thread-pool and Threading Building Blocks (TBB) enhancements in ITK 5.

ITK 5 Improvements

Many more improvements and refinements were added since the ITK 5.0.0 release, which are detailed in the change log below. For example, a number of improvements were made to the itk::SpatialObject’s.


Congratulations and thank you to everyone who contributed to this release. Of the 25 authors, we would like to specially recognize the new contributors: James Butler, Neslisah Torosdagli, Rinat Mukhometzianov, Genevieve Buckley, and yjcchen091.

What’s Next

Additional improvements ITK’s NumPy interface are planned for the next pre-release. Try out the current release, and take part in the community discussion at Contribute with pull requests, code reviews, and issue discussions in our GitHub Organization.

Enjoy ITK!

Changes from 5.0.0 to 5.1 Beta 1

Bradley Lowekamp @blowekamp (32):
      BUG: Use ProcessObject GetInput to obtain base pointer
      BUG: Fix ProcessObject::RemoveOutput for null objects.
      COMP: Address missing fftw include in CurvatureRegistrationFilter
      BUG: Fix ProcessObject::RemoveOutput for null objects.
      BUG: Add casting for vector pixel types
      ENH: Add testing for CastImageFilter for more type conversions
      BUG: Restore support for Cast between explicitly cast-ed pixel type
      BUG: Use ProcessObject GetInput to obtain base pointer
      ENH: Add testing for CastImageFilter for more type conversions
      BUG: Restore support for Cast between explicitly cast-ed pixel type
      BUG: Add DataObject::New method
      BUG: Install FFTW headers in same location as ITK
      Revert "BUG: InterpolateImageFunction::GetRadius hidden in ITKV4_COMPATIBILITY"
      BUG: Preserve Interpolate GetRadius behavior with ITKv4Compatibility
      Revert "COMP: forgotten class for ITKV4_COMPATIBILITY in 2aae174"
      BUG: HDF5 is clobbering ctest TIMEOUT variables
      COMP: Fix not marked 'override' for ImageSink destructor
      BUG: Use enable_if with SFINAE to dispatch
      ENH: Add Vector constructor from C arrays with cast
      COMP: Work around uninitialized value warnings
      ENH: Update ITKv4 registration example to use resample over warp
      BUG: Specify specific CircleCI docker image with platform
      COMP: Address compilation warning with aggregate initializer
      BUG: Specify specific CircleCI docker image with platform
      ENH: Adding VS2019 v142, VS2017 v140 Azure Pipelines on merge
      DOC: Tweak internal documentation in SliceImageFilter
      BUG: Address bug with small size in output of SliceImageFilter
      ENH: Add more test cases for the SliceImageFilter
      COMP: Address internal compiler error on MSVC 19.0.24234.1 (v140)
      ENH: Add check expected input in HistogramMatchingImageFilter
      COMP: Add missing enum type_name from prior enum declaration style

Csaba Pinter @cpinter (2):
      BUG: Fix loading of DICOM files with no preamble
      ENH: Add test for DICOM without preamble for DCMTK and GDCM

Davis Vigneault @DVigneault (1):
      BUG: Make BuildCellLinks method const

Dženan Zukić @dzenanz (32):
      BUG: number of work units was greater than 1 even for 1 thread
      BUG: fix a crash with ITK_DEFAULT_MAX_THREADS greater than 250
      BUG: resample filter no longer triggers unnecessary exception
      COMP: change export specification to template for un-specialized method
      COMP: forgotten class for ITKV4_COMPATIBILITY in 2aae174
      ENH: use double-conversion's CMake targets
      COMP: fix warning about missing override in CastImageFilter
      DOC: wrong class name for PlatformMultiThreader
      COMP: get rid of MSVC's warning 4661
      ENH: enable GaussianInterpolateImageFunction to work with streaming
      STYLE: reduce space in ivar declarations
      STYLE: ITK indentation style in test
      STYLE: invert the name and internal logic of waiting for threads
      BUG: ThreadPool::DoNotWaitForThreads did not work properly
      STYLE: Add ITK prefix to testing macros in release branch
      DOC: invocation of AddWork uses -> because instance is always a pointer
      ENH: updating remote modules
      ENH: PoolMultiThreader uses one less thread
      ENH: documenting supported compilers
      ENH: updating remote modules
      STYLE: more consistent code formatting in test driver
      BUG: offset was not updated after changing Euler angle order (ZYX)
      Fix broken link in
      ENH: support RGB image in windowed sinc interpolation
      ENH: support RGB image in windowed sinc interpolation
      ENH: updating remote modules
      ENH: back-porting #1165 to support Visual Studio 2019
      ENH: updating remote modules
      COMP: fixed enum name error when legacy is OFF and ITK_USE_GPU is ON
      ENH: removing deprecated Python functionality: imp
      ENH: removing deprecated Python functionality: sys.version_info 2/3
      ENH: removing deprecated Python functionality: import print_function

Francois Budin @fbudin69500  (4):
      BUG: ImageBase regions and ImageRegion properties are returned as reference
      DOC: Add ITK 5.0 release notes
      BUG: m_NumberOfPointPixels was set equal to m_NumberOfPoints
      ENH: Adds swig include directory to command line

GDCM Upstream (1):
      GDCM 2019-05-22 (cc5358a1)

Genevieve Buckley @GenevieveBuckley (1):
      BUG: All exceptions must be derived from python's BaseException class

Hans J. Johnson @hjmjohnson (64):
      ENH: Update SphinxExamples to lastest master branch
      COMP: Add attribute for large doxygen config file.
      DOC: Remove ITK_FUTURE_LEGACY_REMOVE from documentation
      ENH: Disable remote module processing when creating doxygen.
      STYLE: Prevent double initialization
      DOC: Purge outdated media wiki WikiExamples
      BUG: Missed propagation of library dependancies
      ENH: Deprecate Neuralnetwork module
      Revert "Merge pull request #1039 from samuelgerber/MultithreadPointSetToPointSetMetricv4"
      STYLE: Remove deprecated support for ITK_WRAP_PYTHON_LEGACY
      DOC: Only warn when Module_NeuralNetworks is selected
      ENH: Use consistent project name with module name
      COMP: Fix clang-format nesting of empty macros
      DOC: Deprecate content.
      DOC: Provide doxygen links for sphinx
      DOC: Improve the documentation clarity for NormalizeImage.
      DOC: Moved wiki examples to sphinx examples part2
      ENH: itkObjectToObjectOptimizerBase Must be explicitly instantiated
      COMP: Terminate conditional doxygen sections
      DOC: Set class name for StreamingProcessObject doxygen
      ENH: Update the DoxygenLayout.xml file
      ENH: Update template files for Doxygen.
      BUG: Patch submission scripts conflict with doxygen
      COMP: Resolve 1000's of alias warnings in 1.8.15
      DOC: Moved wiki pages to sphinx examples
      BUG: Flawed logic for itkExceptionObject.h guards
      STYLE: Use override statements for C++11
      STYLE: Prefer c++11 'using' to 'typedef'
      COMP: Another work around uninitialized value warnings
      ENH: Prefer c++11 'using' to 'typedef' for structs
      COMP: Update AnalyzeObjectMapIO remote for ITKv5.0
      COMP: Suppress warning about file that is too large
      STYLE: Use = default for trivial constructors
      STYLE: For loops can have a space before ;
      STYLE: Suppress longstanding kwstyle violations
      STYLE: Use templated function over macro
      STYLE: Remove unused protected ivar m_MyProduct
      COMP: Isolate RAWIO non-templated code in cxx file
      PERF: Byteswap only when request != system byte order
      STYLE: Suppress longstanding kwstyle violations
      STYLE: Define the .clang-format config file
      ENH: Add script to assist with running clang-format on topic-branches
      ENH: Update C++/C attributes for itk style conformance.
      ENH: Add copy of git-clang-format from llvm binaries
      ENH: Add cmake configuration for clang-format
      ENH: Setup clang-format hooks for pre-commit-style
      DOC: Add missing line separator for ingroup ITKCommon
      DOC: Fix spelling typo VeriyInput -> VerifyInput
      ENH: Refactor to allow ReferenceHistogram instead of ReferenceImage
      COMP: Remove One Definition Rule conflict
      COMP: Fix missing type specialization for `unsigned long long int`
      STYLE: Convert 'enum' to 'enum class' objects with print enum function
      ENH: Workaround MSVC preprocessor name conflict
      STYLE: Prefer enum class definitions internally
      STYLE: Prefer consistent capitalization of Colormap
      ENH: Ignore wrapping warnings for `enum class`
      BUG: Missing ImageAdapter function signatures
      COMP: Change KWStyle to allow reformat to pass.
      STYLE: No-space inside <> () []
      STYLE: Change the packing of parameters.
      STYLE: Use shorter column length for Software Guide.
      STYLE: End of history preceeding clang-format-8.0 style
      STYLE: Fix spelling error foramt -> format

ITK Maintainer (1):
      STYLE: Enforce ITK style defined by .clang-format

James Butler @jamesobutler (1):
      COMP: Add cmake_minimum_required to ITKNumericsFEM

Jean-Christophe Fillion-Robin @jcfr (1):
      ENH: Support building ITKNumericsFEM as external module

Jon Haitz Legarreta Gorroño @jhlegarreta (4):
      STYLE: Fix indentation in bash script
      ENH: Add script to update ITK testing macros names
      BUG: Fix remotes maintenance scripts
      BUG: Fix wrong variable names

Matthew McCormick @thewtex (61):
      ENH: Bump the ITK CMake version to 5.1.0
      ENH: New content links for ITK 5.0.0
      STYLE: DeformableRegistration2 line length warnings
      COMP: SpatialObjectsHierarchy Software Guide newline
      ENH: Bump CI ExternalDataVersion to 5.0.0
      DOC: Release generation updates for ITK 5.0.0
      DOC: Add a note about updating conda-forge for post wheels
      ENH: Update Doxygen to 1.8.15
      BUG: Add test/CMakeLists.txt stub to NumPy bridge
      COMP: Provide NumericTraits<complex<T>>::ZeroValue() definition
      COMP: Backwards compatibility testing macros without ITK_ prefix
      BUG: Get latest tag in
      BUG: Filename vars in
      ENH: UpdateRequiredITKVersionInRemoteModules bump patch version
      ENH: UpdateRequiredITKVersionInRemoteModules supports ITKPythonGitTag
      BUG: Do not require PyBUF_WRITABLE in GetArrayViewFromImage
      DOC: Update supported Python versions warning
      ENH: Require Python 3.5 or newer on all platforms
      BUG: ITKFixedPointInverseDisplacementField wrapping test config update
      BUG: Remove VectorExpandImageFilter wrapping
      BUG: Add PEP 366 __package__ support to ITKLazyModule
      COMP: Remove HasNumericTraitsCheck from ExpandImageFilter
      ENH: Wrap ExpandImageFilter with vector types
      BUG: Release the Python Global Interpreter Lock (GIL) during execution
      STYLE: Apply ITK Style Guidelines to itkPyCommand.cxx
      BUG: itk::PyCommand ensures the GIL state
      BUG: Support pickling LazyITKModule with cloudpickle
      BUG: Add Pipeline name to Azure configuration
      DOC: Update Azure Pipelines badge URL's
      BUG: Add wrapping for TransformMeshFilter
      ENH: Bump itkVersion.cmake for 5.0.1
      ENH: CI testing uses Python 3
      BUG: itkPyBufferTest: use bytes for Python 3 np.frombuffer
      BUG: Remove NumberOfComponents check in _GetImageViewFromArray
      BUG: Remove NumberOfComponents check in _GetImageViewFromArray
      DOC: Update ITK.Linux.Python and ITK.Coverage README badges
      BUG: Update SkullStrip module to address Doxygen configuration
      BUG: Use ITK_BUILD_DOCUMENTATION to enable Doxygen builds
      COMP: Update CastXML to 2019-07-15 master
      DOC: Minor release documentation updates
      ENH: Support numpy.asarray for itk.Image
      ENH: Directly set an itk.ImageBase Direction with a NumPy Array
      BUG: Ensure NumPy array is C-contiguous with matrix conversion
      BUG: Enable ITKBridgeNumPy for Windows CI builds
      DOC: AdaptiveHistogramEqualizationImageFilter default radius
      BUG: Do not run itkPyBufferMemoryLeakTest on Windows
      BUG: Remove Windows Python 2.7 hypot workaround
      ENH: Support NumPy array-like inputs to image filters
      DOC: Add Eigen license to NOTICE file
      ENH: Download clang-format 8.0.1 executable
      ENH: Add wrapping for LabelImageGaussianInterpolateImageFunction
      DOC: 'weight' spelling in LabelImageGaussianInterpolateImageFunction
      BUG: Add NumPy conversion for itk.Image[itk.Vector[itk.D,dim]]
      BUG: Wrap WindowedSincInterpolateImageFunction SmartPointer
      BUG: Do not apply style pre-commit hooks to ThirdParty code
      BUG: Do not download clang-format with ITK_FORBID_DOWNLOADS enabled
      BUG: Add missing KWStyle hook configuration
      ENH: Update clang-format binary path configuration
      BUG: Fix have_KWStyle detection when running clang-format hook
      BUG: Improvements to pre-commit-style hook for clang-format
      ENH: Check for required clang-format version in style hook

MetaIO Maintainers (1):
      MetaIO 2019-05-22 (5f90075b)

Mihail Isakov (1):
      ENH: added missing symbols to JPEG mangling header

Neslisah Torosdagli @neslimsah (2):
      BUG: Regression in PolygonSpatialObject::IsInsideInObjectSpace #1082
      BUG: Regression in PolygonSpatialObject::IsInsideInObjectSpace #1082

Niels Dekker @N-Dekker (22):
      PERF: Replace mutex by atomic in MersenneTwisterRandomVariateGenerator
      STYLE: Remove two duplicated #include <mutex> directives
      STYLE: Add const to MersenneTwisterRandomVariateGenerator::GetSeed()
      ENH: GTest MersenneTwisterRandomVariateGenerator::GetIntegerVariate()
      STYLE: Use image->TransformPhysicalPointToIndex(point), returning index
      ENH: ImageBase Transform-Vector single argument overloads more generic
      STYLE: Use image->TransformVectorToVector(gradient), returning gradient
      STYLE: Vector, CovariantVector(value) call base FixedArray(value)
      STYLE: FastMarching replace FixedArray Begin(), End() by range-based for
      STYLE: Replace FixedArray Begin(), End() by cbegin(), cend()
      STYLE: itkFixedArray.hxx using std::equal, and C++11 fill_n and copy_n
      STYLE: Add const to SetStartingShrinkFactors parameter
      STYLE: Replace std::copy(input, input + n, output) by C++11 std::copy_n
      ENH: Add ImageRegionRange, to iterate over the pixels of an image region
      COMP: No longer disable obsolete MSVC warning C4231 on 'extern' template
      STYLE: Order #pragma warning directives in itkWin32Header.h
      COMP: No longer disable obsolete MSVC warning C4231 in VNL/vxl/vcl
      BUG: Fix possible loss of data on type conversion
      COMP: QuadEdgeMesh::SetCell avoid assignment in conditional expression
      COMP: Remove (char) casts of hexadecimal int literals from UnicodeIOTest
      COMP: ImageRegionRangeGTest issue #1147 Unused function template warning
      COMP: Fix loss of data ProcessObject GetNumberOfValidRequiredInputs()

Pablo Hernandez-Cerdan @phcerdan (1):
      BUG: Fix COMPILE_DEFINITIONS of castxml

Rinat Mukhometzianov @rmukh (3):
      COMP: MSVC AVX flag fix
      COMP: Fix SSE for MSVC x86
      COMP: Replace legacy ITK_Check...Flag.cmake with check_..._flag cmake function

Samuel Gerber @samuelgerber (7):
      PERF: Remove Temporary Variable in GetMeasurementVector
      ENH: Add Multithreading to PointSetToPointSetMetricv4
      ENH: Add Multithreading to PointSetToPointSetMetricv4
      ENH: Add Multithreading to PointSetToPointSetMetricv4
      Revert "Revert "Merge pull request #1039 from samuelgerber/MultithreadPointSetToPointSetMetricv4""
      BUG: Fix PointSetToPointSetMetric Thread Safety
      BUG: Fix CompositeTransform ThreadSafety

Stephen Aylward @aylward (17):
      ENH: Updated Spatial Object tex to match ITKv5
      BUG: Fixed spelling mistakes and use of plural member functions
      ENH: Updated Spatial Object tex to match ITKv5
      BUG: Fixed spelling mistakes and use of plural member functions
      BUG: Fix grammar and naming mistakes in SpatialObject documentation
      DOC: Fixed expected output of examples and documentation
      BUG: Fix grammar and naming mistakes in SpatialObject documentation
      DOC: Fixed expected output of examples and documentation
      BUG: Use AddPoint() for PointBasedSpatialObjects to set SO
      ENH: Replace ExceptionObjects with itkExceptionMacro.
      BUG: Use AddPoint() for PointBasedSpatialObjects to set SO
      ENH: Replace ExceptionObjects with itkExceptionMacro.
      ENH: Converted TubeSpatialObject ComputeTangentsAndNormals to frenet
      BUG: Resolve corner case bug in ComputeTangentsAndNormals in TubeSO
      ENH: Improved IsInside computation (speed and accuracy) of tube
      ENH: Updating TubeSO test to match assumption that default is EndRounded
      BUG: operator= defined in [tube|*]SpatialObjectPoint incomplete

Steve Pieper @pieper (1):
      DOC: ITK5 SpatialObject Scene to Group change

VXL Maintainers (1):
      VNL 2019-08-15 (7cc97a62)

Ziv Yaniv @zivy (1):
      DOC: Correcting some grammer and updating the toolkit name. (#980)

@maekclena (10):
      STYLE: Add ITK prefix to testing macros
      BUG: Fix BSplineGradient configuration
      ENH: Mark VectorExpandImageFilter as deprecated
      ENH: Deprecate VectorCentralDifferenceImageFilter
      ENH: Remove VectorExpandImageFilter when ITK_LEGACY_REMOVE is on
      BUG: add required method for Pickling
      BUG: Fix GaussianInterpolateImageFunction with streaming
      BUG: Avoid buffer overwriting in DCMTKImageIO
      ENH: Disable itkDCMTKImageIOMultiFrameImageTest
      BUG: Mitigate overflow in DCMTKImageIO::Read

@yjcchen0913 (1):
      BUG: Ensure strict weak ordering in HessianToObjectnessMeasure's sort


Very impressive, thanks for all your hard work!

When numpy arrays are used as inputs/output, are image spacing and axis directions preserved?


Not yet :wink: – we are working towards that with a NumPy-based spatial image.