[Insight-developers] [ITK + Wrapping (Python)] Wrapping classes proposal - V.3

[Benoit Regrain]

Hi,

Following some mails on the subject :
   [ITK + Python] Wrapping classes proposal
   [ITK + Python] Wrapping classes proposal - V.2


Changes between V.2 and V.3 :
 - the wrap_Xxx.cmake have been written for all itk parts
 - the mangled name can be choosed randomly (but not for all classes)
 - the class tree is now independant to the mangling name (in the
   final wrapped language)


All of this work can be found on the Creatis CVS server :
   CVSROOT : :pserver:anonymous at cvs.creatis.insa-lyon.fr:2402/cvs/public
   password  : anonymous
   Module name : itkWrapping


Concerning this patch, I would now :
 - if ITK is interested by that, and integrate it
   (thus, I will continue and write the wrap_Xxx.cmake
   files for other ITK parts)
 - if there have conceptual or other problems with this proposal
   (for each of 2 points)
Thanks to ITK to answer me concerning their interest for
this proposal.

Cheers
Benoit Regrain



---> Presentation of changes (from the ITK project v2.0.1) :

1 - Use of CMake to generate wrapping :
------------------------------------------
All wrap_Xxx.cxx files are directly generated by CMake.
For :
 - There is no enought 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 second point (Tree of
   templated classes)
 - The itkCSwigMacro.h and itkCSwigImage.h files are now useless...
   Thus, it's easier to wrap personal ITK classes without integrate them
   in the ITK folder tree.
 - Best support for future ITK addons
Against :
 - The mangled name isn't kept...

For certain classes used to define the template of other classes, it may be
good to have a consistant mangled name. These class's wraps are in the
CSwig/WrapTypePrefix.cmake file.
For other classes, the mangled name can be choosed randomly.


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.
In CSwig/Common : all wrap_Xxx.cxx files are replaced by
wrap_Xxx.cmake when it's needed


2 - 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, I will set the class name.
The itkPyTemplate class can be used like a python dictionnary :
 - the key is the template definition (like in C++)
 - the value is the defined template class

Next, I will call the set method on this new class instance to add
different templates :
   itkImage.set("float,2",itkImageF2)
   itkImage.set("itk::Vector< float,2 >,2",itkImageVF22)
The first parameter is parsed to know all the template definitions used.
We obtain a tuple of all types needed to obtain the class (value
corresponding to the key)
Then, the itkPyTemplate instance can be used like a dictionnary.
So, I can write :
   itkImage["F",2]
   itkImage[ITK_F,2]  # ITK_F  = "F"
to get the itkImageUS2 class.
or write :
   itkImage[itkVector["F",2],2]
to get the itkImageVF22 class

Internally, a class variable (that is a dictionnary) is used to translate 
from
   "itk::Vector< float,2 >" template definition to the itkVectorF2 class
But to know this type, the order of itkPyTemplate classes instanciation
is important :-(

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 : itkcommonPy.py for the common part
Last, we need call the itkcommonPy module while the import of
InsightToolkit package.
In the CSwig/Tests/Python directory, I added the
testTemplate.py file to test the class creation

The code to write the itkcommonPy.py file is in CSwig/WrapITK.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).
To do this implementation in other languages, we only need to have
the type of objects. It's possible in C and Python, I think it's possible
in Java and Tcl (but I don't know these languages)

Information : I'm working on a C++ version of the actual itkPyTemplate, 
but I'm not sure that it's possible to do...