itkImageRegistrationMethodv4.h

Go to the documentation of this file.

/*=========================================================================
 *
 *  Copyright NumFOCUS
 *
 *  Licensed under the Apache License, Version 2.0 (the "License");
 *  you may not use this file except in compliance with the License.
 *  You may obtain a copy of the License at
 *
 *         https://www.apache.org/licenses/LICENSE-2.0.txt
 *
 *  Unless required by applicable law or agreed to in writing, software
 *  distributed under the License is distributed on an "AS IS" BASIS,
 *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 *  See the License for the specific language governing permissions and
 *  limitations under the License.
 *
 *=========================================================================*/
#ifndef itkImageRegistrationMethodv4_h
#define itkImageRegistrationMethodv4_h
 
#include "itkProcessObject.h"
 
#include "itkCompositeTransform.h"
#include "itkDataObjectDecorator.h"
#include "itkObjectToObjectMetricBase.h"
#include "itkObjectToObjectMultiMetricv4.h"
#include "itkObjectToObjectOptimizerBase.h"
#include "itkImageToImageMetricv4.h"
#include "itkPointSetToPointSetMetricWithIndexv4.h"
#include "itkShrinkImageFilter.h"
#include "itkIdentityTransform.h"
#include "itkTransformParametersAdaptorBase.h"
#include "ITKRegistrationMethodsv4Export.h"
 
#include <vector>
 
namespace itk
{
class ImageRegistrationMethodv4Enums
{
public:
  enum class MetricSamplingStrategy : uint8_t
  {
    NONE,
    REGULAR,
    RANDOM
  };
};
// Define how to print enumeration
extern ITKRegistrationMethodsv4_EXPORT std::ostream &
operator<<(std::ostream & out, const ImageRegistrationMethodv4Enums::MetricSamplingStrategy value);

template <typename TFixedImage,
          typename TMovingImage,
          typename TOutputTransform = Transform<double, TFixedImage::ImageDimension, TFixedImage::ImageDimension>,
          typename TVirtualImage = TFixedImage,
          typename TPointSet = PointSet<unsigned int, TFixedImage::ImageDimension>>
class ITK_TEMPLATE_EXPORT ImageRegistrationMethodv4 : public ProcessObject
{
public:
  ITK_DISALLOW_COPY_AND_MOVE(ImageRegistrationMethodv4);

  using Self = ImageRegistrationMethodv4;
  using Superclass = ProcessObject;
  using Pointer = SmartPointer<Self>;
  using ConstPointer = SmartPointer<const Self>;

  itkNewMacro(Self);

  static constexpr unsigned int ImageDimension = TFixedImage::ImageDimension;

  itkOverrideGetNameOfClassMacro(ImageRegistrationMethodv4);

  using FixedImageType = TFixedImage;
  using FixedImagePointer = typename FixedImageType::Pointer;
  using FixedImageConstPointer = typename FixedImageType::ConstPointer;
  using FixedImagesContainerType = std::vector<FixedImageConstPointer>;
  using MovingImageType = TMovingImage;
  using MovingImagePointer = typename MovingImageType::Pointer;
  using MovingImageConstPointer = typename MovingImageType::ConstPointer;
  using MovingImagesContainerType = std::vector<MovingImageConstPointer>;
 
  using PointSetType = TPointSet;
  using PointSetConstPointer = typename PointSetType::ConstPointer;
  using PointSetsContainerType = std::vector<PointSetConstPointer>;

  using OutputTransformType = TOutputTransform;
  using OutputTransformPointer = typename OutputTransformType::Pointer;
  using RealType = typename OutputTransformType::ScalarType;
  using DerivativeType = typename OutputTransformType::DerivativeType;
  using DerivativeValueType = typename DerivativeType::ValueType;
 
  using InitialTransformType = Transform<RealType, ImageDimension, ImageDimension>;
  using InitialTransformPointer = typename InitialTransformType::Pointer;
 
  using CompositeTransformType = CompositeTransform<RealType, ImageDimension>;
  using CompositeTransformPointer = typename CompositeTransformType::Pointer;
 
  using MetricType = ObjectToObjectMetricBaseTemplate<RealType>;
  using MetricPointer = typename MetricType::Pointer;
 
  using VectorType = Vector<RealType, ImageDimension>;
 
  using VirtualImageType = TVirtualImage;
  using VirtualImagePointer = typename VirtualImageType::Pointer;
  using VirtualImageBaseType = ImageBase<ImageDimension>;
  using VirtualImageBaseConstPointer = typename VirtualImageBaseType::ConstPointer;
 
  using MultiMetricType = ObjectToObjectMultiMetricv4<ImageDimension, ImageDimension, VirtualImageType, RealType>;
  using ImageMetricType = ImageToImageMetricv4<FixedImageType, MovingImageType, VirtualImageType, RealType>;
  using PointSetMetricType = PointSetToPointSetMetricWithIndexv4<PointSetType, PointSetType, RealType>;
 
  using FixedImageMaskType = typename ImageMetricType::FixedImageMaskType;
  using FixedImageMaskConstPointer = typename FixedImageMaskType::ConstPointer;
  using FixedImageMasksContainerType = std::vector<FixedImageMaskConstPointer>;
  using MovingImageMaskType = typename ImageMetricType::MovingImageMaskType;
  using MovingImageMaskConstPointer = typename MovingImageMaskType::ConstPointer;
  using MovingImageMasksContainerType = std::vector<MovingImageMaskConstPointer>;

  using DecoratedOutputTransformType = DataObjectDecorator<OutputTransformType>;
  using DecoratedOutputTransformPointer = typename DecoratedOutputTransformType::Pointer;
  using DecoratedInitialTransformType = DataObjectDecorator<InitialTransformType>;
  using DecoratedInitialTransformPointer = typename DecoratedInitialTransformType::Pointer;
 
  using ShrinkFilterType = ShrinkImageFilter<FixedImageType, VirtualImageType>;
  using ShrinkFactorsPerDimensionContainerType = typename ShrinkFilterType::ShrinkFactorsType;
 
  using ShrinkFactorsArrayType = Array<SizeValueType>;
 
  using SmoothingSigmasArrayType = Array<RealType>;
  using MetricSamplingPercentageArrayType = Array<RealType>;

  using TransformParametersAdaptorType = TransformParametersAdaptorBase<InitialTransformType>;
  using TransformParametersAdaptorPointer = typename TransformParametersAdaptorType::Pointer;
  using TransformParametersAdaptorsContainerType = std::vector<TransformParametersAdaptorPointer>;

  using OptimizerType = ObjectToObjectOptimizerBaseTemplate<RealType>;
  using OptimizerPointer = typename OptimizerType::Pointer;

  using OptimizerWeightsType = typename OptimizerType::ScalesType;
 
  using MetricSamplingStrategyEnum = ImageRegistrationMethodv4Enums::MetricSamplingStrategy;
#if !defined(ITK_LEGACY_REMOVE)
  using MetricSamplingStrategyType = MetricSamplingStrategyEnum;
  static constexpr MetricSamplingStrategyEnum NONE = MetricSamplingStrategyEnum::NONE;
  static constexpr MetricSamplingStrategyEnum REGULAR = MetricSamplingStrategyEnum::REGULAR;
  static constexpr MetricSamplingStrategyEnum RANDOM = MetricSamplingStrategyEnum::RANDOM;
#endif
 
 
  using MetricSamplePointSetType = typename ImageMetricType::FixedSampledPointSetType;

  virtual void
  SetFixedImage(const FixedImageType * image)
  {
    this->SetFixedImage(0, image);
  }
  virtual const FixedImageType *
  GetFixedImage() const
  {
    return this->GetFixedImage(0);
  }
  virtual void
                                 SetFixedImage(SizeValueType, const FixedImageType *);
  virtual const FixedImageType * GetFixedImage(SizeValueType) const;

  virtual void
  SetMovingImage(const MovingImageType * image)
  {
    this->SetMovingImage(0, image);
  }
  virtual const MovingImageType *
  GetMovingImage() const
  {
    return this->GetMovingImage(0);
  }
  virtual void
                                  SetMovingImage(SizeValueType, const MovingImageType *);
  virtual const MovingImageType * GetMovingImage(SizeValueType) const;

  virtual void
  SetFixedPointSet(const PointSetType * pointSet)
  {
    this->SetFixedPointSet(0, pointSet);
  }
  virtual const PointSetType *
  GetFixedPointSet() const
  {
    return this->GetFixedPointSet(0);
  }
  virtual void
                               SetFixedPointSet(SizeValueType, const PointSetType *);
  virtual const PointSetType * GetFixedPointSet(SizeValueType) const;

  virtual void
  SetMovingPointSet(const PointSetType * pointSet)
  {
    this->SetMovingPointSet(0, pointSet);
  }
  virtual const PointSetType *
  GetMovingPointSet() const
  {
    return this->GetMovingPointSet(0);
  }
  virtual void
                               SetMovingPointSet(SizeValueType, const PointSetType *);
  virtual const PointSetType * GetMovingPointSet(SizeValueType) const;

  itkSetObjectMacro(Optimizer, OptimizerType);
  itkGetModifiableObjectMacro(Optimizer, OptimizerType);

  void
  SetOptimizerWeights(OptimizerWeightsType &);
  itkGetConstMacro(OptimizerWeights, OptimizerWeightsType);

  itkSetObjectMacro(Metric, MetricType);
  itkGetModifiableObjectMacro(Metric, MetricType);

  itkSetEnumMacro(MetricSamplingStrategy, MetricSamplingStrategyEnum);
  itkGetEnumMacro(MetricSamplingStrategy, MetricSamplingStrategyEnum);

  void
  MetricSamplingReinitializeSeed();
  void
  MetricSamplingReinitializeSeed(int seed);

  void
  SetMetricSamplingPercentage(const RealType);

  virtual void
  SetMetricSamplingPercentagePerLevel(const MetricSamplingPercentageArrayType & samplingPercentages);
  itkGetConstMacro(MetricSamplingPercentagePerLevel, MetricSamplingPercentageArrayType);

  itkSetGetDecoratedObjectInputMacro(FixedInitialTransform, InitialTransformType);

  itkSetGetDecoratedObjectInputMacro(MovingInitialTransform, InitialTransformType);

  itkSetGetDecoratedObjectInputMacro(InitialTransform, InitialTransformType);

  void
  SetTransformParametersAdaptorsPerLevel(TransformParametersAdaptorsContainerType &);
  const TransformParametersAdaptorsContainerType &
  GetTransformParametersAdaptorsPerLevel() const;

  void
  SetNumberOfLevels(const SizeValueType);
  itkGetConstMacro(NumberOfLevels, SizeValueType);

  void
  SetShrinkFactorsPerLevel(ShrinkFactorsArrayType factors)
  {
    for (unsigned int level = 0; level < factors.Size(); ++level)
    {
      auto shrinkFactors = MakeFilled<ShrinkFactorsPerDimensionContainerType>(factors[level]);
      this->SetShrinkFactorsPerDimension(level, shrinkFactors);
    }
  }


  ShrinkFactorsPerDimensionContainerType
  GetShrinkFactorsPerDimension(const unsigned int level) const
  {
    if (level >= this->m_ShrinkFactorsPerLevel.size())
    {
      itkExceptionMacro("Requesting level greater than the number of levels.");
    }
    return this->m_ShrinkFactorsPerLevel[level];
  }


  void
  SetShrinkFactorsPerDimension(unsigned int level, ShrinkFactorsPerDimensionContainerType factors)
  {
    if (level >= this->m_ShrinkFactorsPerLevel.size())
    {
      this->m_ShrinkFactorsPerLevel.resize(level + 1);
    }
    this->m_ShrinkFactorsPerLevel[level] = factors;
    this->Modified();
  }


  itkSetMacro(SmoothingSigmasPerLevel, SmoothingSigmasArrayType);
  itkGetConstMacro(SmoothingSigmasPerLevel, SmoothingSigmasArrayType);

  itkSetMacro(SmoothingSigmasAreSpecifiedInPhysicalUnits, bool);
  itkGetConstMacro(SmoothingSigmasAreSpecifiedInPhysicalUnits, bool);
  itkBooleanMacro(SmoothingSigmasAreSpecifiedInPhysicalUnits);

  using DataObjectPointerArraySizeType = ProcessObject::DataObjectPointerArraySizeType;
  using Superclass::MakeOutput;
  DataObjectPointer MakeOutput(DataObjectPointerArraySizeType) override;

  virtual DecoratedOutputTransformType *
  GetOutput();
  virtual const DecoratedOutputTransformType *
  GetOutput() const;
 
  virtual DecoratedOutputTransformType *
  GetTransformOutput()
  {
    return this->GetOutput();
  }
  virtual const DecoratedOutputTransformType *
  GetTransformOutput() const
  {
    return this->GetOutput();
  }
 
  virtual OutputTransformType *
  GetModifiableTransform();
  virtual const OutputTransformType *
  GetTransform() const;

  itkGetConstMacro(CurrentLevel, SizeValueType);

  itkGetConstReferenceMacro(CurrentIteration, SizeValueType);
 
  /* Get the current metric value.  This is a helper function for reporting observations. */
  itkGetConstReferenceMacro(CurrentMetricValue, RealType);

  itkGetConstReferenceMacro(CurrentConvergenceValue, RealType);

  itkGetConstReferenceMacro(IsConverged, bool);

  itkSetMacro(InPlace, bool);
  itkGetConstMacro(InPlace, bool);
  itkBooleanMacro(InPlace);

  itkBooleanMacro(InitializeCenterOfLinearOutputTransform);
  itkSetMacro(InitializeCenterOfLinearOutputTransform, bool);
  itkGetConstMacro(InitializeCenterOfLinearOutputTransform, bool);

  void
  InitializeCenterOfLinearOutputTransform();
 
protected:
  ImageRegistrationMethodv4();
  ~ImageRegistrationMethodv4() override = default;
  void
  PrintSelf(std::ostream & os, Indent indent) const override;

  void
  GenerateData() override;
 
  virtual void
  AllocateOutputs();

  virtual void
  InitializeRegistrationAtEachLevel(const SizeValueType);

  virtual VirtualImageBaseConstPointer
  GetCurrentLevelVirtualDomainImage();

  virtual void
  SetMetricSamplePoints();
 
  SizeValueType m_CurrentLevel{};
  SizeValueType m_NumberOfLevels{ 0 };
  SizeValueType m_CurrentIteration{};
  RealType      m_CurrentMetricValue{};
  RealType      m_CurrentConvergenceValue{};
  bool          m_IsConverged{};
 
  FixedImagesContainerType      m_FixedSmoothImages{};
  MovingImagesContainerType     m_MovingSmoothImages{};
  FixedImageMasksContainerType  m_FixedImageMasks{};
  MovingImageMasksContainerType m_MovingImageMasks{};
  VirtualImagePointer           m_VirtualDomainImage{};
  PointSetsContainerType        m_FixedPointSets{};
  PointSetsContainerType        m_MovingPointSets{};
  SizeValueType                 m_NumberOfFixedObjects{};
  SizeValueType                 m_NumberOfMovingObjects{};
 
  OptimizerPointer     m_Optimizer{};
  OptimizerWeightsType m_OptimizerWeights{};
  bool                 m_OptimizerWeightsAreIdentity{};
 
  MetricPointer                                       m_Metric{};
  MetricSamplingStrategyEnum                          m_MetricSamplingStrategy{};
  MetricSamplingPercentageArrayType                   m_MetricSamplingPercentagePerLevel{};
  SizeValueType                                       m_NumberOfMetrics{};
  int                                                 m_FirstImageMetricIndex{};
  std::vector<ShrinkFactorsPerDimensionContainerType> m_ShrinkFactorsPerLevel{};
  SmoothingSigmasArrayType                            m_SmoothingSigmasPerLevel{};
  bool                                                m_SmoothingSigmasAreSpecifiedInPhysicalUnits{};
 
  bool m_ReseedIterator{};
  int  m_RandomSeed{};
  int  m_CurrentRandomSeed{};
 
 
  TransformParametersAdaptorsContainerType m_TransformParametersAdaptorsPerLevel{};
 
  CompositeTransformPointer m_CompositeTransform{};
 
  // TODO: m_OutputTransform should be removed and replaced with a named input parameter for
  //      the pipeline
  OutputTransformPointer m_OutputTransform{};
 
 
private:
  bool m_InPlace{};
 
  bool m_InitializeCenterOfLinearOutputTransform{};
 
  // helper function to create the right kind of concrete transform
  template <typename TTransform>
  static void
  MakeOutputTransform(SmartPointer<TTransform> & ptr)
  {
    ptr = TTransform::New();
  }
 
  static void
  MakeOutputTransform(SmartPointer<InitialTransformType> & ptr)
  {
    ptr = IdentityTransform<RealType, ImageDimension>::New().GetPointer();
  }
};
} // end namespace itk
 
#ifndef ITK_MANUAL_INSTANTIATION
#  include "itkImageRegistrationMethodv4.hxx"
#endif
 
#endif