Quick start guide¶

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.

Usage¶

Basic examples¶

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[1]
output_filename = sys.argv[2]

image = itk.imread(input_filename)
median = itk.MedianImageFilter.New(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.

# Use `ImageFileReader` instead of the wrapping function `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)

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 instantiation of median image filter:

# Use `ImageFileReader` instead of the wrapping function `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)

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]
castFilter = itk.CastImageFilter[InputType, OutputType].New()
castFilter.SetInput(image)
itk.imwrite(castFilter, output_filename)

ITK Python types¶

C++ type	Python type
float	itk.F
double	itk.D
unsigned char	itk.UC
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.

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.

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.GetArrayViewFromImage(itk_image)

# Copy of itk.Image, data is copied
np_copy = itk.GetArrayFromImage(itk_image)


# Do numpy stuff


# Convert back to itk, view only, data is not copied
itk_np_view = itk.GetImageViewFromArray(np_copy)

# Convert back to itk, data is copied
itk_np_copy = itk.GetImageFromArray(np_copy)

# Save result
itk.imwrite(itk_np_view, output_filename)

Similar functions are available to work with VNL vector and matrices:

# Vnl matrix from array
arr = np.zeros([3,3], np.uint8)
matrix = itk.GetVnlMatrixFromArray(arr)

# Array from Vnl matrix
arr = itk.GetArrayFromVnlMatrix(matrix)

# Vnl vector from array
vec = np.zeros([3], np.uint8)
vnl_vector = itk.GetVnlVectorFromArray(vec)

# Array from Vnl vector
vec = itk.GetArrayFromVnlVector(vnl_vector)

Examples¶

Examples can be found in the ITKExamples project.