SuperElastix/elastix

📦 Notes:

• When using the Windows binaries, you may need to install or update the appropriate Visual C++ redistributable on your machine (typically the one for X64): https://learn.microsoft.com/en-us/cpp/windows/latest-supported-vc-redist
• When you want to use the [IMPACT](https://github.com/vboussot/ImpactLoss) metric (that is, when you have the "Impact" metric as one of your registration parameters), you must have the run-time libraries of LibTorch 2.8.0 (from https://pytorch.org) in your library path, for elastix.

📦 Most important improvements of this release

• For Windows users: With this release, the executables (`elastix.exe` and `transformix.exe`) fully support Unicode (utf-8) file path names for registration parameter files and transform parameter files (pull request #1401). A big thank you to Bernhard Fröhler (@codeling)!
• The IMPACT metric component that was introduced with elastix 5.3.0 is now loaded as a plugin, by means of "lazy loading", allowing anyone to use it without having to rebuild elastix (pull request #1396). Another big thank you to Valentin Boussot (@vboussot)!
• For users of Linux and MacOS: The executables (`elastix` and `transformix`) now have a relative path to the directory of the third party library that we are using added to its `RPATH` (pull request #1404). So now it is no longer necessary for users to set their `LD_LIBRARY_PATH`. The extra versioned ".1" library files were removed (pull request #1416).
• A small performance improvement was achieved for the metrics (specifically "DistancePreservingRigidityPenalty" and "TransformRigidityPenalty") and two transforms ("BSplineTransformWithDiffusion" "MultiBSplineTransformWithNormal") (pull request #1410).
• Improved error handling for ParameterObject: it now throws an exception when the specified index or parameter name is not there (pull request #1420 and #1422).

📦 Merged pull requests

• #1401 ENH: use utf-8 via manifest on Windows by @codeling
• #1404 ENH: Add relative path to lib directory to RPATH on Linux and MacOS
• #1406 COMP: Replace MersenneTwister Initialize calls in tests with SetSeed
• #1408 COMP: Use GTest::gtest and GTest::gtest_main targets for ITK > v5.4.5
• #1409 Upgrade to Doxygen v1.16.1
• #1410 Avoid calling `ImageConstIterator::GetIndex()` iteratively, in transforms and metrics
• #1411 DOC: Exclude GTesting from Doxygen
• #1396 ENH: Lazy loading for optional components (IMPACT) by @vboussot
• + 11 more

📋 Changes

• Added a new metric component: IMPACT (Image Metric with Pretrained model-Agnostic Comparison for Transmodality registration), by Valentin Boussot (@vboussot) et al. (pull request #1311)
• Reference: "IMPACT : A Generic Semantic Loss for Multimodal Image Registration", Valentin Boussot, Cédric Hémon, Jean-Claude Nunes, Jason Dowling, Simon Rouzé, Caroline Lafond, Anaïs Barateau, Jean-Louis Dillenseger, [arXiv:2503.24121](https://arxiv.org/abs/2503.24121) – _Under review_
• In order to use this metric, download LibTorch and enable CMake option `USE_ImpactMetric`. More information: https://github.com/vboussot/ImpactLoss
• Supported the [TOML](https://toml.io) format for registration parameter files and transform parameter files (pull request #1288, #1289)
• As alternative to the "legacy" elastix specific text file format
• Supported fixed width notation for the elastix parameter `ResultImagePixelType` (pull request #1335)
• Supported parameter values: "int8", "int16", "int32", "int64", "uint8", "uint16", "uint32", "uint64", "float32", "float64"
• Supported registering a 3D slice on a 3D volume (pull request #1388)
• + 11 more

📦 Merged pull requests:

• #1204 BUG: Replace Doxygen "Modules" with "Topics"
• #1206 Append "Flat" to "OriginalFixedImage/fixedImageOriginal" Direction identifiers, replace some `this->`
• #1210 STYLE: Remove warning when UseDirectionCosines is unspecified
• #1211 DOC: Fix documentation about order of matrix elements Rigid3DTransform
• #1212 Declare AdvancedBSplineDeformableTransform data members as C-style array, remove `this->`
• #1213 Remove ValidRegion properties from BSpline Transforms
• #1214 Simplify offset estimations for `AdvancedBSplineDeformableTransform::SetGridRegion`
• #1208 Add notes on the order of matrix elements of `Direction` and `GridDirection` parameters
• + 149 more

✨ New Contributors

• #1242 @Sager611 made their first contribution
• #1344 @vboussot made their first contribution
• Full Changelog: https://github.com/SuperElastix/elastix/compare/5.2.0...5.3.0

📦 Enhancements

• 8111c672508d89995550e63ba54ab871e324105b Added support for the "ComputeZYX" parameter to EulerStackTransform (for a 4D stack of 3D images).
• 76fa510cea569cfefe134ece34a86a381a338545 Added "UseMultiThreadingForSamplers" parameter for sampling (default "true").
• 05d2b40f23d5b1c1438521e505e349bb54fdf7e4 Support "ShowProgressPercentage" parameter (`false` by default).
• c90f1c45d0c45c0f13e015af205f88b1316c05f0 Added "-loglevel" command-line option to elastix and transformix exe (possible values: "off", "error", "warning", or "info")

📦 Library specific enhancements

• 23ef4329e25e0751ebf26ba59d8c85c539f13f80 Avoided irrelevant log messages saying "-fMask unspecified" or "-mMask unspecified".
• 9d76b86f955043e2ae17bbbd621aaa5f0f60e001 Added support for `ELASTIX_BUILD_EXECUTABLE`, allowing to switch off building the elastix and transformix executables, while still building the libraries.
• 5c450b6b41bfd4ffb80a87dacbf5ed5d968d64f2 `elastix::ParameterObject::WriteParameterFile` now writes floating point numbers without rounding errors
• 71a4a9ae60e63c1a81337810c5170c317ff82923 Added `SetTransformParameterFileName(string)` and `GetTransformParameterFileName()` to `itk::TransformixFilter`
• 9e64269bb40f9275015d557263acf1f382436087 Let `itk::ElastixRegistrationMethod` write the transform maps from its InitialTransformParameterObject to the output directory.
• 48c64583c8514eac7fa9ad46848be9d100ac80c9 Added `SetInitialTransformParameterObject(parameterObject)` to `itk::ElastixRegistrationMethod`
• 115d8e1c7b0b23973bfc919a2bf4768f32e4e843 Added `SetInitialTransform(transform)` to `itk::ElastixRegistrationMethod`

⚡ Performance

• The internal `ComputeImageExtremaFilter` has been made up to 6x as fast (pull request #1046), significantly improving the performance of metric components
• Full Sampler and Grid Sampler have been made ~3x as fast, when the input image and the mask have the same domain (geometry)
• 3x as fast
• Grid Sampler is made multithreaded
• Grid Sampler is using memory more efficiently (by doing `sampleVector.reserve`), making the sampling twice as fast (on the use case of sampling without mask)
• Samplers have multithreading enabled by default. Affects Full, Random, RandomCoordinate, and RandomSamplerSparseMask samplers.
• Speed up full, grid, sparse mask samplers by using a local sampleVector variable. (May make sampling almost twice as fast.)
• Internal function calls of the form `mask->IsInsideInWorldSpace(point)` have become twice as fast, improving both metrics and samplers.
• + 1 more

🐛 Bug Fixes

• e3cafc5c1cd5d1eda4736984c3d3050d9353cc6f Fixed support of specifying the number of threads in the thread pool ("-threads" _N_ command-line argument).
• d1e52fc3a269057f6d6116bcdfd7e504c7ded3ee Fixed a small memory leak in ParabolicErodeDilateImageFilter, affecting the use of "ErodeMask".
• 60d3712ff7d4ffc98b5e53a67124b56a05e5fe46 Fixed support SumOfPairwiseCorrelationCoefficients metric for use cases without stack transform.
• 76ede5d8c444978c1be54c2fb6dac4cfe89cddbd Added missing ComputeZYX property to FixedParameters of Euler Transform for 3D, to ensure that ComputeZYX is properly stored and retrieved.
• 33c3873d3371f4a9c99f08b0c6bd8ea551752ca3, 34bdc3ba92ff5a9854b7b6e9b4b4459766b192d5 Fixed overrides of PowellOptimizer, FRPROptimizer. Relevant when using the "ConjugateGradientFRPR" optimizer.
• bc1ddf084aa07b3ca0d17f3a81f69cedcccdfa58 Let ParabolicErodeDilateImageFilter::SplitRequestedRegion override ITK's ImageSource, affecting the use of "ErodeMask".
• f5b9024458ee11f13349405874135612c80013e5 ImageFullSampler do mask updates single-threaded, to avoid race conditions.
• a53d49de76c68e29c3cbbd7ea976b7b3bc3f2889 ComputeImageExtremaFilter SameGeometry function include Index, Spacing, and Direction, fixing issue #1023.
• + 6 more

📦 Under the hood

• Upgraded from C++14 to C++17, and modernized the code using language and library features that were introduced by C++17.
• Upgraded from ITK 5.3.0 to [ITK 5.4.0](https://github.com/InsightSoftwareConsortium/ITK/releases/tag/v5.4.0).
• Added 54 GoogleTest unit tests (total: 153 GoogleTest unit tests).

📦 Contributors

• This release has commits by: Niels Dekker, Konstantinos Ntatsis, Marius Staring, and Matt McCormick. Stefan Klein was also very much involved with this release.
• Full Changelog A list of all commits for this release: https://github.com/SuperElastix/elastix/compare/5.1.0...5.2.0

📦 ITK transform file formats: HDF5 and TFM

• ```
• (Transform "File")
• (TransformFileName "ITK-HDF5-Transform.h5")
• ```
• Supported ITK Transform types: Translation, Affine, Euler (2D and 3D), Similarity (2D and 3D), and BSpline.

📦 Other input parameter support enhancements

• The `"AutomaticScalesEstimation"` parameter is now also supported by _AffineLogStackTransform_ and _EulerStackTransform_, addressing issue https://github.com/SuperElastix/elastix/issues/260

📦 Format adjustments to elastix output transform parameter files

• Added 32-bit floating point ("float") pixel type to 4-D image support: pull request https://github.com/SuperElastix/elastix/pull/418
• Added git revision information to command-line output, addressing issue https://github.com/SuperElastix/elastix/issues/671 submitted by Sebastian van der Voort (@Svdvoort)

📦 Library specific extensions (ITKElastix/SimpleITK interface)

• Added _DisableOutput()_ to `itk::ElastixRegistrationMethod` and `itk::TransformixFilter` (especially to ease writing multi-threading applications)

📦 Under the hood

• Upgraded from C++11 to C++14, and modernized the code using language and library features that were introduced by C++14.
• Upgraded from ITK 5.1.1 to [ITK 5.3.0](https://github.com/InsightSoftwareConsortium/ITK/releases/tag/v5.3.0).
• Added 91 GoogleTest unit tests and 18 Python unit tests.

📦 Contributors

• Full Changelog A list of all commits for this release: https://github.com/SuperElastix/elastix/compare/5.0.1...5.1.0

📦 Enhancements ##

• `elastix` has migrated from ITK version 5.0.1 to [ITK version 5.1.1](https://github.com/InsightSoftwareConsortium/ITK/releases/tag/v5.1.1). `elastix` does not build anymore with earlier versions of ITK. This new ITK version fixes an important issue regarding the use of mask images during registration, https://github.com/InsightSoftwareConsortium/ITK/issues/1950 reported by Theo van Walsum (@tvanwalsum, Erasmus MC, Rotterdam) at [Google Groups - elastix-imageregistration - Issues with mask in el 5.0.0 when mask extent is smaller then image extent](https://groups.google.com/forum/#!category-topic/elastix-imageregistration/elastix/lSLWJq9Zcgk).
• The minimum required CMake version was increased from CMake 2.8 to CMake 3.10.2 (which is also required for ITK 5.1.1).
• Various coding style improvements, including improved const correctness of `ELASTIX::RegisterImages`, and a few issues found by Visual Studio Code Analysis and Clang Tidy.

📦 Contributors ##

• This release has commits by (in alphabetic order): Andras Lasso, Andrey Saenko, Colin Sullender, Kasper Marstal, Marius Staring, Matt McCormick, Niels Dekker, Stefan Klein

📦 Enhancements ##

• `elastix` has migrated to the recent ITK version 5.0.1! [ITK5](https://github.com/InsightSoftwareConsortium/ITK/releases/tag/v5.0.0) is a major new release featuring among others a move to GitHub, switching to C++11, thread pools, and a new spatial object implementation. These modifications have quite some impact on `elastix`, and we decided to adopt them. In order to do so, quite a number of modifications were directly [integrated and contributed to the ITK](https://github.com/InsightSoftwareConsortium/ITK/commits/v5.0.0?author=N-Dekker). Long story short, `elastix 5.0.0` can now be build with the latest release of ITK (v5.0.1), using the CMake flag `ITK_LEGACY_REMOVE ON`. `elastix` does not build anymore with earlier versions of ITK.
• We have migrated to the new `SpatialObject` implementation of ITK. This was quite involved, as the masks used in `elastix` are actually spatial objects, and are used throughout.
• We have started to use new C++11 language features, such as the use of `nullptr`, switched to using new Standard C++ Library functions, using the `override` keyword, and removal of the `register` keyword and dynamic exception specifications. This also means that we have dropped support for compilers that do not support these new features.
• We have added the command line option `--extended-version` that additionally gives version information about the toolchain that we use.
• We started using GoogleTest for unit testing, complementary to the existing elastix registration tests.

✨ New classes and methods ##

• A number of new optimization methods were introduced: `AdaGrad`, `AdaptiveStochasticLBFGS`, `AdaptiveStochasticVarianceReducedGradient` (experimental), `PreconditionedGradientDescent` and `PreconditionedStochasticGradientDescent`. They can be selected via:
• ```
• (Optimizer "PreconditionedStochasticGradientDescent")
• ```

🐛 Bug fixes ##

• We [fixed](https://github.com/SuperElastix/elastix/commit/4ac0e94f20b99498f53814c65f455388a8f10ed9) an overflow issue in the samplers, that occurred in case of really large images.
• 'elastix 4.9.0' [suffered from a performance regression](https://github.com/SuperElastix/elastix/issues/89), which was targeted down to the ITK library. The timer that we used (an `itk::ResourceProbe`) had some serious overhead introduced in ITK 4.9. We [fixed it](https://github.com/InsightSoftwareConsortium/ITK/commit/b13f6a86cb250328f0c185f509649b370bbe49f4) in the ITK directly.
• We [fixed](https://github.com/SuperElastix/elastix/commit/6925e6a8bd6d6d7c8560598ebb5b594ee9be4256) a bug in the library interface (`TransformixFilter`): it was not propagating direction information.

📦 Contributors ##

• This release has commits by (in alphabetic order): Floris Berendsen, Niels Dekker, Stefan Klein, Kasper Marstal, Matt McCormick, Csaba Pinter, Denis P. Shamonin, Marius Staring, Harmen Stoppels

📦 Enhancements ##

• The library interface of `elastix` has been completely redesigned! It now consists of an ITK filter that can be used in ITK pipelines together with other filters. The new library interface is currently used in [SimpleElastix](https://simpleelastix.github.io/). You can read more about the design in the [SimpleElastix paper](http://simpleelastix.github.io/assets/pdf/SimpleElastixWBIR2016.pdf). Transformix got a corresponding ITK filter. Support for a user-supplied initial transform was added by [Bartolomejka](https://github.com/Bartolomejka).
• CUDA support was removed from `elastix`.
• The OpenCL implementation that was included in the previous release is much more mature and supports much more use cases.
• For the OpenCL accelerations it is now possible to select the GPU in the parameter file.
• This can be done using the option `(OpenCLDeviceID "<x>")`
• Multi-threading was added to the displacement distribution code, which is part of the ASGD optimizer.
• We added an option to compute the exact metric value every few iterations, which is nice for evaluation purposes.
• The testing framework was made independent of external libraries. Travis CI and AppVeyor were added as Continuous Integration services. Thank you [Andrey Fedorov](https://github.com/fedorov)!

✨ New classes and/or methods ##

• There is a new and faster implementation of the B-spline transform.
• This transform can be selected using:
• ```
• (Transform "RecursiveBSplineTransform")
• ```
• This transform gives exactly the same results as the original B-spline transform, but is at least twice as fast. It is the new recommended nonrigid transformation.
• Preliminary results were published via [Huizinga et al., _Fast Multidimensional B-spline Interpolation Using Template Metaprogramming_, 2014](https://doi.org/10.1007/978-3-319-08554-8_2).
• A number of classes for PCA-based groupwise image registration.
• + 5 more

🐛 Bugs ##

• There was a remnant of the old elxTimer classes still in the library interface code. This was removed.
• There were some fixes in the xout logging library, related to memory leaks when instantiating multiple `elastix` libraries.
• A memory leak due to a smart pointer cycle was fixed by [Coert Metz](https://github.com/coertmetz).
• Certain B-spline kernels used for interpolation had a small implementation mistake.
• [Steve Robbins](http://www.sumost.ca/steve/) performed a long list of cleanups, addressing Valgrind errors, testing and dashboard setup, library definition, and installation. Thank you Steve!