[Insight-users] problems running and incoherent documentation in Chan-Vese segmentation examples

[Juan Cardelino]

=Introduction=

As much as I love open source and ITK in particular, this is the third
time I try to use contributed code to ITK and fail or invest a huge
amount of time understanding how to make it work.
I won't just criticize, but also offer my two cents. I'm willing to
help improving the documentation and the examples. I did this once
before without much echo from the community so this will be my last
try.

While I find the examples in the software guide nice and realistic,
sometimes they are too complex for a person trying to understand an
algorithm. Even if you deeply understand them (as in my case) case,
sometimes a very simple example helps you grasp the basics. In
addition, in simpler cases is clear what is a good result or not (for
instance in segmentation) while in a realistic case, a good result is
an elusive concept.

This time my problem is with the Chan-Vese level set filters. The
information I could find was the following:
*Insight journal:
**nice presentation and examples, but outdated code. This is
important, because the Insight journal code is the first hit you get
and you tend to download this. Just after you struggle with it you
realize that it won't work and look in the mailing lists. Then you
find out that there are examples buried in the Review folder. My
suggestion: remove all traces of code from IJ.
**In addition, within the papers there are examples of use that had
became obsoleted: names of methods and attributed have changed.
*Doxygen: the doxygen documentation is not complete for the main
clases involved, it is hard to find out what does each of the many
parameters of the algorithm exactly does. You have to deduce them from
the IJ submission (when available) and then translate them into the
actual names.
*ITK git code: there are two examples in the code:
**they only test the single phase scalar case in the dense and sparse versions
**they don't have any example usage (yes, again you can deduce this from IJ)
**they don't have any accompanying images.
*Kitware wiki:
**After struggling with the examples in the review folder (which
changed in last git update of the ITK source) I found out that in the
ITK wiki there were 3 examples of the Chan-Vese algorithm. Two were
the single phase spare and dense examples that used to be in the ITK
source tree and the other was the multiphase case (again, no images).

I'm not a newbie in ITK and I still find hard to grasp information
from 5 or more different sources which could also be potentially
contradictory.

I hope I'm doing something wrong and someone can point out where my
problems are. But I spent a lot of time and careful experimentation in
this, so I think there is something wrong.

I've summarized my whole experience at my wiki:
http://iie.fing.edu.uy/rs/wiki/ContributedCode:ITKChanVese, I hope
someone takes the time to read it. There, I will contribute a couple
of  simple examples just to say how I think they could be presented.
In addition, I'm posting comments on the existing examples. Finally, I
have an easy question:
*once a piece of code finds its way into ITK, what happens to the IJ
submission? Ideally it should go into the SoftwareGuide, but it also
seems hard to find a recent version of it (I even tried to get it from
the Insight Documents in CVS). Is there a place to contribute this
kind of documentation?

Thanks in advance.