Support of ITK 5.0 in OTB

Summary

Support of ITK 5.0 in OTB

Major improvements in ITK 5.0 include a switch to C++11 language standard, improved performance, and cleanup of legacy code. More information about the C++11 transition, spearheaded by Hans Johnson, can be read in the ITK 5.0 Alpha 1 announcement.(Forum, ITK 5.0 Alpha 1).

ITK 5.0 Alpha 2 emphasizes performance improvements:

• A refactored multithreading infrastructure;
• A thread pool is available by default;
• An Intel Threading Building Blocks (TBB) threading backend with dynamic region splitting;
• Improved image iterator performance;
• Simple APIs to execute functions in parallel;
• Simple construction of unary and binary generator image filters;
• New, experimental C++11 range classes for iteration in range-based for loops.
• cmake minimum version required is 3.10.2

Rationale

A major release of ITK is coming soon. As with any other major release there are significant changes and advancement in API. ITK being the foundation on which OTB is built, it is important to update our code base to adopt these changes. Key points of this release are mentioned in their announcement on discourse forum. This release brings dramatic improvements to ITK’s API and performance.

Prior to ITK 5.0, only a subset of C+11 functionality was used, when available, through backports and macros. ITK now requires a C+11 standard compiler. And this get rid of lot of macros. Move to C++11 does not affect OTB since it has already moved to a higher standard (C++14).

Another important API change in ITK is its threading model. This affects OTB , Remote Modules and projects depending on OTB (both official and unofficial) in large scale. This merge request approaches threading model issues between ITK 5.0 and OTB. We had observed a 99% of passing test with our changeset while not breaking compatibility with ITK 4.x.

This MR does not fully cover compatibility yet. There can be classes of filters that are not covered by testing and hence remain un-patched.

Until debian-testing, OpenSUSE, ubuntu and many others pick up the yet-to-release ITK 5.0, it is important to keep support of ITK 4.x. Even though binary packages and superbuild can use alpha version but still a compatibility layer is necessary.

Implementation Details

DynamicMultiThreadingOff method is a newly added feature in ITK5.0. This has been written to keep compatibility with 4.x and 5.x version of ITK. In OTB we have to make extensive use of this macro. According to ITK documentation, a call to this->DynamicMultiThreadingOff() in constructor is needed if any of the following is true:

• Your filter needs a constant, in-advance known number of threads
• Your filter uses threadId parameter in ThreadedGenerateData()
• Your filter uses a custom region splitting method

Hence we introduce a new macro called OTB_DISABLE_DYNAMIC_MT. details of this macro are given below.

OTB_DISABLE_DYNAMIC_MT

This macro is defined in otbMacro.h which expands to this->DynamicMultiThreadingOff() if ITK_MAJOR_VERSION < 5 or empty otherwise.

See code snippet from header:

#if ITK_VERSION_MAJOR < 5
#define OTB_DISABLE_DYNAMIC_MT
#else
#define OTB_DISABLE_DYNAMIC_MT this->DynamicMultiThreadingOff();
#endif

There are cases where we have to include otbMacro.h only for using OTB_DISABLE_DYNAMIC_MT. We had documented such #include lines with proper comment so that one can remove them when OTB drops support of ITK 4.x or even remove this macro from source tree.

Classes and files

All important change and corresponding impacted files are listed below.

OTB_DISABLE_DYNAMIC_MT

• Modules/Core/Common/include/otbFunctionToImageFilter.txx
• Modules/Core/Common/include/otbUnaryFunctorNeighborhoodVectorImageFilter.txx
• ...
• ...
• As you can imagine the list is quite long : a total of 109 files!
• ...
• ...
• Modules/Segmentation/Labelling/include/otbLabelToBoundaryImageFilter.h
• Modules/Segmentation/MorphologicalProfiles/include/otbMultiScaleConvexOrConcaveClassificationFilter.h

itk::Offset<2>::LexicographicCompare

ITK 4.x had a typedef for LexicographicCompare in itk::Offset class. This has been removed in ITK 5.0. It provides alternatives for LexicographicCompare through itk::Functor::LexicographicCompare<OffsetType>. This functor is defined in itkLexicographicCompare.h header.

The following two files have been affected by this change for now.

Modules/Core/LabelMap/include/otbShapeAttributesLabelMapFilter.h
Modules/Core/LabelMap/include/otbShapeAttributesLabelMapFilter.txx

A sample change is given below.

-  typedef std::map<Offset2Type, itk::SizeValueType, Offset2Type::LexicographicCompare> MapIntercept2Type;
+  typedef itk::Functor::LexicographicCompare<Offset2Type>                         LexicographicCompare2;
+  typedef std::map<Offset2Type, itk::SizeValueType, LexicographicCompare2> MapIntercept2Type;

MultiThreader class

Since ITK 5.0 MultiThreader has been split into a class hierarchy. MultiThreader class is marked legacy and will not be available if legacy is set to OFF. PlatformMultiThreader must be used if filter is using SpawnThread/TerminateThread. itkMultiThreaderBase.h add MultiThreader as alias for MultiThreaderBase class. This force one to explicitly include itkMultiThreader.h in classes where itk::MultiThreader namespace is used.

Modules/IO/Carto/include/otbCoordinateToName.h
Modules/IO/Carto/src/otbCoordinateToName.cxx
Modules/Learning/Sampling/include/otbPersistentSamplingFilterBase.txx
Modules/Core/PointSet/include/otbImageToPointSetFilter.txx

Modules/ThirdParty/ITK/include/

This module contains patched version of ITK headers that are not pushed to ITK but are important for proper function of OTB. We cannot use OTB_DISABLE_DYNAMIC_MT macro in these files as it will add a dependency to OTBCommon. Hence we are forced to duplicate our macro code in these two headers.

Modules/ThirdParty/ITK/include/itkTransformToDisplacementFieldSource.hxx
Modules/ThirdParty/ITK/include/itkUnaryFunctorImageFilter.hxx

Modules removed in ITK 5.0

Some modules were moved to remote modules group in ITK 5.0. Among them is ITKNeuralNetworks which is a required module for OTB. Luckily this module wasn't used for any purpose, so we skip it when finding ITK 5.0. Changes are contained in Modules/ThirdParty/ITK/otb-module-init.cmake

Tests

A lot of tests have been affected by the move to ITK 5.0. With this merge request we have observed 99% tests passed. List of failing test from latest build (locally) are given below.

The following tests FAILED:

	354 - apTvDmBlockMatchingTest (Failed)
	698 - dmTvSubPixelDisparityImageFilterNCC (Failed)
	1395 - bfTvStreamingResampleImageFilterCompareWithITK (Failed)
	1775 - msTvMorphoPyrMRToMSConverter (Failed)
	2756 - siTvHyperspectralExampleTest (Failed)
	2783 - msTeMorphologicalPyramidAnalysisFilterExampleTest (Failed)
	2803 - reTeImageRegistration2ExampleTest (Failed)

All these tests are failing due to baseline differences. See attached output of ctest -VV below

Documentation

ITK v5 migration guide for OTB. This is to help external projects using OTB. Key points in migration guide are:

• using dynamic multi-threading macro,
• including itkMultiThreader header when using itk::MultiThreaderBase class
• using/changing to itkLexicographicalCompare

Additional notes

• This will add support of ITK 5.0 but will not benefit from ITK's new dynamic multi-threading capabilities.
• For that we had to break support of ITK 4.x and make ITK 5.x or later as required version for OTB. Such a change can be addressed in separate merge request(s).
• ITK must be built with ITK_LEGACY_REMOVE enabled. This is currently the case for ITK 4.x . Changing ITK_LEGACY_REMOVE has a whole new level of impact on OTB code as it removes a lot of deprecated features.
• Superbuild modification is trivial and is excluded from this merge request. It can be updated when this branch is tested on dashboard.
• SWIG minimum required version is 3.0

Copyright

The copyright owner is CS Systemes d'Information (CS SI) and we had signed the ORFEO ToolBox Contributor License Agreement.

---

Check before merging:

• All discussions are resolved
• At least 2 👍 votes from core developers, no 👎 vote.
• The feature branch is (reasonably) up-to-date with the base branch
• Dashboard is green
• Copyright owner has signed the ORFEO ToolBox Contributor License Agreement