Quick start guide¶
To install the ITK Python package:
$ pip install itk
Here is a simple python script that reads an image, applies a median image filter (radius of 2 pixels), and writes the resulting image in a file.
#!/usr/bin/env python import itk import sys input_filename = sys.argv output_filename = sys.argv image = itk.imread(input_filename) median = itk.median_image_filter(image, radius=2) itk.imwrite(median, output_filename)
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.
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. median = itk.MedianImageFilter.New(reader.GetOutput()) # Same as above. .GetOutput() does not have to be specified. median = itk.MedianImageFilter.New(reader) median.Update() smoothed = median.GetOutput()
- 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 a median image filter:
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()
Explicit instantiation of cast image filter:
image = itk.imread(input_filename) InputType = type(image) # Find input image dimension input_dimension = image.GetImageDimension() # Select float as output pixel type OutputType = itk.Image[itk.UC, input_dimension] # 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()
ITK Python types¶
|C++ type||Python type|
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.
Types can also be obtained from their name in the C programming language:
itk.F == itk.ctype('float') # True
Instantiate an ITK object¶
There are two types of ITK objects. Most ITK objects (images, filters, adapters, …) are instantiated the following way:
InputType = itk.Image[itk.F,3] OutputType = itk.Image[itk.F,3] median = itk.MedianImageFilter[InputType, OutputType].New()
Some objects (matrix, vector, RGBPixel, …) do not require the attribute .New() to be added to instantiate them:
pixel = itk.RGBPixel[itk.D]()
In case of doubt, look at the attributes of the object you are trying to instantiate.
ITK filter parameters can be specified in the following ways:
# Pythonic snake case keyword arguments: # # number_of_iterations # smoothed = itk.anti_alias_binary_image_filter(image, number_of_iterations=3) # CamelCase keyword arguments: # # NumberOfIterations # smoother = itk.AntiAliasBinaryImageFilter.New(image, NumberOfIterations=3) smoother.Update() smoothed = smoother.GetOutput() # CamelCase Set method: # # SetNumberOfIterations # smoother = itk.AntiAliasBinaryImageFilter.New(image) smoother.SetNumberOfIterations(3) smoother.Update() smoothed = smoother.GetOutput()
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.
The following script shows how to integrate NumPy and ITK:
import itk import numpy as np # Read input image itk_image = itk.imread(input_filename) # Run filters on itk.Image # View only of itk.Image, data is not copied np_view = itk.array_view_from_image(itk_image) # Copy of itk.Image, data is copied np_copy = itk.array_from_image(itk_image) # Do NumPy stuff... # 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.image_from_array(np_copy) # Save result itk.imwrite(itk_np_view, output_filename)
Similar functions are available to work with itk.Matrix, VNL vectors and matrices:
# VNL matrix from array 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 vec = np.zeros(, 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 mat = itk.matrix_from_array(np.eye(3)) # array from itk.Matrix arr = itk.array_from_matrix(mat)