SimpleITK  
Public Types | Public Member Functions | Private Types | Private Member Functions | Static Private Member Functions | Private Attributes | Friends | List of all members
itk::simple::InvertDisplacementFieldImageFilter Class Reference

Iteratively estimates the inverse of a displacement field by fixed-point composition. More...

#include <sitkInvertDisplacementFieldImageFilter.h>

+ Inheritance diagram for itk::simple::InvertDisplacementFieldImageFilter:
+ Collaboration diagram for itk::simple::InvertDisplacementFieldImageFilter:

Detailed Description

Iteratively estimates the inverse of a displacement field by fixed-point composition.

Overview (implementation)
Given a forward displacement field \( \mathbf{u}(\mathbf{x}) \) (mapping points \( \mathbf{x} \mapsto \mathbf{x} + \mathbf{u}(\mathbf{x}) \) ), the inverse field \( \mathbf{v}(\mathbf{y}) \) satisfies

\[ \mathbf{x} + \mathbf{u}(\mathbf{x}) = \mathbf{y}, \quad \mathbf{y} + \mathbf{v}(\mathbf{y}) = \mathbf{x}. \]

Eliminating \(\mathbf{x}\) yields the fixed-point condition

\[ \mathbf{v}(\mathbf{y}) \approx -\,\mathbf{u}\!\left(\mathbf{y} + \mathbf{v}(\mathbf{y})\right). \]

This filter solves that condition by iterative composition starting from an initial inverse estimate (optionally supplied by the user). At each iteration, the forward field is interpolated at warped locations \( \mathbf{y} + \mathbf{v}^{(k)}(\mathbf{y}) \) and the inverse is updated to reduce both the mean and max residual norms until user-specified tolerances or an iteration cap is reached. The implementation supports multithreading and vector-image interpolation; linear vector interpolation is used by default.
Algorithmic sketch
For output lattice point \(\mathbf{y}\) :
  • Initialize \(\mathbf{v}^{(0)}(\mathbf{y})\) to the provided InverseFieldInitialEstimate (or zero if none).
  • Iterate \(k = 0,1,\dots\) up to MaximumNumberOfIterations (default 20):

    \[ \mathbf{r}^{(k)}(\mathbf{y}) = \mathbf{u}\!\left(\mathbf{y} + \mathbf{v}^{(k)}(\mathbf{y})\right) + \mathbf{v}^{(k)}(\mathbf{y}), \]

    \[ \mathbf{v}^{(k+1)}(\mathbf{y}) = \mathbf{v}^{(k)}(\mathbf{y}) - \mathbf{r}^{(k)}(\mathbf{y}). \]

  • Stop when \(\max_{\mathbf{y}}\|\mathbf{r}^{(k)}(\mathbf{y})\|\) and \(\mathrm{mean}_{\mathbf{y}}\|\mathbf{r}^{(k)}(\mathbf{y})\|\) fall below MaxErrorToleranceThreshold and MeanErrorToleranceThreshold .
Designed usage and assumptions
  • Best used inside iterative registration where forward updates are small and diffeomorphic at each step; supplying the previous iteration’s inverse as the initial estimate greatly accelerates convergence and improves robustness.
  • Not intended to recover a full inverse from identity in one step for large deformations; prefer multi-resolution schemes, incremental composition, or scaling-and-squaring to stay within the contraction regime of the fixed-point map.
  • The forward field should be (approximately) invertible in the region of interest (positive Jacobian determinant). Non-invertible folds will stall or diverge.
  • Boundary handling: when EnforceBoundaryCondition=true (default), the inverse is clamped to zero at the image boundary to avoid extrapolation artifacts.
Complexity and performance
Each iteration performs one interpolation and vector update per voxel: \(O(N \times I)\) work for \(N\) voxels and \(I\) iterations. The filter parallelizes across the output region and reuses an internal composed field to minimize memory traffic.
Relationship to Symmetric Normalization (SyN)
This filter is a core component of the Symmetric Normalization (SyN) registration algorithm: at each iteration SyN updates forward and inverse velocity/displacement estimates symmetrically and uses this routine to maintain an explicit inverse field, preserving inverse-consistency during optimization
Author
Nick Tustison
Brian Avants
References

Definition at line 103 of file sitkInvertDisplacementFieldImageFilter.h.

Public Types

using PixelIDTypeList = RealVectorPixelIDTypeList
 
using Self = InvertDisplacementFieldImageFilter
 
- Public Types inherited from itk::simple::ImageFilter
using Self = ImageFilter
 
- Public Types inherited from itk::simple::ProcessObject
using Self = ProcessObject
 

Public Member Functions

void EnforceBoundaryConditionOff ()
 
void EnforceBoundaryConditionOn ()
 
Image Execute (const Image &displacementField)
 
Image Execute (const Image &displacementField, const Image &inverseFieldInitialEstimate)
 
bool GetEnforceBoundaryCondition () const
 
double GetMaxErrorNorm () const
 
double GetMaxErrorToleranceThreshold () const
 
uint32_t GetMaximumNumberOfIterations () const
 
double GetMeanErrorNorm () const
 
double GetMeanErrorToleranceThreshold () const
 
std::string GetName () const
 
 InvertDisplacementFieldImageFilter ()
 
void SetEnforceBoundaryCondition (bool EnforceBoundaryCondition)
 
void SetMaxErrorToleranceThreshold (double MaxErrorToleranceThreshold)
 
void SetMaximumNumberOfIterations (uint32_t MaximumNumberOfIterations)
 
void SetMeanErrorToleranceThreshold (double MeanErrorToleranceThreshold)
 
std::string ToString () const
 
virtual ~InvertDisplacementFieldImageFilter ()
 
- Public Member Functions inherited from itk::simple::ImageFilter
 ImageFilter ()
 
virtual ~ImageFilter ()=0
 
- Public Member Functions inherited from itk::simple::ProcessObject
virtual void Abort ()
 
virtual int AddCommand (itk::simple::EventEnum event, const std::function< void()> &func)
 Directly add a callback to observe an event.
 
virtual int AddCommand (itk::simple::EventEnum event, itk::simple::Command &cmd)
 Add a Command Object to observer the event.
 
virtual float GetProgress () const
 An Active Measurement of the progress of execution.
 
virtual bool HasCommand (itk::simple::EventEnum event) const
 Query of this object has any registered commands for event.
 
 ProcessObject ()
 
virtual void RemoveAllCommands ()
 Remove all registered commands.
 
virtual ~ProcessObject ()
 
virtual void DebugOn ()
 
virtual void DebugOff ()
 
virtual bool GetDebug () const
 
virtual void SetDebug (bool debugFlag)
 
virtual void SetNumberOfThreads (unsigned int n)
 
virtual unsigned int GetNumberOfThreads () const
 
virtual void SetNumberOfWorkUnits (unsigned int n)
 
virtual unsigned int GetNumberOfWorkUnits () const
 

Private Types

using MemberFunctionType
 

Private Member Functions

template<class TImageType>
Image ExecuteInternal (const Image *displacementField, const Image *inverseFieldInitialEstimate)
 

Static Private Member Functions

static const detail::MemberFunctionFactory< MemberFunctionType > & GetMemberFunctionFactory ()
 

Private Attributes

bool m_EnforceBoundaryCondition { true }
 
double m_MaxErrorNorm { 0.0 }
 
double m_MaxErrorToleranceThreshold { 0.1 }
 
uint32_t m_MaximumNumberOfIterations { 10u }
 
double m_MeanErrorNorm { 0.0 }
 
double m_MeanErrorToleranceThreshold { 0.001 }
 

Friends

struct detail::MemberFunctionAddressor< MemberFunctionType >
 

Additional Inherited Members

- Static Public Member Functions inherited from itk::simple::ProcessObject
static bool GetGlobalDefaultDebug ()
 
static void GlobalDefaultDebugOff ()
 
static void GlobalDefaultDebugOn ()
 
static void SetGlobalDefaultDebug (bool debugFlag)
 
static void GlobalWarningDisplayOn ()
 
static void GlobalWarningDisplayOff ()
 
static void SetGlobalWarningDisplay (bool flag)
 
static bool GetGlobalWarningDisplay ()
 
static double GetGlobalDefaultCoordinateTolerance ()
 Access the global tolerance to determine congruent spaces.
 
static void SetGlobalDefaultCoordinateTolerance (double)
 Access the global tolerance to determine congruent spaces.
 
static double GetGlobalDefaultDirectionTolerance ()
 Access the global tolerance to determine congruent spaces.
 
static void SetGlobalDefaultDirectionTolerance (double)
 Access the global tolerance to determine congruent spaces.
 
static bool SetGlobalDefaultThreader (const std::string &threader)
 Set/Get the default threader used for process objects.
 
static std::string GetGlobalDefaultThreader ()
 Set/Get the default threader used for process objects.
 
static void SetGlobalDefaultNumberOfThreads (unsigned int n)
 
static unsigned int GetGlobalDefaultNumberOfThreads ()
 Set/Get the default threader used for process objects.
 
- Protected Member Functions inherited from itk::simple::ImageFilter
void CheckImageMatchingDimension (const Image &image1, const Image &image2, const std::string &image2Name)
 
void CheckImageMatchingPixelType (const Image &image1, const Image &image2, const std::string &image2Name)
 
void CheckImageMatchingSize (const Image &image1, const Image &image2, const std::string &image2Name)
 
- Protected Member Functions inherited from itk::simple::ProcessObject
virtual unsigned long AddITKObserver (const itk::EventObject &, itk::Command *)
 
virtual itk::ProcessObject * GetActiveProcess ()
 
virtual void OnActiveProcessDelete ()
 
virtual void onCommandDelete (const itk::simple::Command *cmd) noexcept
 
virtual void PreUpdate (itk::ProcessObject *p)
 
virtual void RemoveITKObserver (EventCommand &e)
 
- Protected Member Functions inherited from itk::simple::NonCopyable
 NonCopyable ()=default
 
 NonCopyable (const NonCopyable &)=delete
 
NonCopyable & operator= (const NonCopyable &)=delete
 
- Static Protected Member Functions inherited from itk::simple::ImageFilter
template<class TImageType>
static void FixNonZeroIndex (TImageType *img)
 
- Static Protected Member Functions inherited from itk::simple::ProcessObject
template<class TImageType>
static TImageType::ConstPointer CastImageToITK (const Image &img)
 
template<class TPixelType, unsigned int VImageDimension, unsigned int VLength, template< typename, unsigned int > class TVector>
static Image CastITKToImage (itk::Image< TVector< TPixelType, VLength >, VImageDimension > *img)
 
template<unsigned int VImageDimension, unsigned int VLength, template< unsigned int > class TVector>
static Image CastITKToImage (itk::Image< TVector< VLength >, VImageDimension > *img)
 
template<class TImageType>
static Image CastITKToImage (TImageType *img)
 
static const itk::EventObject & GetITKEventObject (EventEnum e)
 
template<typename T>
static std::ostream & ToStringHelper (std::ostream &os, const T &v)
 
static std::ostream & ToStringHelper (std::ostream &os, const char &v)
 
static std::ostream & ToStringHelper (std::ostream &os, const signed char &v)
 
static std::ostream & ToStringHelper (std::ostream &os, const unsigned char &v)
 

Member Typedef Documentation

◆ MemberFunctionType

using itk::simple::InvertDisplacementFieldImageFilter::MemberFunctionType
private
Initial value:
Image (Self::*)(const Image *
displacementField, const Image *
inverseFieldInitialEstimate)
itk::simple::Image
The Image class for SimpleITK.
Definition sitkImage.h:77

Setup for member function dispatching

Definition at line 198 of file sitkInvertDisplacementFieldImageFilter.h.

◆ PixelIDTypeList

using itk::simple::InvertDisplacementFieldImageFilter::PixelIDTypeList = RealVectorPixelIDTypeList

Define the pixels types supported by this filter

Definition at line 115 of file sitkInvertDisplacementFieldImageFilter.h.

◆ Self

using itk::simple::InvertDisplacementFieldImageFilter::Self = InvertDisplacementFieldImageFilter

Definition at line 105 of file sitkInvertDisplacementFieldImageFilter.h.

Constructor & Destructor Documentation

◆ ~InvertDisplacementFieldImageFilter()

virtual itk::simple::InvertDisplacementFieldImageFilter::~InvertDisplacementFieldImageFilter ( )
virtual

Destructor

◆ InvertDisplacementFieldImageFilter()

itk::simple::InvertDisplacementFieldImageFilter::InvertDisplacementFieldImageFilter ( )

Default Constructor that takes no arguments and initializes default parameters

Member Function Documentation

◆ EnforceBoundaryConditionOff()

void itk::simple::InvertDisplacementFieldImageFilter::EnforceBoundaryConditionOff ( )
inline

Definition at line 163 of file sitkInvertDisplacementFieldImageFilter.h.

References SetEnforceBoundaryCondition().

◆ EnforceBoundaryConditionOn()

void itk::simple::InvertDisplacementFieldImageFilter::EnforceBoundaryConditionOn ( )
inline

Set the value of EnforceBoundaryCondition to true or false respectfully.

Definition at line 161 of file sitkInvertDisplacementFieldImageFilter.h.

References SetEnforceBoundaryCondition().

◆ Execute() [1/2]

Image itk::simple::InvertDisplacementFieldImageFilter::Execute ( const Image & displacementField)

◆ Execute() [2/2]

Image itk::simple::InvertDisplacementFieldImageFilter::Execute ( const Image & displacementField,
const Image & inverseFieldInitialEstimate )

Execute the filter on the input image

◆ ExecuteInternal()

template<class TImageType>
Image itk::simple::InvertDisplacementFieldImageFilter::ExecuteInternal ( const Image * displacementField,
const Image * inverseFieldInitialEstimate )
private

Referenced by detail::MemberFunctionAddressor< MemberFunctionType >.

◆ GetEnforceBoundaryCondition()

bool itk::simple::InvertDisplacementFieldImageFilter::GetEnforceBoundaryCondition ( ) const
inline

Definition at line 167 of file sitkInvertDisplacementFieldImageFilter.h.

References m_EnforceBoundaryCondition.

◆ GetMaxErrorNorm()

double itk::simple::InvertDisplacementFieldImageFilter::GetMaxErrorNorm ( ) const
inline

This is a measurement. Its value is updated in the Execute methods, so the value will only be valid after an execution.

Definition at line 175 of file sitkInvertDisplacementFieldImageFilter.h.

References m_MaxErrorNorm.

◆ GetMaxErrorToleranceThreshold()

double itk::simple::InvertDisplacementFieldImageFilter::GetMaxErrorToleranceThreshold ( ) const
inline

Definition at line 139 of file sitkInvertDisplacementFieldImageFilter.h.

References m_MaxErrorToleranceThreshold.

◆ GetMaximumNumberOfIterations()

uint32_t itk::simple::InvertDisplacementFieldImageFilter::GetMaximumNumberOfIterations ( ) const
inline

Definition at line 128 of file sitkInvertDisplacementFieldImageFilter.h.

References m_MaximumNumberOfIterations.

◆ GetMeanErrorNorm()

double itk::simple::InvertDisplacementFieldImageFilter::GetMeanErrorNorm ( ) const
inline

This is a measurement. Its value is updated in the Execute methods, so the value will only be valid after an execution.

Definition at line 182 of file sitkInvertDisplacementFieldImageFilter.h.

References m_MeanErrorNorm.

◆ GetMeanErrorToleranceThreshold()

double itk::simple::InvertDisplacementFieldImageFilter::GetMeanErrorToleranceThreshold ( ) const
inline

Definition at line 150 of file sitkInvertDisplacementFieldImageFilter.h.

References m_MeanErrorToleranceThreshold.

◆ GetMemberFunctionFactory()

static const detail::MemberFunctionFactory< MemberFunctionType > & itk::simple::InvertDisplacementFieldImageFilter::GetMemberFunctionFactory ( )
staticprivate

◆ GetName()

std::string itk::simple::InvertDisplacementFieldImageFilter::GetName ( ) const
inlinevirtual

Name of this class

Implements itk::simple::ProcessObject.

Definition at line 185 of file sitkInvertDisplacementFieldImageFilter.h.

◆ SetEnforceBoundaryCondition()

void itk::simple::InvertDisplacementFieldImageFilter::SetEnforceBoundaryCondition ( bool EnforceBoundaryCondition)
inline

Definition at line 156 of file sitkInvertDisplacementFieldImageFilter.h.

References m_EnforceBoundaryCondition.

Referenced by EnforceBoundaryConditionOff(), and EnforceBoundaryConditionOn().

◆ SetMaxErrorToleranceThreshold()

void itk::simple::InvertDisplacementFieldImageFilter::SetMaxErrorToleranceThreshold ( double MaxErrorToleranceThreshold)
inline

Definition at line 134 of file sitkInvertDisplacementFieldImageFilter.h.

References m_MaxErrorToleranceThreshold.

◆ SetMaximumNumberOfIterations()

void itk::simple::InvertDisplacementFieldImageFilter::SetMaximumNumberOfIterations ( uint32_t MaximumNumberOfIterations)
inline

Definition at line 123 of file sitkInvertDisplacementFieldImageFilter.h.

References m_MaximumNumberOfIterations.

◆ SetMeanErrorToleranceThreshold()

void itk::simple::InvertDisplacementFieldImageFilter::SetMeanErrorToleranceThreshold ( double MeanErrorToleranceThreshold)
inline

Definition at line 145 of file sitkInvertDisplacementFieldImageFilter.h.

References m_MeanErrorToleranceThreshold.

◆ ToString()

std::string itk::simple::InvertDisplacementFieldImageFilter::ToString ( ) const
virtual

Print ourselves out

Reimplemented from itk::simple::ProcessObject.

Friends And Related Symbol Documentation

◆ detail::MemberFunctionAddressor< MemberFunctionType >

friend struct detail::MemberFunctionAddressor< MemberFunctionType >
friend

Definition at line 201 of file sitkInvertDisplacementFieldImageFilter.h.

References ExecuteInternal().

Member Data Documentation

◆ m_EnforceBoundaryCondition

bool itk::simple::InvertDisplacementFieldImageFilter::m_EnforceBoundaryCondition { true }
private

Definition at line 215 of file sitkInvertDisplacementFieldImageFilter.h.

Referenced by GetEnforceBoundaryCondition(), and SetEnforceBoundaryCondition().

◆ m_MaxErrorNorm

double itk::simple::InvertDisplacementFieldImageFilter::m_MaxErrorNorm { 0.0 }
private

Definition at line 219 of file sitkInvertDisplacementFieldImageFilter.h.

Referenced by GetMaxErrorNorm().

◆ m_MaxErrorToleranceThreshold

double itk::simple::InvertDisplacementFieldImageFilter::m_MaxErrorToleranceThreshold { 0.1 }
private

Definition at line 211 of file sitkInvertDisplacementFieldImageFilter.h.

Referenced by GetMaxErrorToleranceThreshold(), and SetMaxErrorToleranceThreshold().

◆ m_MaximumNumberOfIterations

uint32_t itk::simple::InvertDisplacementFieldImageFilter::m_MaximumNumberOfIterations { 10u }
private

Definition at line 209 of file sitkInvertDisplacementFieldImageFilter.h.

Referenced by GetMaximumNumberOfIterations(), and SetMaximumNumberOfIterations().

◆ m_MeanErrorNorm

double itk::simple::InvertDisplacementFieldImageFilter::m_MeanErrorNorm { 0.0 }
private

Definition at line 220 of file sitkInvertDisplacementFieldImageFilter.h.

Referenced by GetMeanErrorNorm().

◆ m_MeanErrorToleranceThreshold

double itk::simple::InvertDisplacementFieldImageFilter::m_MeanErrorToleranceThreshold { 0.001 }
private

Definition at line 213 of file sitkInvertDisplacementFieldImageFilter.h.

Referenced by GetMeanErrorToleranceThreshold(), and SetMeanErrorToleranceThreshold().

The documentation for this class was generated from the following file:
Generated on unknown for SimpleITK by   doxygen 1.13.2 | Privacy Policy