itkTransform.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 itkTransform_h
#define itkTransform_h
 
#include <type_traits> // For std::enable_if
#include "itkTransformBase.h"
#include "itkVector.h"
#include "itkSymmetricSecondRankTensor.h"
#include "itkDiffusionTensor3D.h"
#include "itkVariableLengthVector.h"
#include "vnl/vnl_vector_fixed.h"
#include "vnl/vnl_matrix_fixed.h"
#include "itkMatrix.h"
#include "itkImageBase.h"
 
namespace itk
{
template <typename TParametersValueType, unsigned int VInputDimension = 3, unsigned int VOutputDimension = 3>
class ITK_TEMPLATE_EXPORT Transform : public TransformBaseTemplate<TParametersValueType>
{
public:
  ITK_DISALLOW_COPY_AND_MOVE(Transform);

  using Self = Transform;
  using Superclass = TransformBaseTemplate<TParametersValueType>;
  using Pointer = SmartPointer<Self>;
  using ConstPointer = SmartPointer<const Self>;

  itkOverrideGetNameOfClassMacro(Transform);

  static constexpr unsigned int InputSpaceDimension = VInputDimension;
  static constexpr unsigned int OutputSpaceDimension = VOutputDimension;

  itkCloneMacro(Self);

  unsigned int
  GetInputSpaceDimension() const override
  {
    return VInputDimension;
  }

  unsigned int
  GetOutputSpaceDimension() const override
  {
    return VOutputDimension;
  }

  using typename Superclass::FixedParametersType;
  using typename Superclass::FixedParametersValueType;
  using typename Superclass::ParametersType;
  using typename Superclass::ParametersValueType;
  using DerivativeType = Array<ParametersValueType>;

  using ScalarType = ParametersValueType;

  using JacobianType = Array2D<ParametersValueType>;
  using JacobianPositionType = vnl_matrix_fixed<ParametersValueType, VOutputDimension, VInputDimension>;
  using InverseJacobianPositionType = vnl_matrix_fixed<ParametersValueType, VInputDimension, VOutputDimension>;

  using InputVectorType = Vector<TParametersValueType, VInputDimension>;
  using OutputVectorType = Vector<TParametersValueType, VOutputDimension>;

  using InputVectorPixelType = VariableLengthVector<TParametersValueType>;
  using OutputVectorPixelType = VariableLengthVector<TParametersValueType>;
 
  /* Standard symmetric second rank tensor type for this class */
  using InputSymmetricSecondRankTensorType = SymmetricSecondRankTensor<TParametersValueType, VInputDimension>;
  using OutputSymmetricSecondRankTensorType = SymmetricSecondRankTensor<TParametersValueType, VOutputDimension>;
 
  /* Standard tensor type for this class */
  using InputDiffusionTensor3DType = DiffusionTensor3D<TParametersValueType>;
  using OutputDiffusionTensor3DType = DiffusionTensor3D<TParametersValueType>;

  using InputCovariantVectorType = CovariantVector<TParametersValueType, VInputDimension>;
  using OutputCovariantVectorType = CovariantVector<TParametersValueType, VOutputDimension>;

  using InputVnlVectorType = vnl_vector_fixed<TParametersValueType, VInputDimension>;
  using OutputVnlVectorType = vnl_vector_fixed<TParametersValueType, VOutputDimension>;

  using InputPointType = Point<TParametersValueType, VInputDimension>;
  using OutputPointType = Point<TParametersValueType, VOutputDimension>;

  using InverseTransformBaseType = Transform<TParametersValueType, VOutputDimension, VInputDimension>;
 
  using InverseTransformBasePointer = typename InverseTransformBaseType::Pointer;
 
  using MatrixType = Matrix<TParametersValueType, Self::OutputSpaceDimension, Self::InputSpaceDimension>;
 
  using OutputDirectionMatrix = Matrix<double, Self::OutputSpaceDimension, Self::OutputSpaceDimension>;
  using InputDirectionMatrix = Matrix<double, Self::InputSpaceDimension, Self::InputSpaceDimension>;
  using DirectionChangeMatrix = Matrix<double, Self::OutputSpaceDimension, Self::InputSpaceDimension>;
 
  using typename Superclass::NumberOfParametersType;

  virtual OutputPointType
  TransformPoint(const InputPointType &) const = 0;

  virtual OutputVectorType
  TransformVector(const InputVectorType &) const
  {
    itkExceptionMacro("TransformVector(const InputVectorType &)is unimplemented for " << this->GetNameOfClass());
  }

  virtual OutputVectorType
  TransformVector(const InputVectorType & vector, const InputPointType & point) const;

  virtual OutputVnlVectorType
  TransformVector(const InputVnlVectorType &) const
  {
    itkExceptionMacro("TransformVector( const InputVnlVectorType & ) is unimplemented for " << this->GetNameOfClass());
  }

  virtual OutputVnlVectorType
  TransformVector(const InputVnlVectorType & vector, const InputPointType & point) const;

  virtual OutputVectorPixelType
  TransformVector(const InputVectorPixelType & itkNotUsed(vector)) const
  {
    itkExceptionMacro("TransformVector( const InputVectorPixelType & ) is unimplemented for "
                      << this->GetNameOfClass());
  }

  virtual OutputVectorPixelType
  TransformVector(const InputVectorPixelType & vector, const InputPointType & point) const;

  virtual OutputCovariantVectorType
  TransformCovariantVector(const InputCovariantVectorType &) const
  {
    itkExceptionMacro("TransformCovariantVector( const InputCovariantVectorType & ) is unimplemented for "
                      << this->GetNameOfClass());
  }

  virtual OutputCovariantVectorType
  TransformCovariantVector(const InputCovariantVectorType & vector, const InputPointType & point) const;
 

  virtual OutputVectorPixelType
  TransformCovariantVector(const InputVectorPixelType & itkNotUsed(vector)) const
  {
    itkExceptionMacro("TransformCovariantVector(const InputVectorPixelType &)is unimplemented for "
                      << this->GetNameOfClass());
  }

  virtual OutputVectorPixelType
  TransformCovariantVector(const InputVectorPixelType & vector, const InputPointType & point) const;

  virtual OutputDiffusionTensor3DType
  TransformDiffusionTensor3D(const InputDiffusionTensor3DType & itkNotUsed(tensor)) const
  {
    itkExceptionMacro("TransformDiffusionTensor3D( const InputDiffusionTensor3DType & ) is unimplemented for "
                      << this->GetNameOfClass());
  }

  virtual OutputDiffusionTensor3DType
  TransformDiffusionTensor3D(const InputDiffusionTensor3DType & inputTensor, const InputPointType & point) const;

  virtual OutputVectorPixelType
  TransformDiffusionTensor3D(const InputVectorPixelType & itkNotUsed(tensor)) const
  {
    itkExceptionMacro("TransformDiffusionTensor( const InputVectorPixelType & ) is unimplemented for "
                      << this->GetNameOfClass());
  }
 
  virtual OutputVectorPixelType
  TransformDiffusionTensor3D(const InputVectorPixelType & inputTensor, const InputPointType & point) const;

  virtual OutputSymmetricSecondRankTensorType
  TransformSymmetricSecondRankTensor(const InputSymmetricSecondRankTensorType & inputTensor,
                                     const InputPointType &                     point) const;

  virtual OutputSymmetricSecondRankTensorType
  TransformSymmetricSecondRankTensor(const InputSymmetricSecondRankTensorType & itkNotUsed(tensor)) const
  {
    itkExceptionMacro(
      "TransformSymmetricSecondRankTensor( const InputSymmetricSecondRankTensorType & ) is unimplemented for "
      << this->GetNameOfClass());
  }

  virtual OutputVectorPixelType
  TransformSymmetricSecondRankTensor(const InputVectorPixelType & itkNotUsed(tensor)) const
  {
    itkExceptionMacro("TransformSymmetricSecondRankTensor( const InputVectorPixelType & ) is unimplemented for "
                      << this->GetNameOfClass());
  }

  virtual OutputVectorPixelType
  TransformSymmetricSecondRankTensor(const InputVectorPixelType & inputTensor, const InputPointType & point) const;

  void
  SetParameters(const ParametersType &) override = 0;

  void
  SetParametersByValue(const ParametersType & p) override
  {
    this->SetParameters(p);
  }

  void
  CopyInParameters(const ParametersValueType * const begin, const ParametersValueType * const end) override;

  void
  CopyInFixedParameters(const FixedParametersValueType * const begin,
                        const FixedParametersValueType * const end) override;

  const ParametersType &
  GetParameters() const override
  {
    return m_Parameters;
  }

  void
  SetFixedParameters(const FixedParametersType &) override = 0;

  const FixedParametersType &
  GetFixedParameters() const override
  {
    return m_FixedParameters;
  }

  virtual void
  UpdateTransformParameters(const DerivativeType & update, ParametersValueType factor = 1.0);

   *  the number of image dimensions. If it is an affine transform, this will
   *  be the same as the GetNumberOfParameters().
   */
  virtual NumberOfParametersType
  GetNumberOfLocalParameters() const
  {
    return this->GetNumberOfParameters();
  }

  NumberOfParametersType
  GetNumberOfParameters() const override
  {
    return this->m_Parameters.Size();
  }

  virtual NumberOfParametersType
  GetNumberOfFixedParameters() const
  {
    return this->m_FixedParameters.Size();
  }

  bool
  GetInverse(Self * itkNotUsed(inverseTransform)) const
  {
    return false;
  }

  virtual InverseTransformBasePointer
  GetInverseTransform() const
  {
    return nullptr;
  }

  std::string
  GetTransformTypeAsString() const override;
 
  using typename Superclass::TransformCategoryEnum;

  TransformCategoryEnum
  GetTransformCategory() const override
  {
    return Superclass::TransformCategoryEnum::UnknownTransformCategory;
  }
 
  virtual bool
  IsLinear() const
  {
    return this->GetTransformCategory() == Superclass::TransformCategoryEnum::Linear;
  }

  virtual void
  ComputeJacobianWithRespectToParameters(const InputPointType & itkNotUsed(p),
                                         JacobianType &         itkNotUsed(jacobian)) const = 0;
 
  virtual void
  ComputeJacobianWithRespectToParametersCachedTemporaries(const InputPointType & p,
                                                          JacobianType &         jacobian,
                                                          JacobianType &         itkNotUsed(cachedJacobian)) const
  {
    // NOTE: default implementation is not optimized, and just falls back to original methods.
    this->ComputeJacobianWithRespectToParameters(p, jacobian);
  }
 

  virtual void
  ComputeJacobianWithRespectToPosition(const InputPointType & itkNotUsed(x),
                                       JacobianPositionType & itkNotUsed(jacobian)) const
  {
    itkExceptionMacro("ComputeJacobianWithRespectToPosition( InputPointType, JacobianType ) is unimplemented for "
                      << this->GetNameOfClass());
  }
 
#if !defined(ITK_LEGACY_REMOVE)
  itkLegacyMacro(virtual void ComputeJacobianWithRespectToPosition(const InputPointType & x, JacobianType & jacobian)
                   const;)
#endif

  virtual void
  ComputeInverseJacobianWithRespectToPosition(const InputPointType & pnt, InverseJacobianPositionType & jacobian) const;
 
#if !defined(ITK_LEGACY_REMOVE)
  itkLegacyMacro(virtual void ComputeInverseJacobianWithRespectToPosition(const InputPointType & x,
                                                                          JacobianType &         jacobian) const;)
#endif

#if defined(ITK_WRAPPING_PARSER) || defined(SWIG_VERSION)
  // This variant replaces a compile time error with a runtime error.
  // It is therefore suitable to only be available for wrapping.
  void
  ApplyToImageMetadata(ImageBase<VInputDimension> * image) const
  {
    if (VInputDimension != VOutputDimension)
    {
      itkExceptionMacro("ApplyToImageMetadata is only usable with transforms with equal input and output dimensions."
                        " This class is: "
                        << this->GetNameOfClass());
    }
    this->ApplyToImageMetadataInternal(image);
  }
#else
  // These two variants are only available in C++.
  // In case of different input and output dimensions, compile error will be produced.
  template <typename TImage>
  std::enable_if_t<TImage::ImageDimension == VInputDimension && TImage::ImageDimension == VOutputDimension, void>
  ApplyToImageMetadata(TImage * image) const
  {
    this->ApplyToImageMetadataInternal(image);
  }
  template <typename TImage>
  std::enable_if_t<TImage::ImageDimension == VInputDimension && TImage::ImageDimension == VOutputDimension, void>
  ApplyToImageMetadata(SmartPointer<TImage> image) const
  {
    this->ApplyToImageMetadataInternal(image.GetPointer());
  }
#endif
 
protected:
  LightObject::Pointer
  InternalClone() const override;

  Transform() = default;
 
  Transform(NumberOfParametersType numberOfParameters);
  ~Transform() override = default;
 
  mutable ParametersType      m_Parameters{};
  mutable FixedParametersType m_FixedParameters{};
 
  OutputDiffusionTensor3DType
  PreservationOfPrincipalDirectionDiffusionTensor3DReorientation(const InputDiffusionTensor3DType &,
                                                                 const InverseJacobianPositionType &) const;

  template <typename TTransform>
  static InverseTransformBasePointer
  InvertTransform(const TTransform & transform)
  {
    const auto inverse = TTransform::New();
    return transform.GetInverse(inverse) ? inverse.GetPointer() : nullptr;
  }
 
private:
  void
  ApplyToImageMetadataInternal(ImageBase<VInputDimension> * image) const;
 
  template <typename TType>
  static std::string
  GetTransformTypeAsString(TType *)
  {
    std::string rval("other");
 
    return rval;
  }
 
  static std::string
  GetTransformTypeAsString(float *)
  {
    std::string rval("float");
 
    return rval;
  }
 
  static std::string
  GetTransformTypeAsString(double *)
  {
    std::string rval("double");
 
    return rval;
  }
};
} // end namespace itk
 
#ifndef ITK_MANUAL_INSTANTIATION
#  include "itkTransform.hxx"
#endif
 
#endif