Quick start guide

Installation

To install the ITK Python package:

$ pip install itk

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.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
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.

Filter Parameters

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([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
mat = itk.matrix_from_array(np.eye(3))

# array from itk.Matrix
arr = itk.array_from_matrix(mat)

Examples

Examples can be found in the ITKExamples project.