SimpleITK  1.3.0.dev466
sitkImageRegistrationMethod.h
Go to the documentation of this file.
1 /*=========================================================================
2 *
3 * Copyright Insight Software Consortium
4 *
5 * Licensed under the Apache License, Version 2.0 (the "License");
6 * you may not use this file except in compliance with the License.
7 * You may obtain a copy of the License at
8 *
9 * http://www.apache.org/licenses/LICENSE-2.0.txt
10 *
11 * Unless required by applicable law or agreed to in writing, software
12 * distributed under the License is distributed on an "AS IS" BASIS,
13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 * See the License for the specific language governing permissions and
15 * limitations under the License.
16 *
17 *=========================================================================*/
18 #ifndef sitkImageRegistrationMethod_h
19 #define sitkImageRegistrationMethod_h
20 
21 #include "sitkRegistration.h"
22 
23 #include "sitkDetail.h"
24 #include "sitkImage.h"
25 #include "sitkPixelIDTokens.h"
27 #include "sitkProcessObject.h"
28 
29 #include "sitkRandomSeed.h"
30 #include "sitkInterpolator.h"
31 #include "sitkTransform.h"
32 
33 
34 namespace itk
35 {
36 
37 #ifndef SWIG
38 template< typename TInternalComputationValueType> class ObjectToObjectOptimizerBaseTemplate;
39 template<typename TFixedImage,
40  typename TMovingImage,
41  typename TVirtualImage,
42  typename TInternalComputationValueType,
43  typename TMetricTraits >
44 class ImageToImageMetricv4;
45 
46 template<typename TFixedImageType,
47  typename TMovingImageType,
48  typename TVirtualImageType,
49  typename TCoordRep>
50 class DefaultImageToImageMetricTraitsv4;
51 
52 template<typename TMetric> class RegistrationParameterScalesEstimator;
53 
54 template<unsigned int VDimension> class SpatialObject;
55 
56 class Command;
57 class EventObject;
58 #endif
59 
60 
61 
62 namespace simple
63 {
64  class BSplineTransform;
65 
90  : public ProcessObject
91  {
92  public:
93 
96 
97  virtual ~ImageRegistrationMethod();
98 
100 
101  std::string GetName() const { return std::string("ImageRegistrationMethod"); }
102 
109  std::string ToString() const;
110 
116  { return this->m_Interpolator; }
117  SITK_RETURN_SELF_TYPE_HEADER SetInterpolator ( InterpolatorEnum Interpolator )
118  { this->m_Interpolator = Interpolator; return *this; }
137 #if !defined(SWIG) || defined(JAVASWIG) || defined(CSHARPSWIG)
138  // Only wrap this method if the wrapping language is strongly typed
139  SITK_RETURN_SELF_TYPE_HEADER SetInitialTransform ( const Transform &transform );
140 #endif
141  SITK_RETURN_SELF_TYPE_HEADER SetInitialTransform ( Transform &transform, bool inPlace=true );
143  { return this->m_InitialTransform; }
145  { return this->m_InitialTransformInPlace;}
163  void SetInitialTransformAsBSpline( BSplineTransform &transform,
164  bool inPlace=true,
165  const std::vector<unsigned int> &scaleFactors=std::vector<unsigned int>() );
166 
180  SITK_RETURN_SELF_TYPE_HEADER SetMovingInitialTransform( const Transform &transform )
181  { this->m_MovingInitialTransform = transform; return *this; }
183  { return this->m_MovingInitialTransform; }
196  SITK_RETURN_SELF_TYPE_HEADER SetFixedInitialTransform( const Transform &transform )
197  { this->m_FixedInitialTransform = transform; return *this; }
199  { return this->m_FixedInitialTransform; }
207  SITK_RETURN_SELF_TYPE_HEADER SetVirtualDomain( const std::vector<uint32_t> &virtualSize,
208  const std::vector<double> &virtualOrigin,
209  const std::vector<double> &virtualSpacing,
210  const std::vector<double> &virtualDirection );
211  SITK_RETURN_SELF_TYPE_HEADER SetVirtualDomainFromImage( const Image &virtualImage );
220  SITK_RETURN_SELF_TYPE_HEADER SetMetricAsANTSNeighborhoodCorrelation( unsigned int radius );
221 
226  SITK_RETURN_SELF_TYPE_HEADER SetMetricAsCorrelation( );
227 
232  SITK_RETURN_SELF_TYPE_HEADER SetMetricAsDemons( double intensityDifferenceThreshold = 0.001 );
233 
238  SITK_RETURN_SELF_TYPE_HEADER SetMetricAsJointHistogramMutualInformation( unsigned int numberOfHistogramBins = 20,
239  double varianceForJointPDFSmoothing = 1.5);
240 
245  SITK_RETURN_SELF_TYPE_HEADER SetMetricAsMeanSquares( );
246 
252  SITK_RETURN_SELF_TYPE_HEADER SetMetricAsMattesMutualInformation( unsigned int numberOfHistogramBins = 50 );
253 
254 
257  EachIteration
258  };
259 
264  SITK_RETURN_SELF_TYPE_HEADER SetOptimizerAsConjugateGradientLineSearch( double learningRate,
265  unsigned int numberOfIterations,
266  double convergenceMinimumValue = 1e-6,
267  unsigned int convergenceWindowSize = 10,
268  double lineSearchLowerLimit = 0,
269  double lineSearchUpperLimit = 5.0,
270  double lineSearchEpsilon = 0.01,
271  unsigned int lineSearchMaximumIterations = 20,
272  EstimateLearningRateType estimateLearningRate = Once,
273  double maximumStepSizeInPhysicalUnits = 0.0 );
274 
279  SITK_RETURN_SELF_TYPE_HEADER SetOptimizerAsRegularStepGradientDescent( double learningRate,
280  double minStep,
281  unsigned int numberOfIterations,
282  double relaxationFactor=0.5,
283  double gradientMagnitudeTolerance = 1e-4,
284  EstimateLearningRateType estimateLearningRate = Never,
285  double maximumStepSizeInPhysicalUnits = 0.0);
286 
291  SITK_RETURN_SELF_TYPE_HEADER SetOptimizerAsGradientDescent( double learningRate,
292  unsigned int numberOfIterations,
293  double convergenceMinimumValue = 1e-6,
294  unsigned int convergenceWindowSize = 10,
295  EstimateLearningRateType estimateLearningRate = Once,
296  double maximumStepSizeInPhysicalUnits = 0.0);
297 
302  SITK_RETURN_SELF_TYPE_HEADER SetOptimizerAsGradientDescentLineSearch( double learningRate,
303  unsigned int numberOfIterations,
304  double convergenceMinimumValue = 1e-6,
305  unsigned int convergenceWindowSize = 10,
306  double lineSearchLowerLimit = 0,
307  double lineSearchUpperLimit = 5.0,
308  double lineSearchEpsilon = 0.01,
309  unsigned int lineSearchMaximumIterations = 20,
310  EstimateLearningRateType estimateLearningRate = Once,
311  double maximumStepSizeInPhysicalUnits = 0.0 );
312 
319  SITK_RETURN_SELF_TYPE_HEADER SetOptimizerAsLBFGSB(double gradientConvergenceTolerance = 1e-5,
320  unsigned int numberOfIterations = 500,
321  unsigned int maximumNumberOfCorrections = 5,
322  unsigned int maximumNumberOfFunctionEvaluations = 2000,
323  double costFunctionConvergenceFactor = 1e+7,
324  double lowerBound = std::numeric_limits<double>::min(),
325  double upperBound = std::numeric_limits<double>::max(),
326  bool trace = false );
327 
340  SITK_RETURN_SELF_TYPE_HEADER SetOptimizerAsLBFGS2( double solutionAccuracy = 1e-5,
341  unsigned int numberOfIterations = 0,
342  unsigned int hessianApproximateAccuracy = 6,
343  unsigned int deltaConvergenceDistance = 0,
344  double deltaConvergenceTolerance = 1e-5,
345  unsigned int lineSearchMaximumEvaluations = 40,
346  double lineSearchMinimumStep = 1e-20,
347  double lineSearchMaximumStep = 1e20,
348  double lineSearchAccuracy = 1e-4);
349 
350 
367  SITK_RETURN_SELF_TYPE_HEADER SetOptimizerAsExhaustive( const std::vector<unsigned int> &numberOfSteps,
368  double stepLength = 1.0 );
369 
374  SITK_RETURN_SELF_TYPE_HEADER SetOptimizerAsAmoeba(double simplexDelta,
375  unsigned int numberOfIterations,
376  double parametersConvergenceTolerance=1e-8,
377  double functionConvergenceTolerance=1e-4,
378  bool withRestarts = false );
379 
391  SITK_RETURN_SELF_TYPE_HEADER SetOptimizerWeights(const std::vector<double> &weights);
392  std::vector<double> GetOptimizerWeights( ) const;
399  SITK_RETURN_SELF_TYPE_HEADER SetOptimizerAsPowell(unsigned int numberOfIterations = 100,
400  unsigned int maximumLineIterations = 100,
401  double stepLength = 1,
402  double stepTolerance = 1e-6,
403  double valueTolerance = 1e-6 );
404 
413  SITK_RETURN_SELF_TYPE_HEADER SetOptimizerAsOnePlusOneEvolutionary(unsigned int numberOfIterations = 100,
414  double epsilon = 1.5e-4,
415  double initialRadius = 1.01,
416  double growthFactor = -1.0,
417  double shrinkFactor = -1.0,
418  unsigned int seed = sitkWallClock);
419 
420 
421 
423  SITK_RETURN_SELF_TYPE_HEADER SetOptimizerScales( const std::vector<double> &scales );
424 
431  SITK_RETURN_SELF_TYPE_HEADER SetOptimizerScalesFromJacobian( unsigned int centralRegionRadius = 5 );
432 
438  SITK_RETURN_SELF_TYPE_HEADER SetOptimizerScalesFromIndexShift( unsigned int centralRegionRadius = 5,
439  double smallParameterVariation = 0.01 );
440 
447  SITK_RETURN_SELF_TYPE_HEADER SetOptimizerScalesFromPhysicalShift( unsigned int centralRegionRadius = 5,
448  double smallParameterVariation = 0.01 );
449 
450 
460  SITK_RETURN_SELF_TYPE_HEADER SetMetricFixedMask( const Image &binaryMask );
461 
471  SITK_RETURN_SELF_TYPE_HEADER SetMetricMovingMask( const Image &binaryMask );
472 
491  SITK_RETURN_SELF_TYPE_HEADER SetMetricSamplingPercentage(double percentage, unsigned int seed = sitkWallClock);
492  SITK_RETURN_SELF_TYPE_HEADER SetMetricSamplingPercentagePerLevel(const std::vector<double> &percentage, unsigned int seed = sitkWallClock);
496  const std::vector<double> &GetMetricSamplingPercentagePerLevel() const;
497 
501  RANDOM
502  };
503 
508  SITK_RETURN_SELF_TYPE_HEADER SetMetricSamplingStrategy( MetricSamplingStrategyType strategy);
509 
519  SITK_RETURN_SELF_TYPE_HEADER SetMetricUseFixedImageGradientFilter(bool);
520  SITK_RETURN_SELF_TYPE_HEADER MetricUseFixedImageGradientFilterOn() {return this->SetMetricUseFixedImageGradientFilter(true);}
521  SITK_RETURN_SELF_TYPE_HEADER MetricUseFixedImageGradientFilterOff() {return this->SetMetricUseFixedImageGradientFilter(false);}
535  SITK_RETURN_SELF_TYPE_HEADER SetMetricUseMovingImageGradientFilter(bool);
536  SITK_RETURN_SELF_TYPE_HEADER MetricUseMovingImageGradientFilterOn() {return this->SetMetricUseMovingImageGradientFilter(true);}
537  SITK_RETURN_SELF_TYPE_HEADER MetricUseMovingImageGradientFilterOff() {return this->SetMetricUseMovingImageGradientFilter(false);}
548  SITK_RETURN_SELF_TYPE_HEADER SetShrinkFactorsPerLevel( const std::vector<unsigned int> &shrinkFactors );
549 
558  SITK_RETURN_SELF_TYPE_HEADER SetSmoothingSigmasPerLevel( const std::vector<double> &smoothingSigmas );
559 
566  SITK_RETURN_SELF_TYPE_HEADER SetSmoothingSigmasAreSpecifiedInPhysicalUnits(bool arg);
567  SITK_RETURN_SELF_TYPE_HEADER SmoothingSigmasAreSpecifiedInPhysicalUnitsOn() { this->SetSmoothingSigmasAreSpecifiedInPhysicalUnits(true); return *this;}
568  SITK_RETURN_SELF_TYPE_HEADER SmoothingSigmasAreSpecifiedInPhysicalUnitsOff() { this->SetSmoothingSigmasAreSpecifiedInPhysicalUnits(false); return *this;}
573  Transform Execute ( const Image &fixed, const Image & moving );
574 
575 
585  double MetricEvaluate( const Image &fixed, const Image & moving );
586 
587 
594  unsigned int GetOptimizerIteration() const;
595  std::vector<double> GetOptimizerPosition() const;
596  double GetOptimizerLearningRate() const;
597  double GetOptimizerConvergenceValue() const;
598  double GetMetricValue() const;
599 
608  uint64_t GetMetricNumberOfValidPoints() const;
609 
610 
611  unsigned int GetCurrentLevel() const;
612 
620  std::vector<double> GetOptimizerScales() const;
621 
624  std::string GetOptimizerStopConditionDescription() const;
625 
626  protected:
627 
628  template<class TImage>
629  Transform ExecuteInternal ( const Image &fixed, const Image &moving );
630 
631  template<class TImage>
632  double EvaluateInternal ( const Image &fixed, const Image &moving );
633 
634 
635  itk::ObjectToObjectOptimizerBaseTemplate<double> *CreateOptimizer( unsigned int numberOfTransformParameters );
636 
637  template<unsigned int VDimension>
638  itk::SpatialObject<VDimension> *CreateSpatialObjectMask(const Image &mask);
639 
640  template <class TImageType>
641  itk::ImageToImageMetricv4<TImageType,
642  TImageType,
643  TImageType,
644  double,
646  >* CreateMetric( );
647 
648  template <class TImageType>
649  void SetupMetric(
650  itk::ImageToImageMetricv4<TImageType,
651  TImageType,
652  TImageType,
653  double,
655  >*, const TImageType*, const TImageType* );
656 
657  template <typename TMetric>
659 
660  template <typename TTransformAdaptorPointer, typename TRegistrationMethod >
661  std::vector< TTransformAdaptorPointer >
662  CreateTransformParametersAdaptor(
663  TRegistrationMethod* method);
664 
665  virtual void PreUpdate( itk::ProcessObject *p );
666  virtual void OnActiveProcessDelete( ) SITK_NOEXCEPT;
667  virtual unsigned long AddITKObserver(const itk::EventObject &, itk::Command *);
668  virtual void RemoveITKObserver( EventCommand &e );
669 
670  private:
671 
672  nsstd::function<unsigned int()> m_pfGetOptimizerIteration;
673  nsstd::function<std::vector<double>()> m_pfGetOptimizerPosition;
674  nsstd::function<double()> m_pfGetOptimizerLearningRate;
675  nsstd::function<double()> m_pfGetOptimizerConvergenceValue;
676  nsstd::function<double()> m_pfGetMetricValue;
677  nsstd::function<uint64_t()> m_pfGetMetricNumberOfValidPoints;
678  nsstd::function<std::vector<double>()> m_pfGetOptimizerScales;
679  nsstd::function<std::string()> m_pfGetOptimizerStopConditionDescription;
680 
681 
682  nsstd::function<unsigned int()> m_pfGetCurrentLevel;
683 
684  nsstd::function<void (itk::TransformBase *outTransform)> m_pfUpdateWithBestValue;
685 
686  template < class TMemberFunctionPointer >
688  {
689  typedef typename ::detail::FunctionTraits<TMemberFunctionPointer>::ClassType ObjectType;
690 
691  template< typename TImageType >
692  TMemberFunctionPointer operator() ( void ) const
693  {
694  return &ObjectType::template EvaluateInternal< TImageType >;
695  }
696  };
697 
698  typedef Transform (ImageRegistrationMethod::*MemberFunctionType)( const Image &fixed, const Image &moving );
699  typedef double (ImageRegistrationMethod::*EvaluateMemberFunctionType)( const Image &fixed, const Image &moving );
700  friend struct detail::MemberFunctionAddressor<MemberFunctionType>;
701  nsstd::auto_ptr<detail::MemberFunctionFactory<MemberFunctionType> > m_MemberFactory;
702  nsstd::auto_ptr<detail::MemberFunctionFactory<EvaluateMemberFunctionType> > m_EvaluateMemberFactory;
703 
709 
710  std::vector<uint32_t> m_VirtualDomainSize;
711  std::vector<double> m_VirtualDomainOrigin;
712  std::vector<double> m_VirtualDomainSpacing;
713  std::vector<double> m_VirtualDomainDirection;
714 
715  // optimizer
716  enum OptimizerType { ConjugateGradientLineSearch,
725  LBFGS2
726  };
748  std::vector<unsigned int> m_OptimizerNumberOfSteps;
761  unsigned int m_OptimizerSeed;
770 
771 
772  std::vector<unsigned int> m_TransformBSplineScaleFactors;
773 
774  std::vector<double> m_OptimizerWeights;
775 
780  PhysicalShift
781  };
783  std::vector<double> m_OptimizerScales;
786 
787  // metric
788  enum MetricType { ANTSNeighborhoodCorrelation,
793  MattesMutualInformation
794  };
796  unsigned int m_MetricRadius;
800 
803 
804  std::vector<double> m_MetricSamplingPercentage;
806  unsigned int m_MetricSamplingSeed;
807 
810 
811  std::vector<unsigned int> m_ShrinkFactorsPerLevel;
812  std::vector<double> m_SmoothingSigmasPerLevel;
814 
817  unsigned int m_Iteration;
819 
821  };
822 
823 }
824 }
825 
826 #endif // sitkImageRegistrationMethod_h
std::vector< unsigned int > m_OptimizerNumberOfSteps
Never run estimation, use provided value.
Self & SetFixedInitialTransform(const Transform &transform)
Set transform mapping to the fixed domain.
STL namespace.
std::vector< unsigned int > m_ShrinkFactorsPerLevel
Transform GetInitialTransform()
Set the initial transform and parameters to optimize.
itk::ObjectToObjectOptimizerBaseTemplate< double > * m_ActiveOptimizer
#define SITKRegistration_EXPORT
::detail::FunctionTraits< TMemberFunctionPointer >::ClassType ObjectType
Self & SetInterpolator(InterpolatorEnum Interpolator)
Set and get the interpolator to use.
std::vector< unsigned int > m_TransformBSplineScaleFactors
An interface method to the modular ITKv4 registration framework.
nsstd::auto_ptr< detail::MemberFunctionFactory< MemberFunctionType > > m_MemberFactory
Transform GetMovingInitialTransform() const
Set a fixed transform component towards moving domain.
An implementation of the Command design pattern for callback.
Definition: sitkCommand.h:44
A simplified wrapper around a variety of ITK transforms.
Definition: sitkTransform.h:84
Self & SmoothingSigmasAreSpecifiedInPhysicalUnitsOff()
Enable the smoothing sigmas for each level in physical units (default) or in terms of voxels...
A deformable transform over a bounded spatial domain using a BSpline representation for a 2D or 3D co...
Self & MetricUseFixedImageGradientFilterOff()
Enable image gradient computation by a filter.
Self & MetricUseMovingImageGradientFilterOff()
Enable image gradient computation by a filter.
The Image class for SimpleITK.
Definition: sitkImage.h:78
Self & MetricUseFixedImageGradientFilterOn()
Enable image gradient computation by a filter.
#define SITK_NOEXCEPT
Definition: sitkMacro.h:68
Self & MetricUseMovingImageGradientFilterOn()
Enable image gradient computation by a filter.
bool GetInitialTransformInPlace() const
Set the initial transform and parameters to optimize.
Self & SetMovingInitialTransform(const Transform &transform)
Set a fixed transform component towards moving domain.
Estimate learning once each level, ignore provided values.
Self & SmoothingSigmasAreSpecifiedInPhysicalUnitsOn()
Enable the smoothing sigmas for each level in physical units (default) or in terms of voxels...
Base class for SimpleITK classes based on ProcessObject.
Transform GetFixedInitialTransform() const
Set transform mapping to the fixed domain.
class ITK_FORWARD_EXPORT Command
nsstd::auto_ptr< detail::MemberFunctionFactory< EvaluateMemberFunctionType > > m_EvaluateMemberFactory
InterpolatorEnum GetInterpolator()
Set and get the interpolator to use.
::uint64_t uint64_t
EstimateLearningRateType m_OptimizerEstimateLearningRate