<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE Change SYSTEM "https://itk.org/migrationv4/ITKMigration.dtd">

<!--**
**
** RenameGetJacobianInTransform.xml
**
** >>>>>>>>>>>>>>>>>>>>>>>>>>>>
** Please, make sure this file validates the following w3c test before committing it: http://validator.w3.org
**-->
<Change>
    <!--**
    ** Title for the online migration page
    **-->
    <Title>
      Rename GetJacobian In Transform
    </Title>

    <!--**
    ** The author of the change
    **-->
    <Author>
      Hans Johnson
    </Author>

    <!--**
    ** Date of creation for the XML document
    **-->
    <Date>
      2011-08-17
    </Date>

    <!--**
    ** Plain text description of the change
    ** Extracted from git commit messages
    **-->
    <Description>
      <![CDATA[
      BUG: Remove broken GetJacobian  (ITK-2621)
      There was an attempt to preserve the GetJacobian() api in a backwards
      compatible way, but the implementation had a few very negative effects
      that made migration to ITKv4 very confusing and error prone.

      The current solution moves those confusing run-time errors to
      compile time errors in ITKv4, and allows custom derived transforms
      to be written in a way that is both ITKv3 and ITKv4 compatible.

      A complete description of the problem is in the issue tracker.

      To make a Transform ITKv4 compliant only, replace GetJacobian()
      with ComputeJacobianWithRespectToParameters().

      To make a non-standard transform compliant with both ITKv3 and ITKv4,
      move the computation of the JacobianWithRespectToParameters from
      GetJacobian() to ComputeJacobianWithRespectToParameters()
      Then add the following delegation code for GetJacobian()

  // Compute the Jacobian in one position
  template< class TScalar, unsigned int NDimensions >
  const typename MyTransform< TScalar, NDimensions >
  ::JacobianType &
  MyTransform< TScalar, NDimensions >::GetJacobian(const InputPointType & p) const
  {
    JacobianType tmp;
    this->ComputeJacobianWithRespectToParameters( p, tmp );
    return tmp;
  }
      ]]>
    </Description>

    <!--**
    ** Sample code snippets
    ** Extracted from git diff of changed files in Examples and Testing
    **-->
    <SampleCode>
      <Old>
        <![CDATA[
        virtual const JacobianType & GetJacobian ( const InputPointType & p ) const
        {
           /* Start Jacobian Calculations */
           this->m_Jacobian = /* TransformSpecific Jacobian Computation Here */
           /* End Jacobian Calculations */
           return this->m_Jacobian;
        }
        ]]>
      </Old>

      <New>
        <![CDATA[
        virtual const JacobianType & GetJacobian ( const InputPointType & p ) const
        {
          JacobianType tmp;
          this->ComputeJacobianWithRespectToParameters( p, tmp );
          return tmp;
        }
        virtual void ComputeJacobianWithRespectToParameters( const InputPointType & p, JacobianType & jacobian ) const
        {
           jacobian.SetSize( NOutputDimensions, this->GetNumberOfLocalParameters() );
           /* Start Jacobian Calculations */
           jacobian.Fill(0);
           jacobian = /* TransformSpecific Jacobian Computation Here */
           /* End Jacobian Calculations */
        }
        ]]>
      </New>

    </SampleCode>
    <SampleCode>
      <Old>
        <![CDATA[
        /** Get Jacobian at a point. A very specialized function just for BSplines */
        virtual void GetJacobian( const InputPointType &, WeightsType &, ParameterIndexArrayType & ) const;
        ]]>
      </Old>

      <New>
        <![CDATA[
        /** Get Jacobian at a point. A very specialized function just for BSplines */
        virtual void ComputeJacobianFromBSplineWeightsWithRespectToPosition( const InputPointType &, WeightsType &,
                 ParameterIndexArrayType & ) const;
        ]]>
      </New>

    </SampleCode>

    <SampleCode>
      <Old>
        <![CDATA[
        MyCustomTransformITKV3(unsigned int outputDims, unsigned int paramDims);
        MyCustomTransformITKV3< TScalar, NDimensions >::MyCustomTransformITKV3():Superclass(SpaceDimension, ParametersDimension) {}
        MyCustomTransformITKV3< TScalar, NDimensions >::MyCustomTransformITKV3(unsigned int outputSpaceDimension, unsigned int parametersDimension):Superclass(outputSpaceDimension, parametersDimension) {}
        ]]>
      </Old>

      <New>
        <![CDATA[
        /* Thread safe transforms do not have an private mutable m_Jacobian variable, so there is no need to initialize the "SpaceDimension" of that variable. */
        MyCustomTransformITKV3(unsigned int paramDims);

        MyCustomTransformITKV3< TScalar, NDimensions >::MyCustomTransformITKV3()
#if ITK_VERSION_MAJOR >=4
        :Superclass(ParametersDimension)
#else
        /* Only needed to meet defunct ITKv3 API requirements that ensured non-thread-safety */
        :Superclass(SpaceDimension,ParametersDimension)
#endif
#if ITK_VERSION_MAJOR >=4
#else
        /* Only needed to meet defunct ITKv3 API requirements that ensured non-thread-safety */
        MyCustomTransformITKV3< TScalar, NDimensions >::MyCustomTransformITKV3(unsigned int outputSpaceDimension, unsigned int parametersDimension):Superclass(outputSpaceDimension, parametersDimension) {}
#endif

        ]]>
      </New>



    </SampleCode>

    <!--**
    ** The change-ids for all commits in the topic branch
    **-->
    <Gerrit-ChangeId>
    Change-Id: I7a55b04e97879946d4994f23d7a7f7451cd3f81a
    </Gerrit-ChangeId>

    <!--**
    ** List of all changed files from the topic branch
    **-->
    <FileList>
      Modules/Core/Transform/include/itkBSplineDeformableTransform.h
      Modules/Core/Transform/include/itkBSplineDeformableTransform.hxx
      Modules/Core/Transform/include/itkBSplineTransform.h
      Modules/Core/Transform/include/itkBSplineTransform.hxx
      Modules/Core/Transform/include/itkCenteredAffineTransform.h
      Modules/Core/Transform/include/itkCenteredAffineTransform.hxx
      Modules/Core/Transform/include/itkCenteredEuler3DTransform.h
      Modules/Core/Transform/include/itkCenteredEuler3DTransform.hxx
      Modules/Core/Transform/include/itkCenteredRigid2DTransform.h
      Modules/Core/Transform/include/itkCenteredRigid2DTransform.hxx
      Modules/Core/Transform/include/itkCenteredSimilarity2DTransform.h
      Modules/Core/Transform/include/itkCenteredSimilarity2DTransform.hxx
      Modules/Core/Transform/include/itkCompositeTransform.h
      Modules/Core/Transform/include/itkCompositeTransform.hxx
      Modules/Core/Transform/include/itkDisplacementFieldTransform.h
      Modules/Core/Transform/include/itkDisplacementFieldTransform.hxx
      Modules/Core/Transform/include/itkEuler3DTransform.h
      Modules/Core/Transform/include/itkEuler3DTransform.hxx
      Modules/Core/Transform/include/itkIdentityTransform.h
      Modules/Core/Transform/include/itkKernelTransform.h
      Modules/Core/Transform/include/itkKernelTransform.hxx
      Modules/Core/Transform/include/itkMatrixOffsetTransformBase.h
      Modules/Core/Transform/include/itkMatrixOffsetTransformBase.hxx
      Modules/Core/Transform/include/itkQuaternionRigidTransform.h
      Modules/Core/Transform/include/itkQuaternionRigidTransform.hxx
      Modules/Core/Transform/include/itkRigid2DTransform.h
      Modules/Core/Transform/include/itkRigid2DTransform.hxx
      Modules/Core/Transform/include/itkRigid3DPerspectiveTransform.h
      Modules/Core/Transform/include/itkRigid3DPerspectiveTransform.hxx
      Modules/Core/Transform/include/itkScaleLogarithmicTransform.h
      Modules/Core/Transform/include/itkScaleLogarithmicTransform.hxx
      Modules/Core/Transform/include/itkScaleSkewVersor3DTransform.h
      Modules/Core/Transform/include/itkScaleSkewVersor3DTransform.hxx
      Modules/Core/Transform/include/itkScaleTransform.h
      Modules/Core/Transform/include/itkScaleTransform.hxx
      Modules/Core/Transform/include/itkScaleVersor3DTransform.h
      Modules/Core/Transform/include/itkScaleVersor3DTransform.hxx
      Modules/Core/Transform/include/itkSimilarity2DTransform.h
      Modules/Core/Transform/include/itkSimilarity2DTransform.hxx
      Modules/Core/Transform/include/itkSimilarity3DTransform.h
      Modules/Core/Transform/include/itkSimilarity3DTransform.hxx
      Modules/Core/Transform/include/itkTransform.h
      Modules/Core/Transform/include/itkTranslationTransform.h
      Modules/Core/Transform/include/itkTranslationTransform.hxx
      Modules/Core/Transform/include/itkVersorRigid3DTransform.h
      Modules/Core/Transform/include/itkVersorRigid3DTransform.hxx
      Modules/Core/Transform/include/itkVersorTransform.h
      Modules/Core/Transform/include/itkVersorTransform.hxx
      Modules/Core/Transform/test/itkAffineTransformTest.cxx
      Modules/Core/Transform/test/itkBSplineDisplacementFieldTranformTest.cxx
      Modules/Core/Transform/test/itkBSplineTransformInitializerTest1.cxx
      Modules/Core/Transform/test/itkBSplineTransformTest.cxx
      Modules/Core/Transform/test/itkCenteredAffineTransformTest.cxx
      Modules/Core/Transform/test/itkCenteredEuler3DTransformTest.cxx
      Modules/Core/Transform/test/itkCenteredRigid2DTransformTest.cxx
      Modules/Core/Transform/test/itkCompositeTransformTest.cxx
      Modules/Core/Transform/test/itkEuler2DTransformTest.cxx
      Modules/Core/Transform/test/itkEuler3DTransformTest.cxx
      Modules/Core/Transform/test/itkIdentityTransformTest.cxx
      Modules/Core/Transform/test/itkQuaternionRigidTransformTest.cxx
      Modules/Core/Transform/test/itkScaleSkewVersor3DTransformTest.cxx
      Modules/Core/Transform/test/itkScaleVersor3DTransformTest.cxx
      Modules/Core/Transform/test/itkSimilarity2DTransformTest.cxx
      Modules/Core/Transform/test/itkSimilarity3DTransformTest.cxx
      Modules/Core/Transform/test/itkTransformTest.cxx
      Modules/Core/Transform/test/itkVersorRigid3DTransformTest.cxx
      Modules/Core/Transform/test/itkVersorTransformTest.cxx
      Modules/Registration/Common/include/itkMeanReciprocalSquareDifferencePointSetToImageMetric.hxx
      Modules/Registration/Common/include/itkMutualInformationImageToImageMetric.hxx
    </FileList>

    <!--**
    ** If the migration can be accomplished by a simple string
    ** substitution, then use the following construct to define
    ** the substitution rule.
    **
    ** <MigrationFix-Automatic>
    **   <Old>
    **     <![CDATA[MipsleledName]]>
    **   </Old>
    **   <New>
    **     <![CDATA[MisspelledName]]>
    **   </New>
    ** </MigrationFix-Automatic>
    **-->

    <!--**
    ** If the migration can NOT be accomplished by a simple string
    ** substitution, but potential problem spots can be identified,
    ** use the following construct to define a migration flag rule.
    **
    ** <MigrationFix-Manual>
    **   OldFunctionName
    ** </MigrationFix-Manual>
    **-->

</Change>
