diff --git a/docs/source/building.rst b/docs/source/building.rst index e6d4a897b7..0b71a0bd7e 100644 --- a/docs/source/building.rst +++ b/docs/source/building.rst @@ -251,6 +251,7 @@ be the Release configuration, as such: Installation from Build Tree ---------------------------- +.. _python_installation: Python Installation ^^^^^^^^^^^^^^^^^^^ diff --git a/docs/source/migrationGuide2.0.rst b/docs/source/migrationGuide2.0.rst index 7947e0b396..cafa0941de 100644 --- a/docs/source/migrationGuide2.0.rst +++ b/docs/source/migrationGuide2.0.rst @@ -1,34 +1,69 @@ .. _lbl_migration_guide2.0: Migration Guide 2.0 -------------------- +=================== With the release of SimpleITK 2.0 there are changes to the interface and to the behaviour of some methods and classes. The intent of this document is to provide guidance on how to modify code so that it is compatible with SimpleITK 2.0. -DICOM reading -+++++++++++++ +This document will continue to evolve after the SimpleITK 2.0 release, consider reading the `latest `__ version. Contributions to update this document that share problems and solutions when updating to SimpleITK 2.0 are welcomed. -Changes to DICOM reading, due to SimpleITK's move from ITK 4.x to 5.x. Photomertic interpretation, tag 0028|0004, is now taken into account when reading the image. - 1. MOCHOROME1: previously intensity values loaded as is, now they are inverted. Code that previously inverted the intensities explicitly needs to be removed. - 2. Color images (e.g. YBR_FULL_422): Previously channels loaded as is, now they are converted to RGB. If previous code used the photometric interpretation tag value to perform color space conversions outside of SimpleITK it will need to be modified. For example, previously the first channel for an image with photometric interpretation of YBR_FULL was luminance and could be used as the grayscale version of the image. Now all three channels are used to compute the image luminance: +Interface Compatibility +----------------------- + +These changes list API changes that cause compilation or runtime errors. + + +Composite Transforms +++++++++++++++++++++ + +The `Transform::AddTransform` method was removed. + +Composite transformations were previously represented using the generic `Transform class `__. This class served both as a base class for all transformations and as a composite transformation. This dual purpose +has been separated. Composite transformations are now represented by a dedicated class `CompositeTransform `__ and the associated functionality was removed from the `Transform` class. + ++---------------------------------------------------+------------------------------------------------+ +| 1.x | 2.x | ++---------------------------------------------------+------------------------------------------------+ +| .. code-block:: python | .. code-block:: python | +| | | +| tx = sitk.Transform() | tx1 = sitk.TranslationTransform(3,(1,7,76)) | +| tx1 = sitk.TranslationTransform(3,(1,7,76)) | tx2 = sitk.Euler3DTransform() | +| tx2 = sitk.Euler3DTransform() | tx = sitk.CompositeTransform([tx1, tx2]) | +| tx.AddTransform(tx1) | | +| tx.AddTransform(tx2) | | ++---------------------------------------------------+------------------------------------------------+ + +This change does effect compatibility when reading or writing `CompositeTransforms` between versions. + -+----------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------+ -| 1.x | 2.x | -+----------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------+ -| .. code-block:: python | .. code-block:: python | -| | | -| | image = sitk.ReadImage(file_name) | -| | grayscale_image = sitk.Cast(sitk.RescaleIntensity(0.299*sitk.VectorIndexSelectionCast(image,0,sitk.sitkFloat32) + | -| image = sitk.ReadImage(file_name) | 0.587*sitk.VectorIndexSelectionCast(image,1,sitk.sitkFloat32) + | -| grayscale_image = sitk.VectorIndexSelectionCast(image,0)| 0.114*sitk.VectorIndexSelectionCast(image,0,sitk.sitkFloat32)), sitk.sitkUInt8)| -+----------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------+ +Filter's Execute Method ++++++++++++++++++++++++ +The Filters' `Execute` methods with filter parameters as arguments was removed. A filter object's parameters are only set via the SetXYZ methods. For example the `STAPLEImageFilter class `__: -Binary Morphology ++-----------------------------------------------------------+----------------------------------------------------------------+ +| 1.x | 2.x | ++-----------------------------------------------------------+----------------------------------------------------------------+ +| .. code-block:: python | .. code-block:: python | +| | | +| staple_filter = sitk.STAPLEImageFilter() | staple_filter = sitk.STAPLEImageFilter() | +| | staple_filter.ConfidenceWeight(confidenceWeight) | +| staple_image = staple_filter.Execute(image1, | staple_filter.SetForegroundValue(foregroundValue) | +| image2, image3, | staple_filter.SetMaximumIterations(maximumIterations) | +| confidenceWeight, | staple_image = staple_filter.Execute([image1, image2, image3])| +| foregroundValue, | | +| maximumIterations) | staple_specificity = staple_filter.GetSpecificity() | +| staple_specificity = staple_filter.GetSpecificity() | | +| | | ++-----------------------------------------------------------+----------------------------------------------------------------+ + +Alternatively, the procedural method could be used if no measurements or side effects on the object are needed. + +Morphology Radius +++++++++++++++++ -The procedural interfaces for BinaryErode, BinaryDilate and BinaryClosingByReconstruction previously expected a scalar value and now expect a vector structuring element with the same length as image dimension. This enables more flexible structuring elements. For example, previously a structuring element of size 5 used on a 3D image will now be specified as [5, 5, 5]: +The procedural interfaces for morphology filters only accept vector values for the radius parameter. Previously the procedures accepted a scalar for the radius parameter. For example, a structuring element of radius 5 used on a 3D image is specified as [5, 5, 5]: +----------------------------------------------------------+-------------------------------------------------------+ | 1.x | 2.x | @@ -38,48 +73,95 @@ The procedural interfaces for BinaryErode, BinaryDilate and BinaryClosingByRecon | seg = sitk.BinaryDilate(seg, 5) | seg = sitk.BinaryDilate(seg, [5]*seg.GetDimension()) | +----------------------------------------------------------+-------------------------------------------------------+ -Transformations -+++++++++++++++ +The following is a list of procedures affected by this change: + +* `BinaryClosingByReconstruction` +* `BinaryDilate` +* `BinaryErode` +* `BinaryMorphologicalClosing` +* `BinaryMorphologicalOpening` +* `BinaryOpeningByReconstruction` +* `BlackTopHat` +* `ClosingByReconstruction` +* `DilateObjectMorphology` +* `ErodeObjectMorphology` +* `GrayscaleDilate` +* `GrayscaleErode` +* `GrayscaleMorphologicalClosing` +* `GrayscaleMorphologicalOpening` +* `MorphologicalGradient` +* `OpeningByReconstruction` +* `WhiteTopHat` + + +FastMarchingImageFilter ++++++++++++++++++++++++ + +The `FastMarchingImageFilter::AddTrialPoints` and `FastMarchingImageFilter::ClearTrialPoints` methods were removed. The `SetTrialPoints` method can be used instead to set the whole list of trial points. + + +Behavior Changes +---------------- + +ITKv5 ++++++ -Composite transformations were previously represented using the generic `Transform class `__. This class served both as a base class for all transformations and as a composite transformation. This dual purpose -has been separated. Composite transformations are now represented by a dedicated class `CompositeTransform `__ and the associated functionality has been removed from the Transform. +SimpelITK 2.0 uses ITK version 5.0. This major version change to ITK includes numerous changes to the usage and behavior of ITK. The `ITK v5 Migration Guide `_ contains valuable information documenting changes. + + +Show Environment Variables +++++++++++++++++++++++++++ + +The environment variables related to the `Show` method are only checked once. The `Show` method is a wrapper for the `ImageViewer `__ class, changing the behavior from SimpleITK 1.0. The SITK_SHOW_EXTENSION and SITK_SHOW_COMMAND environment variables if defined initialize the corresponding global defaults only the first time accessed. The environment variables SITK_COLOR_COMMAND and SITK_SHOW_3D_COMMAND were removed as the ImageViewer class allows for direct configuration of the command. -+----------------------------------------------------------+-------------------------------------------------------------------------------------------------+ -| 1.x | 2.x | -+----------------------------------------------------------+-------------------------------------------------------------------------------------------------+ -| .. code-block:: python | .. code-block:: python | -| | | -| tx = sitk.Transform() | tx = sitk.CompositeTransform([sitk.TranslationTransform(3,(1,7,76)), sitk.Euler3DTransform()]) | -| tx.AddTransform(sitk.TranslationTransform(3,(1,7,76))) | | -| tx.AddTransform(sitk.Euler3DTransform()) | | -+----------------------------------------------------------+-------------------------------------------------------------------------------------------------+ Images ++++++ -Images previously did not support sub-image left assignment, they now do: +Images support sub-image left assignment of constants and matching image regions. .. code-block:: python img[0:10,5:15] = 128 + img[5:10,10:15] = img2[0:5,5:10] + + +DICOM MOCHOROME1 +++++++++++++++++ + +Changes to DICOM reading, due to SimpleITK's move from ITK 4.x to 5.x. Photomertic interpretation, tag 0028|0004, is now taken into account when reading the image. + + 1. MOCHOROME1: previously intensity values loaded as is, now they are inverted. Code that previously inverted the intensities explicitly needs to be removed. + 2. Color images (e.g. YBR_FULL_422): Previously channels loaded as is, now they are converted to RGB. If previous code used the photometric interpretation tag value to perform color space conversions outside of SimpleITK it will need to be modified. For example, previously the first channel for an image with photometric interpretation of YBR_FULL was luminance and could be used as the grayscale version of the image. Now all three channels are used to compute the image luminance: + ++----------------------------------------------------------+------------------------------------------------------------------------------------+ +| 1.x | 2.x | ++----------------------------------------------------------+------------------------------------------------------------------------------------+ +| .. code-block:: python | .. code-block:: python | +| | | +| | image = sitk.ReadImage(file_name) | +| | grayscale_image = 0.299*sitk.VectorIndexSelectionCast(image,0,sitk.sitkFloat32) + | +| image = sitk.ReadImage(file_name) | 0.587*sitk.VectorIndexSelectionCast(image,1,sitk.sitkFloat32) + | +| grayscale_image = sitk.VectorIndexSelectionCast(image,0)| 0.114*sitk.VectorIndexSelectionCast(image,2,sitk.sitkFloat32) | +| | grayscale_image = sitk.Cast(sitk.RescaleIntensity(grayscale_image)) | ++----------------------------------------------------------+------------------------------------------------------------------------------------+ + + + +Python Installation ++++++++++++++++++++ + +The Python installation procedure to use `setup.py` changed. To install see the updated `Python Installation `_ documentation. + +Multi-threading ++++++++++++++++ + +The upgrade to ITKv5 contains a major refactoring of ITK's threading model. Details on the behavior of the new default PoolMultiThreader can be found in the `ITK v5 Multi-Threading Section `_. + +The SimpelITK `ProcessObject class `_ contains the methods to configure the ITK Threader used and the number of threads and number of work units used for an algorithm. + + +Registration Smoothing +++++++++++++++++++++++ -Image Filters -+++++++++++++ - -Previously, the Execute method for some filters received filter parameter arguments. Now these methods have been removed, and filter parameters are only set via the SetXYZ methods. For example the `ResampleImageFilter class `__: - -+----------------------------------------------------------------+----------------------------------------------------------+ -| 1.x | 2.x | -+----------------------------------------------------------------+----------------------------------------------------------+ -| .. code-block:: python | .. code-block:: python | -| | | -| | resample_filter = sitk.ResampleImageFilter() | -| resample_filter = sitk.ResampleImageFilter() | resample_filter.SetOutputOrigin(new_origin) | -| resample_filter.Execute(image, new_size, tx, sitk.sitkLinear, | resample_filter.SetSize(new_size) | -| new_origin, new_spacing, | resample_filter.SetSpacing(new_spacing) | -| [1,0,0,0,1,0,0,0,1], -1000) | resample_filter.SetTransform(tx) | -| | resample_filter.SetInterpolator(sitk.sitkLinear) | -| | resample_filter.SetOutputDirection([1,0,0,0,1,0,0,0,1]) | -| | resample_filter.SetDefaultPixelValue(-1000) | -| | resampled_image = resample_filter.Execute(image) | -+----------------------------------------------------------------+----------------------------------------------------------+ +Results from the registration framework may change due to the the Gaussian smoothing algorithm changing from the `DiscreteGaussianImageFilter` to the `SmoothingRecursiveGaussianImageFilter`.