itkImageToImageMetric.h

Go to the documentation of this file.

/*=========================================================================
 *
 *  Copyright Insight Software Consortium
 *
 *  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
 *
 *         http://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"

namespace itk
{
template< typename TFixedImage,  typename TMovingImage >
class ITK_TEMPLATE_EXPORT ImageToImageMetric:
  public SingleValuedCostFunction
{
public:
  ITK_DISALLOW_COPY_AND_ASSIGN(ImageToImageMetric);

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

  using CoordinateRepresentationType = typename Superclass::ParametersValueType;

  itkTypeMacro(ImageToImageMetric, SingleValuedCostFunction);

  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 MeasureType = typename Superclass::MeasureType;

  using DerivativeType = typename Superclass::DerivativeType;

  using ParametersType = 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);

  itkSetObjectMacro(MovingImageMask, MovingImageMaskType);
  itkSetConstObjectMacro(MovingImageMask, MovingImageMaskType);
  itkGetConstObjectMacro(MovingImageMask, MovingImageMaskType);

  itkSetObjectMacro(FixedImageMask, FixedImageMaskType);
  itkSetConstObjectMacro(FixedImageMask, FixedImageMaskType);
  itkGetConstObjectMacro(FixedImageMask, FixedImageMaskType);

  void SetFixedImageIndexes(const FixedImageIndexContainer & indexes);

  void SetUseFixedImageIndexes(bool useIndex);

  itkGetConstReferenceMacro(UseFixedImageIndexes, bool);

  void SetNumberOfWorkUnits(ThreadIdType numberOfThreads);
  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 sequentialSampling);

  itkGetConstReferenceMacro(UseSequentialSampling, bool);

  void ReinitializeSeed();
  void ReinitializeSeed(int seed);

  itkSetMacro(UseCachingOfBSplineWeights, bool);
  itkGetConstReferenceMacro(UseCachingOfBSplineWeights, bool);
  itkBooleanMacro(UseCachingOfBSplineWeights);

  using MultiThreaderType = MultiThreaderBase;
  itkGetModifiableObjectMacro(Threader, MultiThreaderType);
  const TransformPointer * GetThreaderTransform()
  {
    return m_ThreaderTransform;
  }

protected:
  ImageToImageMetric();
  ~ImageToImageMetric() override;

  void PrintSelf(std::ostream & os, Indent indent) const override;

  class FixedImageSamplePoint
  {
public:
    FixedImageSamplePoint()
    {
      point.Fill(0.0);
      value = 0;
      valueIndex = 0;
    }

    ~FixedImageSamplePoint() = default;

public:
    FixedImagePointType point;
    double              value;
    unsigned int        valueIndex;
  };

  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;

  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;

  bool m_TransformIsBSpline{false};

  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 BSplineTransformWeightsType    *m_ThreaderBSplineTransformWeights;
  mutable BSplineTransformIndexArrayType *m_ThreaderBSplineTransformIndices;

  virtual void PreComputeTransformValues();

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

  virtual void TransformPointWithDerivatives(unsigned int sampleNumber,
                                             MovingImagePointType & mappedPoint,
                                             bool & sampleWithinSupportRegion,
                                             double & movingImageValue,
                                             ImageDerivativesType & gradient,
                                             ThreadIdType threadId) const;

  bool m_InterpolatorIsBSpline{false};

  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 }
    {}
    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 typename MultiThreaderType::WorkUnitInfo *>( workunitInfoAsVoid )}
    {  }
    ThreadIdType GetThreadId() const { return m_WorkUnitInfo->WorkUnitID; }
    const ImageToImageMetric * GetConstImageToImageMetricPointer() const
    {
      return (static_cast<ConstantPointerWrapper *>( m_WorkUnitInfo ->UserData))->GetConstMetricPointer();
    }
  private:
    const typename MultiThreaderType::WorkUnitInfo *m_WorkUnitInfo;
  };

  MultiThreaderType::Pointer m_Threader;
  ConstantPointerWrapper *   m_ConstSelfWrapper;
  mutable unsigned int *     m_ThreaderNumberOfMovingImageSamples{nullptr};
  bool                       m_WithinThreadPreProcess{false};
  bool                       m_WithinThreadPostProcess{false};

  void                           GetValueMultiThreadedInitiate() const;

  void                           GetValueMultiThreadedPostProcessInitiate() const;

  static ITK_THREAD_RETURN_FUNCTION_CALL_CONVENTION  GetValueMultiThreaded(void *arg);

  static ITK_THREAD_RETURN_FUNCTION_CALL_CONVENTION  GetValueMultiThreadedPostProcess(void *arg);

  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 *arg);

  static ITK_THREAD_RETURN_FUNCTION_CALL_CONVENTION GetValueAndDerivativeMultiThreadedPostProcess(void *arg);

  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