itkImageToImageMetric.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 itkImageToImageMetric_h
#define itkImageToImageMetric_h
 
#include "itkBSplineBaseTransform.h"
#include "itkBSplineInterpolateImageFunction.h"
#include "itkSingleValuedCostFunction.h"
#include "itkGradientRecursiveGaussianImageFilter.h"
#include "itkSpatialObject.h"
#include "itkCentralDifferenceImageFunction.h"
#include "itkMultiThreaderBase.h"
 
#include <memory> // For unique_ptr.
 
namespace itk
{
 
template <typename TFixedImage, typename TMovingImage>
class ITK_TEMPLATE_EXPORT ImageToImageMetric : public SingleValuedCostFunction
{
public:
  ITK_DISALLOW_COPY_AND_MOVE(ImageToImageMetric);

  using Self = ImageToImageMetric;
  using Superclass = SingleValuedCostFunction;
  using Pointer = SmartPointer<Self>;
  using ConstPointer = SmartPointer<const Self>;

  using CoordinateRepresentationType = typename Superclass::ParametersValueType;

  itkOverrideGetNameOfClassMacro(ImageToImageMetric);

  using MovingImageType = TMovingImage;
  using MovingImagePixelType = typename TMovingImage::PixelType;
  using MovingImageConstPointer = typename MovingImageType::ConstPointer;

  using FixedImageType = TFixedImage;
  using FixedImagePixelType = typename TFixedImage::PixelType;
  using FixedImageConstPointer = typename FixedImageType::ConstPointer;
  using FixedImageRegionType = typename FixedImageType::RegionType;

  static constexpr unsigned int MovingImageDimension = TMovingImage::ImageDimension;
  static constexpr unsigned int FixedImageDimension = TFixedImage::ImageDimension;

  using TransformType = Transform<CoordinateRepresentationType, Self::MovingImageDimension, Self::FixedImageDimension>;
 
  using TransformPointer = typename TransformType::Pointer;
  using InputPointType = typename TransformType::InputPointType;
  using OutputPointType = typename TransformType::OutputPointType;
  using TransformParametersType = typename TransformType::ParametersType;
  using TransformJacobianType = typename TransformType::JacobianType;

  using FixedImageIndexType = typename FixedImageType::IndexType;
  using FixedImageIndexValueType = typename FixedImageIndexType::IndexValueType;
  using MovingImageIndexType = typename MovingImageType::IndexType;
  using FixedImagePointType = typename TransformType::InputPointType;
  using MovingImagePointType = typename TransformType::OutputPointType;
 
  using FixedImageIndexContainer = std::vector<FixedImageIndexType>;

  using InterpolatorType = InterpolateImageFunction<MovingImageType, CoordinateRepresentationType>;

  using RealType = typename NumericTraits<MovingImagePixelType>::RealType;
  using GradientPixelType = CovariantVector<RealType, Self::MovingImageDimension>;
  using GradientImageType = Image<GradientPixelType, Self::MovingImageDimension>;
  using GradientImagePointer = SmartPointer<GradientImageType>;
  using GradientImageFilterType = GradientRecursiveGaussianImageFilter<MovingImageType, GradientImageType>;
  using GradientImageFilterPointer = typename GradientImageFilterType::Pointer;
 
  using InterpolatorPointer = typename InterpolatorType::Pointer;

  using FixedImageMaskType = SpatialObject<Self::FixedImageDimension>;
  using FixedImageMaskPointer = typename FixedImageMaskType::Pointer;
  using FixedImageMaskConstPointer = typename FixedImageMaskType::ConstPointer;

  using MovingImageMaskType = SpatialObject<Self::MovingImageDimension>;
  using MovingImageMaskPointer = typename MovingImageMaskType::Pointer;
  using MovingImageMaskConstPointer = typename MovingImageMaskType::ConstPointer;

  using typename Superclass::MeasureType;

  using typename Superclass::DerivativeType;

  using typename Superclass::ParametersType;

  itkSetConstObjectMacro(FixedImage, FixedImageType);
  itkGetConstObjectMacro(FixedImage, FixedImageType);
  itkSetConstObjectMacro(MovingImage, MovingImageType);
  itkGetConstObjectMacro(MovingImage, MovingImageType);
  itkSetObjectMacro(Transform, TransformType);

  itkGetModifiableObjectMacro(Transform, TransformType);

  itkSetObjectMacro(Interpolator, InterpolatorType);

  itkGetModifiableObjectMacro(Interpolator, InterpolatorType);

  SizeValueType
  GetNumberOfMovingImageSamples()
  {
    return this->GetNumberOfPixelsCounted();
  }
 
  itkGetConstReferenceMacro(NumberOfPixelsCounted, SizeValueType);

  virtual void
  SetFixedImageRegion(const FixedImageRegionType reg);

  itkGetConstReferenceMacro(FixedImageRegion, FixedImageRegionType);

#ifndef ITK_FUTURE_LEGACY_REMOVE
  virtual void
  SetMovingImageMask(MovingImageMaskType * const arg)
  {
    const auto * const constArg = arg;
    // Call the overload defined by itkSetConstObjectMacro, or an override.
    this->SetMovingImageMask(constArg);
  }
#endif
  itkSetConstObjectMacro(MovingImageMask, MovingImageMaskType);
  itkGetConstObjectMacro(MovingImageMask, MovingImageMaskType);
#ifndef ITK_FUTURE_LEGACY_REMOVE
  virtual void
  SetFixedImageMask(FixedImageMaskType * const arg)
  {
    const auto * const constArg = arg;
    // Call the overload defined by itkSetConstObjectMacro, or an override.
    this->SetFixedImageMask(constArg);
  }
#endif
  itkSetConstObjectMacro(FixedImageMask, FixedImageMaskType);
  itkGetConstObjectMacro(FixedImageMask, FixedImageMaskType);
  void
  SetFixedImageIndexes(const FixedImageIndexContainer & indexes);
 
  void
  SetUseFixedImageIndexes(bool useIndexes);
 
  itkGetConstReferenceMacro(UseFixedImageIndexes, bool);

  void
  SetNumberOfWorkUnits(ThreadIdType numberOfWorkUnits);
  itkGetConstReferenceMacro(NumberOfWorkUnits, ThreadIdType);
  itkSetMacro(ComputeGradient, bool);
  itkGetConstReferenceMacro(ComputeGradient, bool);
  itkBooleanMacro(ComputeGradient);
  virtual void
  ComputeGradient();

  itkGetModifiableObjectMacro(GradientImage, GradientImageType);

  void
  SetTransformParameters(const ParametersType & parameters) const;

  unsigned int
  GetNumberOfParameters() const override
  {
    return m_Transform->GetNumberOfParameters();
  }

  virtual void
  Initialize();

  virtual void
  MultiThreadingInitialize();

  virtual void
  SetNumberOfFixedImageSamples(SizeValueType numSamples);
  itkGetConstReferenceMacro(NumberOfFixedImageSamples, SizeValueType);
  void
  SetNumberOfSpatialSamples(SizeValueType num)
  {
    this->SetNumberOfFixedImageSamples(num);
  }
 
  SizeValueType
  GetNumberOfSpatialSamples()
  {
    return this->GetNumberOfFixedImageSamples();
  }

  void
  SetFixedImageSamplesIntensityThreshold(const FixedImagePixelType & thresh);
 
  itkGetConstReferenceMacro(FixedImageSamplesIntensityThreshold, FixedImagePixelType);
 
  void
  SetUseFixedImageSamplesIntensityThreshold(bool useThresh);
 
  itkGetConstReferenceMacro(UseFixedImageSamplesIntensityThreshold, bool);

  void
  SetUseAllPixels(bool useAllPixels);
 
  void
  UseAllPixelsOn()
  {
    this->SetUseAllPixels(true);
  }
 
  void
  UseAllPixelsOff()
  {
    this->SetUseAllPixels(false);
  }
 
  itkGetConstReferenceMacro(UseAllPixels, bool);

  void
  SetUseSequentialSampling(bool useSequential);
 
  itkGetConstReferenceMacro(UseSequentialSampling, bool);

  void
  ReinitializeSeed();
  void
  ReinitializeSeed(int seed);
  itkSetMacro(UseCachingOfBSplineWeights, bool);
  itkGetConstReferenceMacro(UseCachingOfBSplineWeights, bool);
  itkBooleanMacro(UseCachingOfBSplineWeights);
 
#ifndef ITK_FUTURE_LEGACY_REMOVE
  using MultiThreaderType [[deprecated("Please use `itk::MultiThreaderBase` directly.")]] = MultiThreaderBase;
#endif

  itkGetModifiableObjectMacro(Threader, MultiThreaderBase);
  const TransformPointer *
  GetThreaderTransform()
  {
    return m_ThreaderTransform.get();
  }

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

  class FixedImageSamplePoint
  {
  public:
    FixedImageSamplePoint() { point.Fill(0.0); }
 
    ~FixedImageSamplePoint() = default;
 
    friend inline std::ostream &
    operator<<(std::ostream & os, const FixedImageSamplePoint & val)
    {
      os << "point: " << static_cast<typename NumericTraits<FixedImagePointType>::PrintType>(val.point) << std::endl;
      os << "value: " << val.value << std::endl;
      os << "valueIndex: " << val.valueIndex << std::endl;
 
      return os;
    }
 
  public:
    FixedImagePointType point;
    double              value{ 0 };
    unsigned int        valueIndex{ 0 };
  };
 
  bool                     m_UseFixedImageIndexes{ false };
  FixedImageIndexContainer m_FixedImageIndexes{};
 
  bool                m_UseFixedImageSamplesIntensityThreshold{ false };
  FixedImagePixelType m_FixedImageSamplesIntensityThreshold{};

  using FixedImageSampleContainer = std::vector<FixedImageSamplePoint>;

  virtual void
  SampleFixedImageRegion(FixedImageSampleContainer & samples) const;

  virtual void
  SampleFixedImageIndexes(FixedImageSampleContainer & samples) const;

  virtual void
  SampleFullFixedImageRegion(FixedImageSampleContainer & samples) const;

  FixedImageSampleContainer m_FixedImageSamples{};
 
  SizeValueType m_NumberOfParameters{ 0 };
 
  SizeValueType m_NumberOfFixedImageSamples{ 50000 };
  // m_NumberOfPixelsCounted must be mutable because the const
  // thread consolidation functions merge each work unit's values
  // onto this accumulator variable.
  mutable SizeValueType m_NumberOfPixelsCounted{ 0 };
 
  FixedImageConstPointer  m_FixedImage{};
  MovingImageConstPointer m_MovingImage{};

  TransformPointer m_Transform{};

  std::unique_ptr<TransformPointer[]> m_ThreaderTransform;
 
  InterpolatorPointer m_Interpolator{};
 
  bool                 m_ComputeGradient{ true };
  GradientImagePointer m_GradientImage{};
 
  FixedImageMaskConstPointer  m_FixedImageMask{};
  MovingImageMaskConstPointer m_MovingImageMask{};
 
  ThreadIdType m_NumberOfWorkUnits{ 1 };
 
  bool m_UseAllPixels{ false };
  bool m_UseSequentialSampling{ false };
 
  bool m_ReseedIterator{ false };
 
  mutable int m_RandomSeed{};

 
#ifndef ITK_FUTURE_LEGACY_REMOVE
  bool m_TransformIsBSpline{ false };
#endif

  SizeValueType m_NumBSplineWeights{ 0 };
 
  static constexpr unsigned int DeformationSplineOrder = 3;
 
  using BSplineTransformType =
    BSplineBaseTransform<CoordinateRepresentationType, FixedImageType::ImageDimension, Self::DeformationSplineOrder>;
 
  using BSplineTransformWeightsType = typename BSplineTransformType::WeightsType;
  using WeightsValueType = typename BSplineTransformWeightsType::ValueType;
  using BSplineTransformWeightsArrayType = Array2D<WeightsValueType>;
 
  using BSplineTransformIndexArrayType = typename BSplineTransformType::ParameterIndexArrayType;
  using IndexValueType = typename BSplineTransformIndexArrayType::ValueType;
  using BSplineTransformIndicesArrayType = Array2D<IndexValueType>;
 
  using MovingImagePointArrayType = std::vector<MovingImagePointType>;
  using BooleanArrayType = std::vector<bool>;
  using BSplineParametersOffsetType = FixedArray<SizeValueType, FixedImageType::ImageDimension>;
  using BSplineInterpolatorType = BSplineInterpolateImageFunction<MovingImageType, CoordinateRepresentationType>;

  using DerivativeFunctionType = CentralDifferenceImageFunction<MovingImageType, CoordinateRepresentationType>;
  using ImageDerivativesType = CovariantVector<double, Self::MovingImageDimension>;
 
  typename BSplineTransformType::Pointer m_BSplineTransform{};
 
  BSplineTransformWeightsArrayType m_BSplineTransformWeightsArray{};
  BSplineTransformIndicesArrayType m_BSplineTransformIndicesArray{};
  MovingImagePointArrayType        m_BSplinePreTransformPointsArray{};
  BooleanArrayType                 m_WithinBSplineSupportRegionArray{};
 
  BSplineParametersOffsetType m_BSplineParametersOffset{};
 
  // Variables needed for optionally caching values when using a BSpline
  // transform.
  bool                                   m_UseCachingOfBSplineWeights{ true };
  mutable BSplineTransformWeightsType    m_BSplineTransformWeights{};
  mutable BSplineTransformIndexArrayType m_BSplineTransformIndices{};
 
  mutable std::unique_ptr<BSplineTransformWeightsType[]>    m_ThreaderBSplineTransformWeights;
  mutable std::unique_ptr<BSplineTransformIndexArrayType[]> m_ThreaderBSplineTransformIndices;

  virtual void
  PreComputeTransformValues();

  virtual void
  TransformPoint(unsigned int           sampleNumber,
                 MovingImagePointType & mappedPoint,
                 bool &                 sampleOk,
                 double &               movingImageValue,
                 ThreadIdType           threadId) const;

  virtual void
  TransformPointWithDerivatives(unsigned int           sampleNumber,
                                MovingImagePointType & mappedPoint,
                                bool &                 sampleOk,
                                double &               movingImageValue,
                                ImageDerivativesType & movingImageGradient,
                                ThreadIdType           threadId) const;
 
#ifndef ITK_FUTURE_LEGACY_REMOVE
  bool m_InterpolatorIsBSpline{ false };
#endif

  typename BSplineInterpolatorType::Pointer m_BSplineInterpolator{};

  typename DerivativeFunctionType::Pointer m_DerivativeCalculator{};

  virtual void
  ComputeImageDerivatives(const MovingImagePointType & mappedPoint,
                          ImageDerivativesType &       gradient,
                          ThreadIdType                 threadId) const;


  class ConstantPointerWrapper final
  {
  public:
    ConstantPointerWrapper(ImageToImageMetric * i2i_metricPointer)
      : m_ConstMetricPointer{ i2i_metricPointer }
    {}
    [[nodiscard]] const ImageToImageMetric *
    GetConstMetricPointer() const
    {
      return m_ConstMetricPointer;
    }
 
  private:
    const ImageToImageMetric * m_ConstMetricPointer;
  };

  class MultiThreaderWorkUnitInfoImageToImageMetricWrapper final
  {
  public:
    MultiThreaderWorkUnitInfoImageToImageMetricWrapper(const void * workunitInfoAsVoid)
      : m_WorkUnitInfo(static_cast<const MultiThreaderBase::WorkUnitInfo *>(workunitInfoAsVoid))
    {}
    [[nodiscard]] ThreadIdType
    GetThreadId() const
    {
      return m_WorkUnitInfo->WorkUnitID;
    }
    [[nodiscard]] const ImageToImageMetric *
    GetConstImageToImageMetricPointer() const
    {
      return (static_cast<ConstantPointerWrapper *>(m_WorkUnitInfo->UserData))->GetConstMetricPointer();
    }
 
  private:
    const MultiThreaderBase::WorkUnitInfo * m_WorkUnitInfo;
  };
 
  MultiThreaderBase::Pointer              m_Threader{};
  std::unique_ptr<ConstantPointerWrapper> m_ConstSelfWrapper;
  mutable std::unique_ptr<unsigned int[]> m_ThreaderNumberOfMovingImageSamples;
  bool                                    m_WithinThreadPreProcess{ false };
  bool                                    m_WithinThreadPostProcess{ false };
 
  void
  GetValueMultiThreadedInitiate() const;
 
  void
  GetValueMultiThreadedPostProcessInitiate() const;

  static ITK_THREAD_RETURN_FUNCTION_CALL_CONVENTION
  GetValueMultiThreaded(void * workunitInfoAsVoid);

  static ITK_THREAD_RETURN_FUNCTION_CALL_CONVENTION
  GetValueMultiThreadedPostProcess(void * workunitInfoAsVoid);

  virtual inline void
  GetValueThread(ThreadIdType threadId) const;

  virtual inline void
  GetValueThreadPreProcess(ThreadIdType itkNotUsed(threadId), bool itkNotUsed(withinSampleThread)) const
  {}
  virtual inline bool
  GetValueThreadProcessSample(ThreadIdType                 itkNotUsed(threadId),
                              SizeValueType                itkNotUsed(fixedImageSample),
                              const MovingImagePointType & itkNotUsed(mappedPoint),
                              double                       itkNotUsed(movingImageValue)) const
  {
    return false;
  }
  virtual inline void
  GetValueThreadPostProcess(ThreadIdType itkNotUsed(threadId), bool itkNotUsed(withinSampleThread)) const
  {}

  void
  GetValueAndDerivativeMultiThreadedInitiate() const;
 
  void
  GetValueAndDerivativeMultiThreadedPostProcessInitiate() const;
 
  static ITK_THREAD_RETURN_FUNCTION_CALL_CONVENTION
  GetValueAndDerivativeMultiThreaded(void * workunitInfoAsVoid);
 
  static ITK_THREAD_RETURN_FUNCTION_CALL_CONVENTION
  GetValueAndDerivativeMultiThreadedPostProcess(void * workunitInfoAsVoid);
 
  virtual inline void
  GetValueAndDerivativeThread(ThreadIdType threadId) const;
 
  virtual inline void
  GetValueAndDerivativeThreadPreProcess(ThreadIdType itkNotUsed(threadId), bool itkNotUsed(withinSampleThread)) const
  {}
  virtual inline bool
  GetValueAndDerivativeThreadProcessSample(ThreadIdType                 itkNotUsed(threadId),
                                           SizeValueType                itkNotUsed(fixedImageSample),
                                           const MovingImagePointType & itkNotUsed(mappedPoint),
                                           double                       itkNotUsed(movingImageValue),
                                           const ImageDerivativesType & itkNotUsed(movingImageGradientValue)) const
  {
    return false;
  }
  virtual inline void
  GetValueAndDerivativeThreadPostProcess(ThreadIdType itkNotUsed(threadId), bool itkNotUsed(withinSampleThread)) const
  {}

  virtual void
  SynchronizeTransforms() const;
 
private:
  FixedImageRegionType m_FixedImageRegion{};
};
} // end namespace itk
 
#ifndef ITK_MANUAL_INSTANTIATION
#  include "itkImageToImageMetric.hxx"
#endif
 
#endif