doc: Update the Quick start guide for ITK 5.0

Author: thewtex

docs/Quick_start_guide.rst

@@ -9,19 +9,7 @@ Installation
 
 To install the ITK Python package::
 
-    $ python -m pip install --upgrade pip
-    $ python -m pip install itk
-
-If a pre-compiled wheel package is not found for your Python distribution, then it will
-attempt to build from source.
-
-.. note::
-
-  On Windows machines, the source path cannot be greater than 50 characters or
-  issues will occur during build time due to filename truncation in Visual
-  Studio. If you must compile from source, clone this repository in a short
-  directory, like *C:/IPP*. Then, run `setup.py` within the repository via the
-  command line.
+    $ pip install itk
 
 
 Usage
@@ -36,22 +24,22 @@ Here is a simple python script that reads an image, applies a median image filte
 
 There are two ways to instantiate filters with ITKPython:
 
-- Implicit (recommended): ITK type information is automatically detected from the data. Typed filter objects and images are implicitly created.
+- *Implicit (recommended)*: ITK type information is automatically detected from the data. Typed filter objects and images are implicitly created.
 
 .. literalinclude:: code/ImplicitInstantiation.py
    :lines: 8-
 
-- Explicit: This can be useful if a filter cannot automatically select the type information (e.g. `CastImageFilter`), or to detect type mismatch errors which can lead to cryptic error messages.
+- *Explicit*: This can be useful if an appropriate type cannot be determined implicitly, e.g. with the `CastImageFilter`, and when a different filter type than the default is desired.
 
-Explicit instantiation of median image filter:
+Explicit instantiation of a median image filter:
 
-.. literalinclude:: code/ImplicitInstantiation.py
+.. literalinclude:: code/ExplicitInstantiation.py
    :lines: 8-
 
 Explicit instantiation of cast image filter:
 
 .. literalinclude:: code/CastImageFilter.py
-   :lines: 9-
+   :lines: 9-23
 
 ITK Python types
 ................
@@ -68,7 +56,7 @@ ITK Python types
 | std::complex<float> | itk.complex[itk.F] |
 +---------------------+--------------------+
 
-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/html/Book1/ITKSoftwareGuide-Book1ch9.html#x48-1530009.5>`_.
+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>`_.
 
 Types can also be obtained from their name in the C programming language:
 
@@ -101,7 +89,7 @@ The following script shows how to integrate NumPy and ITK:
    :lines: 8-33
 
 
-Similar functions are available to work with VNL vector and matrices:
+Similar functions are available to work with `itk.Matrix`, VNL vectors and matrices:
 
 .. literalinclude:: code/MixingITKAndNumPy.py
    :lines: 35-

docs/code/CastImageFilter.py

@@ -12,6 +12,15 @@
 input_dimension = image.GetImageDimension()
 # Select float as output pixel type
 OutputType = itk.Image[itk.UC, input_dimension]
-castFilter = itk.CastImageFilter[InputType, OutputType].New()
-castFilter.SetInput(image)
-itk.imwrite(castFilter, output_filename)
+
+# Functional interface
+casted = itk.cast_image_filter(image, ttype=(InputType, OutputType))
+
+# Object-oriented interface
+cast_filter = itk.CastImageFilter[InputType, OutputType].New()
+cast_filter.SetInput(image)
+cast_filter.Update()
+casted = cast_filter.GetOutput()
+
+# imwrite calls .Update()
+itk.imwrite(cast_filter, output_filename)

docs/code/ExplicitInstantiation.py

@@ -5,8 +5,16 @@
 
 input_filename = sys.argv[1]
 
-ImageType = itk.Image[itk.F,2]
-reader = itk.ImageFileReader[ImageType].New(FileName = input_filename)
+PixelType = itk.F
+ImageType = itk.Image[PixelType,2]
+
+# Functional interface
+image = itk.imread(input_filename, PixelType)
+smoothed = itk.median_image_filter(image, ttype=(ImageType, ImageType))
+
+# Object-oriented interface
+reader = itk.ImageFileReader[ImageType].New(FileName=input_filename)
 median = itk.MedianImageFilter[ImageType, ImageType].New()
 median.SetInput(reader.GetOutput())
-
+median.Update()
+smoothed = median.GetOutput()

docs/code/ImplicitInstantiation.py

@@ -5,11 +5,29 @@
 
 input_filename = sys.argv[1]
 
-# Use `ImageFileReader` instead of the wrapping function `imread` to illustrate this example.
+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.
+smoothed = itk.median_image_filter(image)
+
+# Alternatively, create filter objects. These filter objects can be connected in
+# a pipeline to stream-process large datasets. To generate the output of the
+# pipeline, .Update() must explicitly be called on the last filter of the
+# pipeline.
+#
+# We can implicitly instantiate the filter object based on the type
+# of the input image in multiple ways.
+
+# Use itk.ImageFileReader instead of the wrapping function,
+# itk.imread to illustrate this example.
 reader = itk.ImageFileReader.New(FileName=input_filename)
 # Here we specify the filter input explicitly
 median = itk.MedianImageFilter.New(Input=reader.GetOutput())
-# Same as above but shortened. `Input` does not have to be specified.
+# 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.
+# Same as above. .GetOutput() does not have to be specified.
 median = itk.MedianImageFilter.New(reader)
+
+median.Update()
+smoothed = median.GetOutput()

docs/code/MixingITKAndNumPy.py

@@ -14,34 +14,40 @@
 # Run filters on itk.Image
 
 # View only of itk.Image, data is not copied
-np_view = itk.GetArrayViewFromImage(itk_image)
+np_view = itk.array_view_from_image(itk_image)
 
 # Copy of itk.Image, data is copied
-np_copy = itk.GetArrayFromImage(itk_image)
+np_copy = itk.array_from_image(itk_image)
 
 
-# Do numpy stuff
+# Do NumPy stuff...
 
 
-# Convert back to itk, view only, data is not copied
-itk_np_view = itk.GetImageViewFromArray(np_copy)
+# Convert back to ITK, view only, data is not copied
+itk_np_view = itk.image_view_from_array(np_copy)
 
-# Convert back to itk, data is copied
-itk_np_copy = itk.GetImageFromArray(np_copy)
+# Convert back to ITK, data is copied
+itk_np_copy = itk.image_from_array(np_copy)
 
 # Save result
 itk.imwrite(itk_np_view, output_filename)
 
-# Vnl matrix from array
+# VNL matrix from array
 arr = np.zeros([3,3], np.uint8)
-matrix = itk.GetVnlMatrixFromArray(arr)
+matrix = itk.vnl_matrix_from_array(arr)
 
-# Array from Vnl matrix
-arr = itk.GetArrayFromVnlMatrix(matrix)
+# Array from VNL matrix
+arr = itk.array_from_vnl_matrix(matrix)
 
-# Vnl vector from array
+# VNL vector from array
 vec = np.zeros([3], np.uint8)
-vnl_vector = itk.GetVnlVectorFromArray(vec)
+vnl_vector = itk.vnl_vector_from_array(vec)
 
-# Array from Vnl vector
-vec = itk.GetArrayFromVnlVector(vnl_vector)
+# Array from VNL vector
+vec = itk.array_from_vnl_vector(vnl_vector)
+
+# itk.Matrix from array
+mat = itk.matrix_from_array(np.eye(3))
+
+# array from itk.Matrix
+arr = itk.array_from_matrix(mat)

docs/code/ReadMedianWrite.py

@@ -7,5 +7,7 @@
 output_filename = sys.argv[2]
 
 image = itk.imread(input_filename)
-median = itk.MedianImageFilter.New(image, Radius = 2)
+
+median = itk.median_image_filter(image, radius=2)
+
 itk.imwrite(median, output_filename)

docs/index.rst

@@ -8,20 +8,10 @@ infrastructure to build ITK external module Python wheels.
 
 To install the stable ITK Python package::
 
-  python -m pip install --upgrade pip
-  python -m pip install itk
+  $ pip install itk
 
-The Python packages are built daily. To install the latest build from the ITK
-Git *master* branch::
-
-  python -m pip install --upgrade pip numpy
-  python -m pip install itk --upgrade --no-index \
-    -f https://github.com/InsightSoftwareConsortium/ITKPythonPackage/releases/tag/latest
-
-
-For more information on ITK's Python wrapping, see `an introduction in the ITK
-Software Guide
-<https://itk.org/ITKSoftwareGuide/html/Book1/ITKSoftwareGuide-Book1ch3.html#x32-420003.7>`_.
+For more information on ITK's Python wrapping, see `an introduction in the
+Book 1, Chapter 3 of the ITK Software Guide <https://itk.org/ItkSoftwareGuide.pdf>`_.
 There are also many `downloadable examples documented in Sphinx
 <https://itk.org/ITKExamples/search.html?q=Python>`_.