ITK Release 4/Users Migration Guide/Migration Guide XML Samples

From KitwarePublic
Jump to navigationJump to search

Sample Files

The wiki is not particularly friendly about uploading xml documents (security issue I think), so the following page shows two examples directly.

Format Specification

Example 1 - Move GetLength and SetLength from MeasurementVectorTraits to NumericTraits

<?xml version="1.0" encoding="UTF-8"?>

<!--***************************************************************************
**
** MoveGetSetLengthMeasurementVectorTraits.xml
**
** This file provides a sample of an ITKv4 Migration guide XML document. The
** goal of these documents is to encode all information about changes to the
** ITK API between the v3.X releases and v4.0. Each migration document consists
** of a single <Change> element and a set of associated child elements. The
** <Change> element has a set of required child elements and a set of
** additional optional child elements which can be used to automatically
** identify locations in user code where the API change will mandate updates.
** In the case of simple changes, these rules can be used to automatically fix
** user code with the migration tool.
**
** REQUIRED CHILD ELEMENTS:
**
**    - <Title>: Title of the guide page for publication.
**
**    - <Description>: English description of what changes were made along with
**      rational for making them.
**
**    - <SampleCode>: Code snippet either manually written or automatically
**      harvested from the patch's changes that illustrates how to update the
**      API from the old version to the new version. This element must contain
**      two child elements, <Old> and <New>. As their names suggest, these two
**      elements contain the snippets of old API code and new API code .
**
**    - <FileList>: A list of all files that were changed in association with
**      the API change. File names should be specified relative to the base
**      source directory for ITK.
**
**    - <Gerrit-ChangeId>: This element links the API change to the Gerrit
**      entry used to review the change.
**
** OPTIONAL CHILD ELEMENTS:
**
**    - <ApplicationFixLink>: A link to git changes made when fixing
**      sequestered applications that broke due to the API change.
**
**    - <MigrationFix-Automatic>: A rule for the migration tool that can
**      automatically fix errors in user code. The current list of automatic
**      fix types is:
**
**      - "FileRename": Find and replace the file name with the new one. Must
**        include <Old> and <New> child elements.
**
**      - "ClassRename": Find and replace the name of a class. Must include
**        <Old> and <New> child elements.
**
**      - "ClassMove": Include the new location of the class. Must include
**        <Old> and <New> child elements. Will warn the user that the old
**        include file may be able to be removed but will not automatically
**        remove it.
**
**      - "MethodRename": Find and replace the name of the method. Must include
**        <Old> and <New> child elements.
**
**      - "MethodMove": Find and replace the name of a method. Only works if
**        the method's signature hasn't changed. Must include <Old> and <New>
**        child elements.
**
**      - "NamespaceChange": Find object from the old namespace and update its
**        namespace. This may not fix instances where "using namespace" is used
**        so the migration tool should warn the user wherever the object's
**        signature is found without a namespace attached. Must include <Old>
**        and <New> child elements.
**
**    - <MigrationFix-Manual>: A rule for the migration tool that can not be
**      automatcally fixed, but can be automatically identified. These rules
**      will cause the migration tool to flag a section of the code for
**      revision. The current type list is:
**
**      - "MethodRefactor": Flag the user anywhere the changed method is
**        called. Should be used any time a method's signature changes. Must
**        include an <Old> child element.
**
**      - "GeneralRefactor": Flag the user anywhere that the text specified in
**        the <Old> child element is found.
**
****************************************************************************-->

<Change>

  <!--
  ** Title for the published page
  **-->
  <Title>
  Move GetLength and SetLength Functions from MeasurementVectorTraits to NumericTraits
  </Title>

  <!--
  ** English language description of what was changed and why
  **-->
  <Description>
  In an attempt to consolidate the numeric traits api, we are moving all
  functionality from Code/Numerics/Statistics/itkMeasurementVectorTraits.h into
  the individual NumericTraits files in Code/Common.
  </Description>

  <!--
  ** Sample code to illustrate the fix process
  **-->
  <SampleCode>
    <OldCode>
    MeasurementVectorType mv;
    MeasurementVectorTraits::SetLength( mv, 3 );
    unsigned int length = MeasurementVectorTraits::GetLength( mv );
    </OldCode>

    <NewCode>
    MeasurementVectorType mv;
    NumericTraits&lt;MeasurementVectorType&gt;::SetLength( mv, 3 );
    unsigned int length = NumericTraits&lt;MeasurementVectorType&gt;::GetLength( mv );
    </NewCode>
  </SampleCode>

  <!--
  ** List of all files that were changed (might be automatically populated by
  ** git hook?)
  **-->
  <FileList>
  Code/Common/itkNumericTraitsArrayPixel.h
  Code/Common/itkNumericTraitsCovariantVectorPixel.h
  Code/Common/itkNumericTraitsDiffusionTensor3DPixel.h
  Code/Common/itkNumericTraitsFixedArrayPixel.h
  Code/Common/itkNumericTraitsPointPixel.h
  Code/Common/itkNumericTraitsRGBAPixel.h
  Code/Common/itkNumericTraitsRGBPixel.h
  Code/Common/itkNumericTraitsStdVector.h
  Code/Common/itkNumericTraitsTensorPixel.h
  Code/Common/itkNumericTraitsVariableLengthVectorPixel.h
  Code/Common/itkNumericTraitsVectorPixel.h
  Code/Numerics/Statistics/itkCovarianceSampleFilter.txx
  Code/Numerics/Statistics/itkDistanceMetric.h
  Code/Numerics/Statistics/itkDistanceMetric.txx
  Code/Numerics/Statistics/itkEuclideanDistanceMetric.txx
  Code/Numerics/Statistics/itkEuclideanSquareDistanceMetric.txx
  Code/Numerics/Statistics/itkExpectationMaximizationMixtureModelEstimator.txx
  Code/Numerics/Statistics/itkGaussianMembershipFunction.txx
  Code/Numerics/Statistics/itkGaussianMixtureModelComponent.txx
  Code/Numerics/Statistics/itkImageToListSampleFilter.txx
  Code/Numerics/Statistics/itkKdTree.txx
  Code/Numerics/Statistics/itkKdTreeBasedKmeansEstimator.h
  Code/Numerics/Statistics/itkKdTreeBasedKmeansEstimator.txx
  Code/Numerics/Statistics/itkKdTreeGenerator.txx
  Code/Numerics/Statistics/itkListSample.txx
  Code/Numerics/Statistics/itkMahalanobisDistanceMetric.txx
  Code/Numerics/Statistics/itkManhattanDistanceMetric.txx
  Code/Numerics/Statistics/itkMeasurementVectorTraits.h
  Code/Numerics/Statistics/itkMembershipFunctionBase.h
  Code/Numerics/Statistics/itkSample.h
  Code/Numerics/Statistics/itkSampleToHistogramFilter.txx
  Code/Numerics/Statistics/itkScalarImageToHistogramGenerator.txx
  Code/Numerics/Statistics/itkStandardDeviationPerComponentSampleFilter.txx
  Code/Numerics/Statistics/itkStatisticsAlgorithm.txx
  Code/Numerics/Statistics/itkWeightedCentroidKdTreeGenerator.txx
  Code/Numerics/Statistics/itkWeightedCovarianceSampleFilter.txx
  Testing/Code/Numerics/Statistics/CMakeLists.txt
  Testing/Code/Numerics/Statistics/itkDistanceToCentroidMembershipFunctionTest.cxx
  Testing/Code/Numerics/Statistics/itkEuclideanDistanceMetricTest.cxx
  Testing/Code/Numerics/Statistics/itkEuclideanSquareDistanceMetricTest.cxx
  Testing/Code/Numerics/Statistics/itkGaussianMembershipFunctionTest.cxx
  Testing/Code/Numerics/Statistics/itkListSampleTest.cxx
  Testing/Code/Numerics/Statistics/itkMahalanobisDistanceMetricTest.cxx
  Testing/Code/Numerics/Statistics/itkManhattanDistanceMetricTest.cxx
  Testing/Code/Numerics/Statistics/itkMembershipSampleTest1.cxx
  Testing/Code/Numerics/Statistics/itkMembershipSampleTest2.cxx
  Testing/Code/Numerics/Statistics/itkMembershipSampleTest3.cxx
  Testing/Code/Numerics/Statistics/itkMembershipSampleTest4.cxx
  Testing/Code/Numerics/Statistics/itkSampleClassifierFilterTest1.cxx
  Testing/Code/Numerics/Statistics/itkSampleClassifierFilterTest2.cxx
  Testing/Code/Numerics/Statistics/itkSampleClassifierFilterTest3.cxx
  Testing/Code/Numerics/Statistics/itkSampleClassifierFilterTest4.cxx
  Testing/Code/Numerics/Statistics/itkSampleClassifierFilterTest5.cxx
  Testing/Code/Numerics/Statistics/itkSampleClassifierFilterTest6.cxx
  Testing/Code/Numerics/Statistics/itkStatisticsTests.cxx
  Testing/Code/Numerics/Statistics/itkWeightedCentroidKdTreeGeneratorTest8.cxx
  Testing/Code/Numerics/Statistics/itkWeightedCentroidKdTreeGeneratorTest9.cxx
  Testing/Code/Numerics/Statistics/itkWeightedCovarianceSampleFilterTest2.cxx
  </FileList>

  <!--
  ** The asociated Gerrit entry for this API change
  **-->
  <Gerrit-ChangeId>
  Ie78170c85c29a5d030e5ab605610878fe67d75c2
  </Gerrit-ChangeId>


  <!--
  ** Migration guide rules
  **-->
  <MigrationFix-Manual type="MethodRefactor">
    <Old>
    MeasurementVectorTraits::GetLength
    </Old>
  </MigrationFix-Manual>

  <MigrationFix-Manual type="MethodRefactor">
    <Old>
    MeasurementVectorTraits::SetLength
    </Old>
  </MigrationFix-Manual>


</Change>

Example 2 - Improve Attribute Names for Label Objects

<?xml version="1.0" encoding="UTF-8"?>

<!--***************************************************************************
**
** MoveGetSetLengthMeasurementVectorTraits.xml
**
** This is the second sample Migration Guide XML document. For full details,
** see MoveGetSetLengthMeasurementVectorTraits.xml. One aditional required
** element has been added which is <Title>. This will be used for the title of
** the migration guide page.
**
****************************************************************************-->

<Change>

  <!--
  ** Title for the published page
  **-->
  <Title>
  Improve Attribute Names for Labels
  </Title>

  <!--
  ** English language description of what was changed and why
  **-->
  <Description>
  This change updates the attribute names for the LabelObject system.  The
  changes are:

  BinaryElongation        -> Elongation
  BinaryFlatness          -> Flatness
  BinaryPrincipalMoments  -> PrincipalMoments
  BinaryPrincipalAxes     -> PrincipalAxes
  Elongation              -> WeightedElongation
  EquivalentEllipsoidSize -> EquivalentEllipsoidDiameter
  EquivalentPerimeter     -> EquivalentSphericalPerimeter
  EquivalentRadius        -> EquivalentSphericalRadius
  Flatness                -> WeightedFlatness
  PhysicalSizeOnBorder    -> PerimeterOnBorder
  Region                  -> BoundingBox
  PrincipalAxes           -> WeightedPrincipalAxes
  PrincipalMoments        -> WeightedPrincipalMoments
  Sigma                   -> StandardDeviation
  Size                    -> NumberOfPixels
  SizeOnBorder            -> NumberOfPixelsOnBorder
  </Description>

  <!--
  ** Sample code to illustrate the fix process
  **-->
  <SampleCode>
    <OldCode>
    typedef ShapeLabelObject LabelObjectType;
    LabelObjectType::Pointer labelObject;
    LabelObjectType::RegionType region = labelObject->GetRegion();
    </OldCode>

    <NewCode>
    typedef TLabelObject LabelObjectType;
    LabelObjectType::Pointer labelObject;
    LabelObjectType::RegionType region = labelObject->GetBoundingBox();
    </NewCode>
  </SampleCode>

  <!--
  ** List of all files that were changed (might be automatically populated by
  ** git hook?)
  **-->
  <FileList>
  Code/Review/itkBinaryFillholeImageFilter.txx
  Code/Review/itkBinaryGrindPeakImageFilter.txx
  Code/Review/itkBinaryShapeKeepNObjectsImageFilter.txx
  Code/Review/itkBinaryShapeOpeningImageFilter.txx
  Code/Review/itkLabelMapUtilities.h
  Code/Review/itkLabelShapeKeepNObjectsImageFilter.txx
  Code/Review/itkLabelShapeOpeningImageFilter.txx
  Code/Review/itkShapeKeepNObjectsLabelMapFilter.txx
  Code/Review/itkShapeLabelMapFilter.txx
  Code/Review/itkShapeLabelObject.h
  Code/Review/itkShapeLabelObjectAccessors.h
  Code/Review/itkShapeOpeningLabelMapFilter.txx
  Code/Review/itkShapeRelabelImageFilter.txx
  Code/Review/itkShapeRelabelLabelMapFilter.txx
  Code/Review/itkShapeUniqueLabelMapFilter.txx
  Code/Review/itkStatisticsLabelMapFilter.txx
  Code/Review/itkStatisticsLabelObject.h
  Code/Review/itkStatisticsLabelObjectAccessors.h
  Testing/Code/Review/itkAttributePositionLabelMapFilterTest1.cxx
  Testing/Code/Review/itkAttributeUniqueLabelMapFilterTest1.cxx
  Testing/Code/Review/itkLabelMapToAttributeImageFilterTest1.cxx
  Testing/Code/Review/itkShapeLabelObjectAccessorsTest1.cxx
  </FileList>

  <!--
  ** The asociated Gerrit entry for this API change
  **-->
  <Gerrit-ChangeId>
  Ib5bdca1cd1809490f1c5a0f991c7cc2714d33c70
  </Gerrit-ChangeId>


  <!--
  ** Migration tool rules
  **-->
  <MigrationFix-Manual>
  BinaryElongation
  </MigrationFix-Manual>

  <MigrationFix-Manual>
  BINARY_ELONGATION
  </MigrationFix-Manual>

  <MigrationFix-Manual>
  BinaryFlatness
  </MigrationFix-Manual>

  <MigrationFix-Manual>
  BINARY_FLATNESS
  </MigrationFix-Manual>

  <MigrationFix-Manual>
  BinaryPrincipalMoments
  </MigrationFix-Manual>

  <MigrationFix-Manual>
  BINARY_PRINCIPAL_MOMENTS
  </MigrationFix-Manual>

  <MigrationFix-Manual>
  BinaryPrincipalAxes
  </MigrationFix-Manual>

  <MigrationFix-Manual>
  BINARY_PRINCIPAL_AXES
  </MigrationFix-Manual>

  <MigrationFix-Manual>
  Elongation
  </MigrationFix-Manual>

  <MigrationFix-Manual>
  ELONGATION
  </MigrationFix-Manual>

  <MigrationFix-Manual>
  EquivalentEllipsoidSize
  </MigrationFix-Manual>

  <MigrationFix-Manual>
  EQUIVALENT_ELLIPSOID_SIZE
  </MigrationFix-Manual>

  <MigrationFix-Manual>
  EquivalentPerimeter
  </MigrationFix-Manual>

  <MigrationFix-Manual>
  EQUIVALENT_PERIMETER
  </MigrationFix-Manual>

  <MigrationFix-Manual>
  EquivalentRadius
  </MigrationFix-Manual>

  <MigrationFix-Manual>
  EQUIVALENT_RADIUS
  </MigrationFix-Manual>

  <MigrationFix-Manual>
  Flatness
  </MigrationFix-Manual>

  <MigrationFix-Manual>
  FLATNESS
  </MigrationFix-Manual>

  <MigrationFix-Manual>
  PhysicalSizeOnBorder
  </MigrationFix-Manual>

  <MigrationFix-Manual>
  PHYSICAL_SIZE_ON_BORDER
  </MigrationFix-Manual>

  <MigrationFix-Manual>
  Region
  </MigrationFix-Manual>

  <MigrationFix-Manual>
  REGION
  </MigrationFix-Manual>

  <MigrationFix-Manual>
  PrincipalAxes
  </MigrationFix-Manual>

  <MigrationFix-Manual>
  PRINCIPAL_AXES
  </MigrationFix-Manual>

  <MigrationFix-Manual>
  PrincipalMoments
  </MigrationFix-Manual>

  <MigrationFix-Manual>
  PRINCIPAL_MOMENTS
  </MigrationFix-Manual>

  <MigrationFix-Manual>
  Sigma
  </MigrationFix-Manual>

  <MigrationFix-Manual>
  SIGMA
  </MigrationFix-Manual>

  <MigrationFix-Manual>
  Size
  </MigrationFix-Manual>

  <MigrationFix-Manual>
  SIZE
  </MigrationFix-Manual>

  <MigrationFix-Manual>
  SizeOnBorder
  </MigrationFix-Manual>

  <MigrationFix-Manual>
  SIZE_ON_BORDER
  </MigrationFix-Manual>

</Change>