Debian Codegraph @

Documentation/docs/migration_guides/itk_5_migration_guide.md

raw
1 ITK v5 Migration Guide
2 ======================
3
4 This guide documents the changes required to migrate a code base
5 which uses ITK v4 to use ITK v5. The migration guide for transition
6 from v3 to v4 can be found [here](https://itk.org/migrationv4/).
7
8 Legacy code removed
9 -------------------
10
11 All code which was marked as legacy in ITK 4.13 has been removed.
12 External code which previously required
13 `ITK_LEGACY_REMOVE` CMake option to be `OFF` in order to build will now fail
14 to compile. Before starting migration to v5 (as explained in this guide),
15 migration to v4 should be finished. Dependent code should build and pass tests
16 with `ITK_LEGACY_REMOVE` turned `ON` when compiling against
17 [ITK v4.13](https://github.com/InsightSoftwareConsortium/ITK/releases/tag/v4.13.1).
18
19 Code which was marked as `ITK_FUTURE_LEGACY_REMOVE` has been now
20 re-flagged as `ITK_LEGACY_REMOVE`. There have been some other
21 deprecations and API changes. The new behavior is activated by setting
22 `ITK_LEGACY_REMOVE` to `ON`. By default, compatibility with v4 is retained
23 (`ITK_LEGACY_REMOVE=OFF`).
24
25 The first step is to get the external code building against ITK compiled with
26 `ITKV4_COMPATIBILITY` set to `ON`. Once that is accomplished, turn this
27 option `OFF`. It is `OFF` by default.
28
29 Once external code builds successfully with the default configuration
30 (`ITKV4_COMPATIBILITY` and `ITK_LEGACY_REMOVE` both `OFF`),
31 `ITK_LEGACY_REMOVE` should be set to `ON`. Possible additional build errors
32 and/or warnings should be addressed. Once dependent code builds and passes
33 tests without legacy options, migration to v5 is complete.
34
35 Support for for pre-20160229 `VXL_VERSION_DATE_FULL` system installed
36 versions of VXL has been removed. VXL now supports more common Semantic Versioning
37 conventions with the minimum supported version for ITKv5 being 2.0.2 (as of 2018-11-30).
38
39 C++11
40 -----
41
42 A major improvement in ITK 5 is to fully adopt C++11.
43 Prior to ITK 5, a limited subset of C++11 functionalities were available in ITK
44 through back-ports and macros. This functionality was enabled when ITK was built with the C++11 standard enabled.
45 ITK 5.0.0 deprecates or removes these macros (e.g. `ITK_NULLPTR`, `ITK_DELETED_FUNCTION`,
46 `ITK_NOEXCEPT`, `ITK_CONSTEXPR`) and directly uses C++11 keywords such as
47 [delete](https://github.com/InsightSoftwareConsortium/ITK/commit/02128abbd0bf790deadc86a28c62c4a25e23518b),
48 [constexpr](https://github.com/InsightSoftwareConsortium/ITK/commit/b8e41d0d1652a8f6ddb84328faef67b207e77430),
49 [nullptr](https://github.com/InsightSoftwareConsortium/ITK/commit/3c6372b80ac2900e2e197899989c4cd151f1695f),
50 [override](https://github.com/InsightSoftwareConsortium/ITK/commit/3ceacc0ad4ec699b094d96e23d33f9467c2a63c6),
51 [noexcept](https://github.com/InsightSoftwareConsortium/ITK/commit/af4f65519abb32b59cebb2d72f0186a96efe3b4e).
52 The keywords [auto](https://github.com/InsightSoftwareConsortium/ITK/commit/de713e7ac52f7815a35754de885795ff0a1c4981)
53 and `using` [[1](https://github.com/InsightSoftwareConsortium/ITK/commit/66e5d6b3bcc28f1a85b702086b6cedc8cab6723b),
54 [2](https://github.com/InsightSoftwareConsortium/ITK/commit/f21c1d27025575167ea9194214aa5bf17a0a5495)]
55 as well as [range-based loops](https://github.com/InsightSoftwareConsortium/ITK/commit/48daed0751df99bcb5fd1077e78ceb1b47546ccc)
56 are also now used in ITK. As a consequence, due to limitations in C++11 support
57 Visual Studio 2013 (MSVC 12.0) and other older C++ complilers cannot be used to build ITK from 5.0 and forward.
58
59 Errors similar to `error: conversion from 'int' to 'typename InterpolatorType::Pointer'` are a result of further
60 type safety for dealing with pointers. Enhancements in nullptr behavior in ITKv5 provide more clear
61 type checking and respect the nullptr identifier. The 'long 0' value
62 known as NULL causes an ambiguity for overload compilations of the ITKv5 smartpointers. To be backwards compatible
63 with pre C++11 compilers use the `ITK_NULLPTR` designation, otherwise replace NULL and 0 initialization of
64 `itk::SmartPointer` with nullptr.
65
66
67
68 Availability of the C++11 standard allows use of many Standard Library
69 features. These were previously implemented as portable ITK classes.
70 The standard library classes are preferred over ITK's implementations.
71 The most notable examples of this are:
72 * [atomic integers](https://docs.itk.org/projects/doxygen/en/v4.13.0/classitk_1_1AtomicInt.html) should be replaced by `std::atomic`.
73 * [mutex locks](https://docs.itk.org/projects/doxygen/en/v4.13.0/classitk_1_1MutexLock.html)
74 and related classes should be replaced by the similarly named classes from STL's
75 [`<mutex>`](https://en.cppreference.com/w/cpp/header/mutex) header.
76 * `itksys::hash_map` should be replaced by [std::unordered_map](https://en.cppreference.com/w/cpp/container/unordered_map).
77
78 To modernize your code base, replace:
79 * `SimpleFastMutexLock` with `std::mutex`, and `#include "itkSimpleFastMutexLock.h"` with `#include <mutex>`.
80 * `FastMutexLock` with `std::mutex`, and `#include "itkFastMutexLock.h"` with `#include <mutex>`.
81 * `MutexLock` with `std::mutex`, and `#include "itkMutexLock.h"` with `#include <mutex>`.
82 * `mpl::EnableIf<X>::Type` with `std::enable_if_t<X>`, and `#include "itkEnableIf.h"` with `#include <type_traits>`.
83 * `mpl::IsSame<X, Y>::Value` with `std::is_same<X, Y>::value`, and `#include "itkIsSame.h"` with `#include <type_traits>`.
84 * `mpl::IsBaseOf<X, Y>::Value` with `std::is_base_of<X, Y>::value`, and `#include "itkIsBaseOf.h"` with `#include <type_traits>`.
85 * `mpl::IsConvertible<X, Y>::Value` with `std::is_convertible<X, Y>::value`, and `#include "itkIsBaseOf.h"` with `#include <type_traits>`.
86
87
88 Modern CMake requirement
89 ------------------------
90
91 ITK now requires **CMake 3.10.2** for configuration. While only a few features
92 enabled by this modern version of CMake are being used for 5.0 release, a
93 modern version of CMake is a prerequisite for future more aggressive updates
94 to ITK's build system. This is planned for a later version.
95
96 Before making other changes suggested in this document,
97 your code should work with the latest version of CMake.
98
99 Updated style
100 -------------
101
102 Important changes in style have also been integrated in ITK to match
103 C++11 best practices. This includes replacing `typedef` calls with
104 the keyword `using`, the usage of the keyword `auto` when appropriate,
105 and moving the macros `ITK_DISALLOW_COPY_AND_ASSIGN` or `ITK_DISALLOW_COPY_AND_MOVE` from the private
106 class section to the public class section. The ITK Software Guide has
107 been updated to match these changes.
108
109 Multithreading refactored
110 -------------------------
111
112 Since ITK 5.0 `itk::MultiThreader` has been split into a class hierarchy.
113 Instead of a single `itk::MultiThreader` class which could optionally delegate work
114 to an [itk::ThreadPool](https://itk.org/Insight/Doxygen/html/classitk_1_1ThreadPool.html),
115 there are now multiple backends to provide thread-based parallel processing.
116 Most of the time you will want to replace `itk::MultiThreader` by
117 [itk::MultiThreaderBase](https://itk.org/Insight/Doxygen/html/classitk_1_1MultiThreaderBase.html).
118
119 [PlatformMultiThreader](https://itk.org/Insight/Doxygen/html/itkPlatformMultiThreader_8h.html)
120 is essentially the old `itk::MultiThreader`, renamed. `itk::PoolMultiThreader` behaves like
121 the old `itk::MultiThreader` with `ITK_USE_THREADPOOL=ON`. There is an addition of
122 [TBBMultiThreader](https://itk.org/Insight/Doxygen/html/classitk_1_1TBBMultiThreader.html),
123 which uses Intel Thread Building Blocks library's thread-pool, with has load balancing features.
124 The option to build TBB support must be enabled during the CMake configuration step.
125 The default multi-threader can be set via environment variable
126 `ITK_GLOBAL_DEFAULT_THREADER` with possible case-insensitive values of
127 `Platform`, `Pool` and `TBB`, e.g. `ITK_GLOBAL_DEFAULT_THREADER=tbb`.
128
129 For filter multi-threading, a new signature has been introduced:
130 `void DynamicThreadedGenerateData( const OutputRegionType& threadRegion )`.
131 By default, this new signature is invoked instead of the classic
132 `void ThreadedGenerateData( const OutputRegionType& threadRegion, ThreadIdType threadId )`.
133 To temporarily obtain the old behavior (classic signature invoked by default),
134 set `ITKV4_COMPATIBILITY` to `ON` in ITK's CMake configuration.
135 To permanently have your filter use the classic threading model,
136 invoke `this->DynamicMultiThreadingOff();` in the filter constructor.
137 That is required if any of the following is true:
138 * Your filter needs a constant number of threads (known in advance)
139 * Your filter uses `threadId` parameter in `ThreadedGenerateData()`
140 * Your filter uses a custom region splitting method
141
142 Additionally, replace `itk::MultiThreader` by `itk::PlatformMultiThreader`
143 if any of the following is true:
144 * Your filter uses cross-thread synchronization e.g. `itk::Barrier`
145 * Your filter uses `MultipleMethodExecute()`
146 * Your filter uses `SpawnThread`/`TerminateThread`
147
148 It is strongly advised to not explicitly use `itk::PlatformMultiThreader`.
149 `SpawnThread`/`TerminateThread` and `MultipleMethodExecute` can be
150 replaced by C++11 `std::thread`. Code in the example below shows
151 how to remove dependence on barrier by using ParallelizeImageRegion.
152
153 - Pattern for Multiple Parallel Operations:
154 ```cpp
155 ThreadedGenerateData()
156 {
157 // code1 (parallel)
158 myBarrier->Wait();
159 if (threadId == 0)
160 {
161 // code2 single-threaded
162 }
163 // code3 (parallel)
164 }
165 ```
166
167 after refactoring to not use barrier:
168 ```cpp
169 GenerateData() // Not Threaded
170 {
171 this->AllocateOutputs();
172 this->BeforeThreadedGenerateData();
173 ParallelizeImageRegion(code1 as lambda)
174 // code2 single-threaded
175 ParallelizeImageRegion(code3 as lambda)
176 this->AfterThreadedGenerateData();
177 }
178 ```
179
180 - ITK_THREAD_RETURN_TYPE is now in the itk:: namespace
181 ```cpp
182 #if ITK_VERSION_MAJOR >= 5
183 static itk::ITK_THREAD_RETURN_TYPE NetworkingThreaderCallback( void * );
184 #else
185 static ITK_THREAD_RETURN_TYPE NetworkingThreaderCallback( void * );
186 #endif
187 ```
188
189 - ITK_THREAD_RETURN_VALUE is named itk::ITK_THREAD_RETURN_DEFAULT_VALUE
190 ```cpp
191 #if ITK_VERSION_MAJOR >= 5
192 return itk::ITK_THREAD_RETURN_DEFAULT_VALUE;
193 #else
194 return ITK_THREAD_RETURN_VALUE;
195 #endif
196 ```
197
198 - ThreadInfoStruct is renamed to WorkUnitInfo
199 ```cpp
200 #if ITK_VERSION_MAJOR >= 5
201 (((itk::PlatformMultiThreader::WorkUnitInfo *)(arg))->UserData);
202 #else
203 (((itk::MultiThreader::ThreadInfoStruct *)(arg))->UserData);
204 #endif
205 ```
206
207 - Pattern for Parallel Counting:
208 Previously parallel counting was often storing per-thread counts in an `itk::Array`
209 and aggregating the result in a filter's `AfterThreadedGenerateData()`.
210 With C++11, you might want to instead use `std::atomic`.
211 An external module example that demonstrates this can be found in
212 [this commit](https://github.com/InsightSoftwareConsortium/ITKBoneMorphometry/pull/32/commits/a8014c186ac53837362a0cb9db46ae224b8e9584).
213
214 Before, using `itk::Array`:
215 ```cpp
216 // Members:
217 Array<SizeValueType> m_NumVoxelsInsideMask;
218 BeforeThreadedGenerateData()
219 {
220 // Resize the thread temporaries
221 m_NumVoxelsInsideMask.SetSize(this->GetNumberOfThreads());
222 m_NumVoxelsInsideMask.Fill(0);
223 }
224
225 ThreadedGenerateData(const RegionType & outputRegionForThread, ThreadIdType threadId)
226 {
227 // Do algorithm per threadId
228 // Store the results per thread at the end
229 m_NumVoxelsInsideMask[threadId] = numVoxelsForThisRegion;
230 }
231
232 AfterThreadedGenerateData()
233 {
234 // Retrieve and sum all the results per thread.
235 ThreadIdType numberOfThreads = this->GetNumberOfThreads();
236 SizeValueType numVoxelsInsideMask = 0;
237 for (unsigned int i = 0; i < numberOfThreads; ++i)
238 {
239 numVoxelsInsideMask += m_NumVoxelsInsideMask[i];
240 }
241 }
242 ```
243 After, using `std::atomic`:
244 ```cpp
245 // Members:
246 std::atomic<SizeValueType> m_NumVoxelsInsideMask;
247 BeforeThreadedGenerateData()
248 {
249 // Initialize atomics
250 m_NumVoxelsInsideMask.store(0);
251 }
252
253 DynamicThreadedGenerateData(const RegionType & outputRegionForThread)
254 {
255 // Do algorithm without handling threadId
256 m_NumVoxelsInsideMask.fetch_add(numVoxelsForThisRegion, std::memory_order_relaxed);
257 }
258
259 AfterThreadedGenerateData()
260 {
261 // Get the value from the atomic
262 SizeValueType numVoxelsInsideMask = m_NumVoxelsInsideMask.load();
263 }
264 ```
265
266 `Get/SetGlobalMaximumNumberOfThreads()`, and `GlobalDefaultNumberOfThreads()`
267 now reside in `itk::MultiThreaderBase`. With a warning, they are still
268 available in `itk::PlatformMultiThreader`.
269 `GetGlobalDefaultNumberOfThreadsByPlatform()` has also been moved from
270 `itk::ThreadPool` to `itk::MultiThreaderBase`. In image filters and other
271 descendents of `itk::ProcessObject`, method `SetNumberOfThreads` has been
272 renamed into `SetNumberOfWorkUnits`. For `itk::MultiThreaderBase` and
273 descendents, `SetNumberOfThreads` has been split into
274 `SetMaximumNumberOfThreads` and `SetNumberOfWorkUnits`. Load balancing is
275 possible when `NumberOfWorkUnits` is greater than the number of threads. The
276 common case of `innerFilter->SetNumberOfThreads(1);` should be replaced by
277 `innerFilter->SetNumberOfWorkUnits(1);`. Generally, in most places where
278 threads were being manipulated before, work units should be accessed or
279 changed now.
280
281
282 To transition to the new threading model, it is usually enough to rename
283 `ThreadedGenerateData` into `DynamicThreadedGenerateData`, remove the
284 `threadId` parameter, and remove progress reporting which uses `threadId`.
285 Progress is being reported by multi-threaders on behalf of filters which
286 use `DynamicThreadedGenerateData` signature.
287
288 If your class needs to also work with legacy code where
289 `ITKV4_COMPATIBILITY` is enabled, invoke
290 `this->DynamicMultiThreadingOn();` in the filter constructor. An example of
291 an external module that transitioned to the new threading model can be found in
292 [this commit](https://github.com/InsightSoftwareConsortium/ITKTextureFeatures/commit/f794baa7546f9bb8b7d89ae3a083c9a432d55df0).
293
294 The variables `ITK_MAX_THREADS` and `ITK_DEFAULT_THREAD_ID` are now in the `itk::` namespace.
295 Backwards compatibility is currently supported by exposing these to the global namespace
296 with
297 ```cpp
298 using itk::ITK_MAX_THREADS;
299 using itk::ITK_DEFAULT_THREAD_ID;
300 ```
301
302 Spatial Objects Refactoring
303 ---------------------------
304 The SpatialObject classes were refactored to address issues and inconsistencies that had arisen over the years. The severity of these issues and inconsistencies was such that the classes provided incorrect and/or unexpected behaviors that made their proper usage problematic.
305
306 The most notable change is that dependencies on VNL Tree data structures and the requirement that every SpatialObject be defined
307 in an object space were eliminated. The VNL Tree data structures introduced unnecessary complexity, additional (redundant)
308 transformations, and dependencies on VNL in the API that ITKv5 seeks to eliminate. The elimination of a dependency on an IndexSpace
309 simplified the set of transformations that each SpatialObject needed to maintain and made the API of every SpatialObject more consistent
310 and intuitive.
311
312 SpatialObjects now only have two spaces and two transforms directly associated with them:
313 * ObjectSpace is the space that is "local" to each object. It is the physical space in which its data/parameters are defined. For
314 example, for an ImageSpatialObject it is the "PhysicalSpace" (see Image Class definition) of the Image. For an Line/Tube/DTI and other
315 point-based SpatialObjects, it is the inherent space in which the Point coordinates are specififed. Typically, when a SpatialObject is
316 extracted from an Image, the parameters/coordinates of the SpatialObject are the space as the physical space of the source Image. Any
317 children of a SpatialObject are defined within the ObjectSpace of that parent SpatialObject.
318
319 * ObjectToParent transform is the transform applied to move a SpatialObject within its parent object's ObjectSpace. An ObjectToParent
320 transform is an invertible affine transform. It is used to, for example, align a SpatialObject with a parent image (e.g., if an object
321 is extracted from one ImageSpatialObject but then aligned to and made a child of another ImageSpatialObject as is needed for atlas-based
322 image segmentation or for image-to-image registration). If an object does not have a parent, then its ObjectToParent transform
323 specifies how that object is positioned in "WorldSpace", as defined next.
324
325 * WorldSpace is the coordinate system defined by the top-level SpatialObject in a hierarchy (defined by parent-child relationships) of a
326 set of SpatialObjects. The top-level SpatialObject does not have a parent SpatialObject, and its ObjectToParentTransform specifies how
327 its ObjectSpace is transformed to map into the WorldSpace.
328
329 * ObjectToWorld transform is a derived transform that is managed by each SpatialObject for convenience (e.g., to save redundant
330 computations). It is a composition of all of the ObjectToParent transforms from an object's ObjectSpace to the WorldSpace in which it
331 exists. If an application maintains a single WorldSpace, point selections, object intersections, and such can be readily resolved by
332 using the ObjectToWorld transforms (and their inverses) at each object.
333
334 Each member function and variable of a SpatialObject now explicitly declares (via its name) if it is operating in WorldSpace or
335 ObjectSpace. For example, the `IsInside( point )` function has been replaced by two functions `IsInsideInObjectSpace( point )` and
336 `IsInsideInWorldSpace( point )` functions.
337
338 As implied above, the changes to SpatialObject are extensive. They include the following:
339 * Replace use of ComputeMyBoundingBox() with Update();
340 * Replace use of ComputeObjectToWorldTransform() with Update();
341 * Eliminate IndexToX transforms. SpatialObjects exist purely in physical space coordinates
342 * Eliminate vnl TreeNode usage. SpatialObjects now track their transforms, parents, and children directly.
343 * Eliminate AffineGeometryFrame
344 * Eliminate OffsetTable computation
345 * Dimension renamed to ObjectDimension - for consistency
346 * `AddSpatialObject()` renamed to `AddChild()` - for consistency
347 * `RemoveSpatialObject()` renamed to `RemoveChild()` - for consistency
348 * `Clear()` renamed to `ClearChildren()` - for clarity and consistency
349 * `AddChildrenToList()` added to speed parsing of children in tree
350 * `GetSpatialObjectTypeAsString()` is now `GetClassNameAndDimension()`
351 * PropertyType is not templated
352 * Converted API from using char * to using std::string
353 * `SetParent()` and `AddChild()` now create consistent trees and do not cause a spatial object to move in physical space (i.e., transforms are updated appropriately).
354 * `RemoveChild()` and `RemoveAllChildren()` fixed to remove all pointers to / from those children to / from the tree
355 * Helper functions simplify the specification of `IsInsideInObjectSpace()`, `ValueAtInObjectSpace()`, and other computations that potentially traverse an SO tree.
356 * Derived classes typically only need to implement `IsInsideInObjectSpace()` and `ComputeMyBoundingBoxInObjectSpace()` member functions. Logic for `ValueAtInObjectSpace()`, `IsInsideInWorldSpace()` and such is improved.
357 * PointBasedSpatialObjects had a PointListType type declaration. This was confusing because it referred to a list of SpatialObjectPoints and not ITK::Points. So, to avoid such confusion, now TubeSpatialObjects define TubePointListType, BlobSpatialObjects define BlobPointListType, and so forth.
358 * `ImageMaskSpatialObject::GetAxisAlignedBoundingBoxRegion()` was removed. `ImageMaskSpatialObject::ComputeMyBoundingBoxInIndexSpace()` should be used instead.
359 * `SpatialObjectReader::GetScene` was renamed to `GetGroup` along with changing the type from `ScenePointer` to `GroupPointer`.
360 * Elements of a `Group` are now `Children`, so `scene->GetObjects` now becomes `group->GetChildren`
361
362 Class changes
363 -------------
364
365 `itk::FilterWatcher` was deleted.
366 It should be replaced by [itk::SimpleFilterWatcher](../../../Modules/Core/Common/include/itkSimpleFilterWatcher.h).
367
368 `itksys::hash_map` has been removed. It should be replaced by `std::unordered_map`.
369
370 `WatershedImageFilter` produces slightly different results due to changes of `hash_map`.
371 Generally, [MorphologicalWatersheds](https://docs.itk.org/projects/doxygen/en/stable/classitk_1_1MorphologicalWatershedImageFilter.html)
372 produce more stable results and should be preferred to regular watersheds.
373
374 Since `itk::ProgressReporter` does not work well with the new threading model,
375 it should be replaced by `itk::ProgressTransformer`.
376 This only applies to classes which use `GenerateData()` method, and either
377 have multiple `ParallelizeRegion` calls or a long single-threaded section.
378 An example of how to add progress reporting can be found in
379 [this commit](https://github.com/InsightSoftwareConsortium/ITK/commit/dd0b0d128d6c0760cefd8a958107cb0e841b51b4).
380
381 Otsu filters now return the correct threshold (bin's maximum value instead of mid-point) with ITKv5.
382 The old behavior is kept when ITKV4_COMPATIBILITY is enabled by setting `ReturnBinMidpoint` to true by default.
383 It is recommended when migrating to ITKv5 to explicitly set the `ReturnBinMidpoint` value to false.
384 This change may effect computations which rely on the results of an Otsu threshold filter.
385
386 `HoughTransform2DCirclesImageFilter<TInputPixelType, TOutputPixelType, TRadiusPixelType>` no longer
387 has a default argument for its last template parameter. Instead, users of the filter should now
388 explicitly specify all three template arguments. Earlier versions of ITK assumed that the radius
389 pixel type should be the same as `TOutputPixelType`. However, it appears that for the radius pixel
390 type (`TRadiusPixelType`), a floating point type is often preferred, whereas for the accumulator
391 output pixel type (`TOutputPixelType`), an unsigned integer type is often more appropriate.
392
393 `GaussianDerivativeImageFunction::ImageDimension2` is renamed to `GaussianDerivativeImageFunction::ImageDimension`.
394 The nested `GaussianDerivativeImageFunction` types `GaussianDerivativeFunctionType` and
395 `GaussianDerivativeFunctionPointer` are renamed to `GaussianDerivativeSpatialFunctionType` and
396 `GaussianDerivativeSpatialFunctionPointer`, respectively.
397
398 All descendents of `itk::InterpolateImageFunction` must implement
399 `SizeType GetRadius() const` to indicate support radius of the interpolator.
400 This is used in `itk::ResampleImageFilter` to support streaming.
401
402 With ITK 5.0, `itk::ProcessObject::VerifyPreconditions()` and
403 `itk::ProcessObject::VerifyInputInformation` are now declared `const`,
404 so if you have overridden these virtual member function, make sure that you
405 also add `const`. If your application needs to compile with both ITKv4 and ITKv5,
406 you should use macro `ITKv5_CONST` instead of `const` keyword.
407 This macro is present in ITKv4 since commit
408 [commit b40f74e on 2018-11-14](https://github.com/InsightSoftwareConsortium/ITK/commit/b40f74e07d74614c75be4aceac63b87e80e589d1).
409
410 `itk::Barrier`, `itk::VectorResampleImageFilter` and `itk::VectorCastImageFilter` have been moved to `ITKDeprecated` module.
411
412 `itk::TreeNode`, `itk::TreeContainer`, `itk::TreeIteratorBase`, and all related classes have been moved to `ITKDeprecated` module.
413
414 `FixedArray` member functions `rBegin()` and `rEnd()` are replaced by `rbegin()` and `rend()`,
415 which return a `reverse_iterator`, compatible with the Standard C++ Library.
416
417 `BoundingBox` member function `GetCorners()` is replaced by `ComputeCorners()`, which return an
418 `std::array<PointType, NumberOfCorners>`, instead of a pointer to a `PointsContainer`.
419
420 `itk::ImageTransformer` has been moved to `ITKDeprecated` module. The new `itk::ImageSink` filter can be used in its place.
421
422 `itk::StatisticsImageFilter`, `itk::LabelStatisticsImageFilter` and
423 `itk::MinimumMaximumImageFilter` no longer produce an image as their
424 primary output, as it was a shallow copy of the primary
425 input. Additionally, minor API changes have occurred related to the
426 decorated output methods to conform to ITK conventions.
427
428 `itk::NiftiImageIO` was changed to support different kinds of Analyze file conventions.
429 See [Mayo/SPM "Analyze" Format Spec Compilation](http://www.grahamwideman.com/gw/brain/analyze/formatdoc.htm) for detailed description.
430 The method `SetLegacyAnalyze75Mode` is now expecting parameter specifying which convention to use:
431 * `itk::Analyze75Flavor::AnalyzeReject` - refuse to read Analyze files and show an error message
432 * `itk::Analyze75Flavor::AnalyzeITK4` - behaviour introduced in ITK4 NIFTI reader
433 * `itk::Analyze75Flavor::AnalyzeITK4Warning` - same as `AnalyzeITK4`, but a warning will be displayed
434 * `itk::Analyze75Flavor::AnalyzeSPM` - use SPM convention, same as Analyze reader in ITK3/ITK4
435 * `itk::Analyze75Flavor::AnalyzeFSL` - use FSL convention
436 There is also now CMake configuration option `ITK_NIFTI_IO_ANALYZE_FLAVOR` which specifies default behaviour of the reader, `ITK4Warning` is the default.
437
438 `itk::Transform` class had method signature change.
439 `void ComputeJacobianWithRespectToPosition(const PointType &, JacobianType &) const`
440 now has signature
441 `void ComputeJacobianWithRespectToPosition(const PointType &, JacobianPositionType &) const`.
442 `JacobianPositionType` is publicly exposed in `itk::Transform`.
443 See commit [commit 212cae5](https://github.com/InsightSoftwareConsortium/ITK/commit/212cae522d8451ea089c41f8a151279e1dd17042) for details.
444
445 With ITK 5.3, the `GetNumberOfWeights()` member functions of `itk::BSplineBaseTransform` and `itk::BSplineInterpolationWeightFunction`
446 are replaced by static constexpr data members named `NumberOfWeights`, and the `GetSupportSize()` member function of
447 `itk::BSplineInterpolationWeightFunction` is replaced by a static constexpr data member named `SupportSize`.
448
449 With ITK 5.3, SpatialOrientation was updated to a strongly typed enumeration (see below for details).
450 The namespece itself is only available in legacy mode. Some classes were renamed:
451 * `itk::SpatialOrientation::CoordinateTerms` became `itk::SpatialOrientationEnums::CoordinateTerms`.
452 * `itk::SpatialOrientation::CoordinateMajornessTerms` became `itk::SpatialOrientationEnums::CoordinateMajornessTerms`.
453 * `itk::SpatialOrientation::ValidCoordinateOrientationFlags` became `itk::SpatialOrientationEnums::ValidCoordinateOrientations`.
454
455 Since ITK 5.3, `OrientationAdapterBase` is deprecated. In ITKv6 it will be available in `ITKDeprecated` module.
456 SpatialOrientationAdapter no longer inherits from it.
457
458 Enumeration member names (`ITK_COORDINATE_UNKNOWN`, `ITK_COORDINATE_Right`, `ITK_COORDINATE_PrimaryMinor`, `ITK_COORDINATE_ORIENTATION_RIP` etc) are unchanged.
459
460 Implicit conversion of a single scalar value to a container (which would _fill_ the container by the
461 scalar value) is discouraged. With ITK 5.3, when having `ITK_LEGACY_REMOVE=ON`, the constructors of
462 `Point`, `RGBPixel`, `RGBAPixel`, and `Vector` that accept a single scalar value as argument are
463 declared `explicit`. ITK 5.3 has included a preferable alternative to these constructors:
464 `itk::MakeFilled<ContainerType>(value)`.
465
466 `itk::NumericTraits` can no longer be instantiated with `std::complex<T>`, if T is not a floating point type.
467 The old behavior can be restored by turning off `ITK_LEGACY_REMOVE`.
468
469 Consolidated Vector Filter
470 --------------------------
471
472 In ITK 5.0 many "vector" specialized filters and functions are
473 deprecated. These filters commonly contain a "Vector" prefix to the
474 regular filter. "Vector" may refer to an `itk::Image` of
475 `itk::Vector` pixel types and/or an `itk::VectorImage`. Support for
476 "vector" images is being consolidated into the regular filters without
477 the "Vector" prefix. The following deprecated classes need to be replaced
478 as follows:
479
480 * `VectorCentralDifferenceImageFunction` -> `CentralDifferenceImageFunction`
481 * `VectorExpandImageFilter` -> `ExpandImageFilter`
482 * `VectorCastImageFilter` -> `CastImageFilter`
483 * `VectorResampleImageFilter` -> `ResampleImageFilter`
484
485 Additionally, the following change should be considered:
486
487 * `WarpImageFilter` -> `ResampleImageFilter`
488 * `WarpVectorImageFilter` -> `ResampleImageFilter`
489
490 [This update to the ITK
491 Examples](https://github.com/InsightSoftwareConsortium/ITK/commit/b8dbc939ecb086b0e60faf4710657596553f643f)
492 is illustrative on how to use the `ResampleImageFilter` in place of a
493 warp filter. Note these warp filters are being considered for
494 deprecation in the future.
495
496
497 Python changes
498 --------------
499
500 Mesh-related class wrapping has been simplified, made more consistent, and
501 expanded, but previous template parameters may not be available.
502
503 Arguments to functions in `extras` were cleaned up and now use snake case.
504
505 Strongly Typed Enumerations
506 ---------------------------
507
508 In ITK 5, enumerations are strongly typed, declared with `enum class`. A best
509 practice in modern C++, strongly typed enum's [offer the following improvements](https://www.modernescpp.com/index.php/strongly-typed-enums):
510
511 - The enumerators can only be accessed in the scope of the enumeration.
512 - The enumerators don't implicitly convert to `int`.
513 - The enumerators aren't imported in the enclosing scope.
514 - The type of the enumerators is by default `int`. Therefore, you can forward the enumeration.
515
516 In order to preserve as much backwards compatibility as possible, appropriate
517 scoping, provide clean, readable code, facilitate wrapping in languages such
518 as Python, and enable printing enum values to `std::ostream` with
519 `operator<<`, and support templates, enums that we previously declared as:
520
521 ```cpp
522 // itkClassName.h
523 namespace itk
524 {
525
526 class ClassName
527 {
528 public:
529 enum Choices
530 {
531 One,
532 Two,
533 Three
534 };
535 };
536
537 } // namespace itk
538 ```
539
540 are now declared as:
541
542 ```cpp
543 // itkClassName.h
544 namespace itk
545 {
546
547 class ClassNameEnums
548 {
549 public:
550 enum class Choices : uint8_t
551 {
552 One,
553 Two,
554 Three
555 };
556 };
557 extern ITKModuleName_EXPORT std::ostream &
558 operator<<(std::ostream & out, const ClassNameEnums::Choices value);
559
560 class ClassName
561 {
562 public:
563 using ChoicesEnum = ClassNameEnums::Choices;
564 #if !defined(ITK_LEGACY_REMOVE)
565 using Choices = ChoicesEnum;
566 static constexpr Choices One = ChoicesEnum::One;
567 static constexpr Choices Two = ChoicesEnum::Two;
568 static constexpr Choices Three = ChoicesEnum::Three;
569 #endif
570 };
571
572 } // namespace itk
573
574 // itkClassName.cxx
575 namespace itk
576 {
577
578 /** Print enum values */
579 std::ostream &
580 operator<<(std::ostream & out, const ClassNameEnums::Choices value)
581 {
582 return out << [value] {
583 switch (value)
584 {
585 case ClassNameEnums::Choices::One:
586 return "itk::ClassNameEnums::Choices::One";
587 case ClassNameEnums::Choices::Two:
588 return "itk::ClassNameEnums::Choices::Two";
589 case ClassNameEnums::Choices::Three:
590 return "itk::ClassNameEnums::Choices::Three";
591 default:
592 return "INVALID VALUE FOR itk::ClassNameEnums::Choices";
593 }
594 }();
595 }
596 ```
597
598 for a class called `ClassName` and an enum called `Choices`.
599
600 Wrapping is configured with `itk_wrap_simple_class("itk::ClassNameEnums")`,
601 which results in access to the enums in Python as
602 `itk.ClassNameEnums.Choices_One`, `itk.ClassNameEnums.Choices_Two`, and
603 `itk.ClassNameEnums.Choices_Three`.
604
605 While backwards compatible type aliases and `static constexpr` backwards
606 compatible values were introduced, the names of the enums were generally made
607 more consistent, and existing code should migrate to new enum names. Since
608 strongly typed enums do not implicitly cast to int's like classic enums,
609 explicit `static_cast`'s may be required in migrated code.
610
611 Common enums used in classes across the toolkit are now available in the
612 `itk::CommonEnums` class.
613
614 As a consequence of improved enum support, a new library binary to provide
615 enum class `operator<<` definitions is required for many ITK modules that were
616 previously header-only. As a result, remote modules may encounter build-time
617 link errors such as:
618
619 ```
620 itk::RecursiveGaussianImageFilter<itk::Image<float, 3u>, itk::Image<float, 3u> >::PrintSelf(std::ostream&, itk::Indent) const: error: undefined reference to 'itk::operator<<(std::ostream&, itk::RecursiveGaussianImageFilterEnums::GaussianOrder)' `itk::CommonEnums` class.
621 ```
622
623 To resolve these errors, update the remote module's dependency specification in
624 `itk-module.cmake`. List the dependent module under `DEPENDS` instead of
625 `COMPILE_DEPENDS`; this will link to the new dependent library.
626
627 Update scripts
628 --------------
629
630 [Utilities/ITKv5Preparation](https://github.com/InsightSoftwareConsortium/ITK/tree/master/Utilities/ITKv5Preparation) directory contains
631 bash scripts which have been used to update ITK to version 5. These scripts
632
633
634
635 Backported ITKv6 features
636 -------------------------
637
638 ITKv6 will prefer itk::AnatomicalOrientation over itk::SpatialOrientation
639 -------------------------------------------------------------------------
640
641 As of v5.4.5 and later, the `itk::AnatomicalOrientation` API is added and supported to facilitate
642 conversion to the ITKv6 recommended paradigm. The `itk::AnatomicalOrientation` is not available
643 in v5.4.4 and earlier releases.
644
645 The enumeration defined in `itk::SpatialOrientation`, including `itk::SpatialOrientation::CoordinateTerms`,
646 `itk::SpatialOrientation::CoordinateMajornessTerms`, and `itk::SpatialOrientation::ValidCoordinateOrientations` may be
647 deprecated in the future. These terms described an orientation of an axis in a coordinate system, by the "from" or
648 "negative" direction. For example `CoordinateTerms::ITK_COORDINATE_Right` describes an axis moving from the "Right" to
649 the "Left" side of the body.
650
651 This is the opposite of the DICOM `Patient Orientation (0020,0020)` tag.
652
653 The `itk::AnatomicalOrientation` class now represents the anatomical orientation. The class can provide a representation
654 of itself as an unambiguous enumeration, string and a matrix. It provides both a `PositiveEnum` and a `NegativeEnum` for
655 three letter descriptions of the anatomical orientation, which is ambiguous.
656
657 The recommended unambiguous way to define an anatomical orientation is the following:
658
659 ```cpp
660 itk::AnatomicalOrientation(itk::AnatomicalOrientation::CoordinateEnum::RightToLeft,
661 itk::AnatomicalOrientation::CoordinateEnum::AnteriorToPosterior,
662 itk::AnatomicalOrientation::CoordinateEnum::InferiorToSuperior);
663 ```
664
665 The `itk::SpatialOrientation::ValidCoordinateOrientations` enumerations can be explicitly or implicitly converted to the
666 new `AnatomicalOrientation` object:
667
668 ```cpp
669 itk::AnatomicalOrientation orientation = itk::SpatialOrientation::ValidCoordinateOrientations::ITK_COORDINATE_ORIENTATION_RAI;
670 orientation = itk::AnatomicalOrientation(itk::SpatialOrientation::ValidCoordinateOrientations::ITK_COORDINATE_ORIENTATION_RIP;)
671 ```
672
673 The Python wrapping of `itk::AnatomicalOrientation` is not supported in ITKv5 due to conflicts with `itk::SpatialOrientation`
674 wrapping.