DOC: Python Quick Start updates for ITK 5.2

Author: thewtex

docs/Quick_start_guide.rst

@@ -22,9 +22,11 @@ Here is a simple python script that reads an image, applies a median image filte
 
 .. literalinclude:: code/ReadMedianWrite.py
 
-There are two ways to instantiate filters with ITKPython:
+In `itk`, filters are optimized at compile time for each image pixel type and
+image dimension. There are two ways to instantiate these filters with the `itk`
+Python wrapping:
 
-- *Implicit (recommended)*: ITK type information is automatically detected from the data. Typed filter objects and images are implicitly created.
+- *Implicit (recommended)*: Type information is automatically detected from the data. Typed filter objects and images are implicitly created.
 
 .. literalinclude:: code/ImplicitInstantiation.py
    :lines: 8-
@@ -38,23 +40,23 @@ Explicit instantiation of a median image filter:
 
 Explicit instantiation of cast image filter:
 
-.. literalinclude:: code/CastImageFilter.py
-   :lines: 9-23
+.. literalinclude:: code/Cast.py
+   :lines: 10-18
 
 ITK Python types
 ................
 
-+---------------------+--------------------+
-| C++ type            | Python type        |
-+=====================+====================+
-| float               | itk.F              |
-+---------------------+--------------------+
-| double              | itk.D              |
-+---------------------+--------------------+
-| unsigned char       | itk.UC             |
-+---------------------+--------------------+
-| std::complex<float> | itk.complex[itk.F] |
-+---------------------+--------------------+
++---------------------+--------------------+--------------------+
+| C++ type            | Python type        | NumPy dtype        |
++=====================+====================+====================+
+| float               | itk.F              | np.float32         |
++---------------------+--------------------+--------------------+
+| double              | itk.D              | np.float64         |
++---------------------+--------------------+--------------------+
+| unsigned char       | itk.UC             | np.uint8           |
++---------------------+--------------------+--------------------+
+| std::complex<float> | itk.complex[itk.F] | np.complex64       |
++---------------------+--------------------+--------------------+
 
 This list is not exhaustive and is only presented to illustrate the type names. The complete list of types can be found in the `ITK Software Guide <https://itk.org/ItkSoftwareGuide.pdf>`_.
 
@@ -90,7 +92,7 @@ ITK filter parameters can be specified in the following ways:
 Mixing ITK and NumPy
 --------------------
 
-A common use case for using ITK in Python is to mingle NumPy and ITK operations on raster data. ITK provides a large number of I/O image formats and several sophisticated image processing algorithms not available in any other packages. The ability to intersperse that with numpy special purpose hacking provides a great tool for rapid prototyping.
+A common use case for using ITK in Python is to mingle NumPy and ITK operations on raster data. ITK provides a large number of I/O image formats and several sophisticated image processing algorithms not available in any other packages. The ability to intersperse that with the SciPy ecosystem provides a great tool for rapid prototyping.
 
 The following script shows how to integrate NumPy and ITK:
 
@@ -107,4 +109,4 @@ Similar functions are available to work with `itk.Matrix`, VNL vectors and matri
 Examples
 --------
 
-Examples can be found in the `ITKExamples project <https://itk.org/ITKExamples/src/index.html>`_.
+Examples can be found in the `ITKSphinxExamples project <https://itk.org/ITKExamples/src/index.html>`_.

docs/code/Cast.py

@@ -0,0 +1,18 @@
+#!/usr/bin/env python3
+
+import numpy as np
+import itk
+import sys
+
+input_filename = sys.argv[1]
+output_filename = sys.argv[2]
+
+image = itk.imread(input_filename)
+
+# Cast to an unsigned char pixel type
+cast_image = image.astype(itk.UC)
+
+# Equivalent
+cast_image = image.astype(np.uint8)
+
+itk.imwrite(cast_image, output_filename)

docs/code/CastImageFilter.py

@@ -5,15 +5,21 @@
 
 input_filename = sys.argv[1]
 
+# An apriori ImageType
 PixelType = itk.F
 ImageType = itk.Image[PixelType,2]
+image = itk.imread(input_filename, PixelType)
+
+# An image type dynamically determined from the type on disk
+image = itk.imread(input_filename)
+ImageType = type(image)
 
 # Functional interface
-image = itk.imread(input_filename, PixelType)
+# The `ttype` keyword argument specifies the filter type.
 smoothed = itk.median_image_filter(image, ttype=(ImageType, ImageType))
 
 # Object-oriented interface
-reader = itk.ImageFileReader[ImageType].New(FileName=input_filename)
+reader = itk.ImageFileReader[ImageType].New(file_name=input_filename)
 median = itk.MedianImageFilter[ImageType, ImageType].New()
 median.SetInput(reader.GetOutput())
 median.Update()

docs/code/ExplicitInstantiation.py

@@ -11,15 +11,13 @@
 #
 #   number_of_iterations
 #
-smoothed = itk.anti_alias_binary_image_filter(image,
-        number_of_iterations=3)
+smoothed = itk.anti_alias_binary_image_filter(image, number_of_iterations=3)
 
 # CamelCase keyword arguments:
 #
 #   NumberOfIterations
 #
-smoother = itk.AntiAliasBinaryImageFilter.New(image,
-        NumberOfIterations=3)
+smoother = itk.AntiAliasBinaryImageFilter.New(image, NumberOfIterations=3)
 smoother.Update()
 smoothed = smoother.GetOutput()
 

docs/code/FilterParameters.py

@@ -6,6 +6,7 @@
 input_filename = sys.argv[1]
 
 image = itk.imread(input_filename)
+
 # Use ITK's functional, Pythonic interface. The filter type is implied by the
 # type of the input image. The filter is eagerly executed, and the output image
 # is directly returned.
@@ -21,9 +22,10 @@
 
 # Use itk.ImageFileReader instead of the wrapping function,
 # itk.imread to illustrate this example.
-reader = itk.ImageFileReader.New(FileName=input_filename)
+ImageType = itk.Image[itk.UC, 2]
+reader = itk.ImageFileReader[ImageType].New(FileName=input_filename)
 # Here we specify the filter input explicitly
-median = itk.MedianImageFilter.New(Input=reader.GetOutput())
+median = itk.MedianImageFilter.New(reader.GetOutput())
 # Same as above but shortened. Input does not have to be specified.
 median = itk.MedianImageFilter.New(reader.GetOutput())
 # Same as above. .GetOutput() does not have to be specified.

docs/code/ImplicitInstantiation.py

@@ -8,4 +8,4 @@
 median = itk.MedianImageFilter[InputType, OutputType].New()
 
 # Instantiate non-SmartPointer objects
-pixel = itk.RGBPixel[itk.D]()
+pixel = itk.RGBPixel[itk.UC]()

docs/code/InstantiateITKObjects.py

@@ -13,11 +13,13 @@
 
 # Run filters on itk.Image
 
-# View only of itk.Image, data is not copied
+# View only of itk.Image, pixel data is not copied
 np_view = itk.array_view_from_image(itk_image)
 
-# Copy of itk.Image, data is copied
+# Copy of itk.Image, pixel data is copied
 np_copy = itk.array_from_image(itk_image)
+# Equivalent
+np_copy = np.asarray(itk_image)
 
 
 # Do NumPy stuff...
@@ -32,22 +34,22 @@
 # Save result
 itk.imwrite(itk_np_view, output_filename)
 
-# VNL matrix from array
+# VNL matrix from np.ndarray
 arr = np.zeros([3,3], np.uint8)
 matrix = itk.vnl_matrix_from_array(arr)
 
 # Array from VNL matrix
 arr = itk.array_from_vnl_matrix(matrix)
 
-# VNL vector from array
+# VNL vector from np.ndarray
 vec = np.zeros([3], np.uint8)
 vnl_vector = itk.vnl_vector_from_array(vec)
 
 # Array from VNL vector
 vec = itk.array_from_vnl_vector(vnl_vector)
 
-# itk.Matrix from array
+# itk.Matrix from np.ndarray
 mat = itk.matrix_from_array(np.eye(3))
 
-# array from itk.Matrix
+# np.ndarray from itk.Matrix
 arr = itk.array_from_matrix(mat)

docs/code/MixingITKAndNumPy.py

@@ -39,9 +39,9 @@ def cleanup(files):
 # Run test ExplicitInstantiation.py
 add_test(["ExplicitInstantiation.py", baseline_image])
 
-# Run test CastImageFilter.py
+# Run test Cast.py
 output_image = os.path.join(temp_folder, "filtered_image.png")
-add_test(["CastImageFilter.py", baseline_image, output_image])
+add_test(["Cast.py", baseline_image, output_image])
 cleanup([output_image])
 
 # Run test CompareITKTypes.py

docs/code/testDriver.py docs/code/test.pydocs/code/testDriver.py renamed to docs/code/test.py

@@ -161,5 +161,5 @@ for PYBIN in "${PYBINARIES[@]}"; do
     (cd $HOME && ${PYBIN}/python -c 'from itk import ITKCommon;')
     (cd $HOME && ${PYBIN}/python -c 'import itk; image = itk.Image[itk.UC, 2].New()')
     (cd $HOME && ${PYBIN}/python -c 'import itkConfig; itkConfig.LazyLoading = False; import itk;')
-    (cd $HOME && ${PYBIN}/python ${script_dir}/../../docs/code/testDriver.py )
+    (cd $HOME && ${PYBIN}/python ${script_dir}/../../docs/code/test.py )
 done