Difference between revisions of "Proposals:Refactoring Wrapping"

From KitwarePublic
Jump to navigationJump to search
Line 11: Line 11:
* All wrap_XxxLang.cxx files, concerning the module wrapping, are now directly generated by CMake
* All wrap_XxxLang.cxx files, concerning the module wrapping, are now directly generated by CMake


For :
The advantages of these changes are:


* There is no enought C++ macros (that are numerous and copied between some files... ex : All Transform classes wrapping).
* There is no enough C++ macros (that are numerous and copied between some files... ex : All Transform classes wrapping).
* All classes are wrapped with consistent rules. The mangled name is then coherent between all classes.
* All classes are wrapped with consistent rules. The mangled name is then coherent between all classes.
- It simplifies the integration of the two next points (Wrap an own class
* It simplifies the integration of the two next points (Wrap an own class and Tree of templated classes)
  and Tree of templated classes)
* The itkCSwigMacro.h and itkCSwigImage.h files are now useless...
- The itkCSwigMacro.h and itkCSwigImage.h files are now useless...
* Best support for future ITK addons
- Best support for future ITK addons
 
Against :
The disadvantages of these changes are:
- The mangled name isn't kept
 
* The mangled name isn't kept
   
   
The write of these files is made using CMake macros. These macros
The write of these files is made using CMake macros. These macros
Line 28: Line 29:
classes.
classes.


2 - Wrap an own class :
== Wrapping a user-defined class ==
----------------------------------
 
The first change tails this second point : all files are genericly created.
The first change tails this second point : all files are generic-ly created.
   
   
The project to create the corresponding libraries and files to a module
The project to create the corresponding libraries and files to a module
Line 50: Line 50:
   
   


3 - Tree of templated classes :
===- Tree of templated classes ==
-------------------------------
 
The goal is to have a simplest and generic use of templated ITK classes.
The goal is to have a simplest and generic use of templated ITK classes.
Consider this python example :
Consider this python example :
   def write( itkImg, file ) :
   def write( itkImg, file ) :
       # typedef itk::ImageFileWriter< itkImg::Self > writerT
       # typedef itk::ImageFileWriter< itkImg::Self > writerT
Line 71: Line 73:
itkPyTemplate type while the wrapping of the ITK classes.
itkPyTemplate type while the wrapping of the ITK classes.
So, I will have :
So, I will have :
   itkImage = itkPyTemplate("itkImage")
   itkImage = itkPyTemplate("itkImage")
For specific internal processing,
For specific internal processing,
The itkPyTemplate class can be used like a python dictionnary
The itkPyTemplate class can be used like a python dictionnary
Line 77: Line 81:
Next, I will call the set method on this new class instance to add
Next, I will call the set method on this new class instance to add
different templates :
different templates :
   itkImage.set("unsigned short,2",itkImageUS2)
   itkImage.set("unsigned short,2",itkImageUS2)
First parameter is the template type used as a key and the second
First parameter is the template type used as a key and the second
parameter is the definition corresponding to the key.
parameter is the definition corresponding to the key.


So, I can write :
So, I can write :
   itkImage[itkUS,2]
   itkImage[itkUS,2]
to get the itkImageUS2 class.
to get the itkImageUS2 class.
After, I call the New method on this class and I get a class instance.
After, I call the New method on this class and I get a class instance.
Line 90: Line 98:
in the resulting file : itkcommonaPy.py for the common part
in the resulting file : itkcommonaPy.py for the common part
Last, we need call the itkcommonaPy module.
Last, we need call the itkcommonaPy module.
All of these created python modules are imported in the itkPython.py file
All of these created python modules are imported in the itkPython.py file
so, the user only needs to import the itkPython module use this advance
so, the user only needs to import the itkPython module use this advance
Line 102: Line 111:
Java (I don't know if Tcl has classes... but a similar solution may be
Java (I don't know if Tcl has classes... but a similar solution may be
found).
found).
This patch can be removed by remove the code contained only in the macros
This patch can be removed by remove the code contained only in the macros
in the CSwig/WrapITKLang.cmake file. But I think that patch is a usefull advance.
in the CSwig/WrapITKLang.cmake file. But I think that patch is a usefull advance.

Revision as of 19:46, 10 October 2005

Refactoring ITK Wrapping

The current process used for Wrapping ITK requires a number of steps for adding new classes to be wrapped. Some of those steps can be simplified if the wrapping process is reorganized. This proposal gathers the work of Benoit Regrain (Creatis Team, France) and Gaetan Lehmann (Inria, France).

Proposal

Use of CMake to generate wrapping

  • All wrap_Xxx.cxx files, concerning the ITK classes wrapping, are now directly generated by CMake.
  • All wrap_XxxLang.cxx files, concerning the module wrapping, are now directly generated by CMake

The advantages of these changes are:

  • There is no enough C++ macros (that are numerous and copied between some files... ex : All Transform classes wrapping).
  • All classes are wrapped with consistent rules. The mangled name is then coherent between all classes.
  • It simplifies the integration of the two next points (Wrap an own class and Tree of templated classes)
  • The itkCSwigMacro.h and itkCSwigImage.h files are now useless...
  • Best support for future ITK addons

The disadvantages of these changes are:

  • The mangled name isn't kept

The write of these files is made using CMake macros. These macros are in CSwig/WrapITK.cmake The CSwig/WrapType*.cmake files are help for the basic types and advanced types creation. These types are used define the template classes.

Wrapping a user-defined class

The first change tails this second point : all files are genericly created.

The project to create the corresponding libraries and files to a module is placed in a generic macro, generic in the sens that this macro independant to ITK.

This macro and all used macros are placed in the CSwig/itkConfigWrapping.cmake file.

So, if an user want wrap its own ITK class... or extent the wrapping of an existing ITK class, it must include the itkConfigWrapping.cmake and WrapITK.cmake files and use the corresponding macros to his work.

In the itkWrapping CVS repository, there is an example to simply wrap my own class itkImageNothingFilter (easy filter that do nothing on the image). This example is completed with a Python test file.


=- Tree of templated classes

The goal is to have a simplest and generic use of templated ITK classes.

Consider this python example :

  def write( itkImg, file ) :
     # typedef itk::ImageFileWriter< itkImg::Self > writerT
     writerT = itkImageFileWriter[ itkImg ]
     writer = writerT.New()
     writer.SetInput( itkImg )
     writer.SetFileName( file )
     writer.Update()

This function will write an image (itkImg) in a file. But the writer creation is dependant to the itkImg type. The goal is : offer the possibility to the programmer to instanciate an ITK class without before known of the itkImg type.

To have it, I will create a new class instance of itkPyTemplate type while the wrapping of the ITK classes. So, I will have :

  itkImage = itkPyTemplate("itkImage")

For specific internal processing, The itkPyTemplate class can be used like a python dictionnary

Next, I will call the set method on this new class instance to add different templates :

  itkImage.set("unsigned short,2",itkImageUS2)

First parameter is the template type used as a key and the second parameter is the definition corresponding to the key.

So, I can write :

  itkImage[itkUS,2]

to get the itkImageUS2 class. After, I call the New method on this class and I get a class instance.

The code of the itkPyTemplate class is at CSwig/Python/itkPyTemplate.py The code to generate these classes is written by CMake. It's in the resulting file : itkcommonaPy.py for the common part Last, we need call the itkcommonaPy module.

All of these created python modules are imported in the itkPython.py file so, the user only needs to import the itkPython module use this advance In the CSwig/Tests/Python directory, I added the testTemplate.py and testTemplateUse.py files to test the class creation

The code to write the itkcommonaPy.py file is in CSwig/WrapITKLang.cmake This code contains the WRITE_LANG_WRAP macro that will write these additionnal python classes

This solution is actually only in python but it can be implemented for Java (I don't know if Tcl has classes... but a similar solution may be found).

This patch can be removed by remove the code contained only in the macros in the CSwig/WrapITKLang.cmake file. But I think that patch is a usefull advance.