ITK/Scripting: Difference between revisions

From KitwarePublic
< ITK
Jump to navigationJump to search
No edit summary
(Adding description on how to wrap a new class)
Line 65: Line 65:
You have two independent lines of action:  
You have two independent lines of action:  


A) Write an email to the users-list and request the developers to wrap the class that you need.
# Write an email to the users-list and request the developers to wrap the class that you need.
# Wrap the class yourself by following the instructions in the remaining part of this section.


B) Wrap the class yourself by following the instructions in the remaining part of this section.


Since we have learned that programmers are great at learning-by-example, the following section will teach you how to wrap a new class by walking step-by-step through the process of wrapping a new class. The subject of our example is the <tt>itkOtsuMultipleThresholdCalculator</tt>, simply because at the time of writing this text there was a request pending for adding this class to the wrapping, so we thought that by writing these instructions we will solve two problems simultaneously :-)


Since we have learned that programmers are great at learning-by-example, the following section will teach you how to wrap a new class by walking step-by-step through the process of wrapping a new class. The subject of our example is the itkOtsuMultipleThresholdCalculator, simply because at the time of writing this text there was a request pending for adding this class to the wrapping, so we thought that by writing these instructions we will solve two problems simultaneously :-)
=== Finding the directory ===
 
The first step in writing the wrapping for a class is to find the directory where such class has been cataloged. In the particular case of our subject, the <tt>itkOtsuMultipleThresholdCalculator</tt>, it is located in the directory
 
    <tt>Insight/Code/Algorithms</tt>
 
Therefore we know that its wrapping files will have to be placed under
 
    <tt>Insight/Wrapping/CSwig/Algorithms</tt>
 
As you probably noticed already, all the files defining the wrapping process are located in the directory
 
    <tt>Insight/Wrapping/CSwig</tt>
 
=== What files to modify ===
 
Now that we found the directory, we have to keep in mind that '''three''' files will have to be modified in order to add wrapping for our subject class. These files are
 
# CMakeLists.txt
# wrap_ITKAlgorithms.cxx
# the new file that defines the instantiations for our class
 
Let's start with the CMakeLists.txt file since it will be the simplest change to make. When you open any of the CMakeLists.txt files in the Wrapping/CSwig subdirectories you will find that the initial section contains a list of source files to wrap. Something like
 
 
  SET(WRAP_SOURCES
      wrap_itkCurvatureFlowImageFilter
      wrap_itkDemonsRegistrationFilter
      wrap_itkHistogramMatchingImageFilter
      wrap_itkImageRegistrationMethod
      ...
      )
 
The only thing that you have to change in this file is to add your class to this list. Note that you must add the prefix "wrap_itk" to the name of your class. In our case,
for wrapping the <tt>itkOtsuMultipleThresholdCalculator</tt> we will add it as
 
 
  SET(WRAP_SOURCES
      wrap_itkCurvatureFlowImageFilter
      wrap_itkDemonsRegistrationFilter
      '''wrap_itkOtsuMultipleThresholdCalculator'''
      wrap_itkHistogramMatchingImageFilter
      wrap_itkImageRegistrationMethod
      ...
      )

Revision as of 02:06, 15 November 2004

ITK itself is written in C++, however a tool called CableSwig can be used to generate bindings for other languages. This allows you to use the same runtime (running in optimised C++ code) but develop in a scripting language (and take advantage of all the attendant benefits).

The following languages are supported via the bindings:

In order to build the bindings, you will need to:

  1. Build and install CableSwig (more info)
  2. Ensure you have installed both the runtime and the development versions of your chosen language
  3. Build ITK using the appropriate settings for your platform, and enable the CABLE_* option for your language
  4. Install ITK as per normal
  5. Test!

Tcl Bindings

Tcl (Tool Command Language) is a very simple language for writing scripts.

Python Bindings

Python is a very elegant and powerful language.

Here is some example Python code for ITK (taken from `Insight/Examples/Filtering`):

#!/usr/bin/env python
 
# BinaryThresholdImageFilter.py
 
from InsightToolkit import *
 
from sys import argv
 
reader = itkImageFileReaderUS2_New()
writer = itkImageFileWriterUS2_New()
 
filter  = itkBinaryThresholdImageFilterUS2US2_New()
 
filter.SetInput( reader.GetOutput() )
writer.SetInput( filter.GetOutput() )
 
reader.SetFileName( argv[1] )
writer.SetFileName( argv[2] )
 
filter.SetLowerThreshold( eval( argv[3] )  )
filter.SetUpperThreshold( eval( argv[4] )  )
filter.SetOutsideValue(   eval( argv[5] )  )
filter.SetInsideValue(    eval( argv[6] )  )
 
writer.Update()

Java Bindings

Java is a modern object-oriented language.

How to wrap additional classes

Given that ITK is based on Generic Programming, most of the C++ classes are implemented as templates. Therefore, their final type is not defined until the actual template is instantiated with specific template arguments. This generality makes difficult to automatically wrap ITK classes for scripting languages such as Tcl and Python. The solution adopted by ITK is to use the powerful Cable-Swig platform and to select specific instantiation for the most commonly used types. In practice it is impossible to wrap all ITK classes, simply because the combinations of types will result in an very large number of classes.

It is then likely that you may find that your favorite class is not being wrapped...

What to do in that case ?

You have two independent lines of action:

  1. Write an email to the users-list and request the developers to wrap the class that you need.
  2. Wrap the class yourself by following the instructions in the remaining part of this section.


Since we have learned that programmers are great at learning-by-example, the following section will teach you how to wrap a new class by walking step-by-step through the process of wrapping a new class. The subject of our example is the itkOtsuMultipleThresholdCalculator, simply because at the time of writing this text there was a request pending for adding this class to the wrapping, so we thought that by writing these instructions we will solve two problems simultaneously :-)

Finding the directory

The first step in writing the wrapping for a class is to find the directory where such class has been cataloged. In the particular case of our subject, the itkOtsuMultipleThresholdCalculator, it is located in the directory

   Insight/Code/Algorithms

Therefore we know that its wrapping files will have to be placed under

   Insight/Wrapping/CSwig/Algorithms

As you probably noticed already, all the files defining the wrapping process are located in the directory

   Insight/Wrapping/CSwig

What files to modify

Now that we found the directory, we have to keep in mind that three files will have to be modified in order to add wrapping for our subject class. These files are

  1. CMakeLists.txt
  2. wrap_ITKAlgorithms.cxx
  3. the new file that defines the instantiations for our class

Let's start with the CMakeLists.txt file since it will be the simplest change to make. When you open any of the CMakeLists.txt files in the Wrapping/CSwig subdirectories you will find that the initial section contains a list of source files to wrap. Something like


  SET(WRAP_SOURCES
      wrap_itkCurvatureFlowImageFilter
      wrap_itkDemonsRegistrationFilter
      wrap_itkHistogramMatchingImageFilter
      wrap_itkImageRegistrationMethod
      ...
      )

The only thing that you have to change in this file is to add your class to this list. Note that you must add the prefix "wrap_itk" to the name of your class. In our case, for wrapping the itkOtsuMultipleThresholdCalculator we will add it as


 SET(WRAP_SOURCES
     wrap_itkCurvatureFlowImageFilter
     wrap_itkDemonsRegistrationFilter
     wrap_itkOtsuMultipleThresholdCalculator
     wrap_itkHistogramMatchingImageFilter
     wrap_itkImageRegistrationMethod
     ...
     )