[Insight-users] Unclear documentation for the new ImageScanlineIterator

[Bradley Lowekamp]

Hello Joel,

It looks like I only updated the documentation in the constant scanline iterator [1]. There is a sample usage there:


it = ImageScanlineConstIterator()
while ( !it.IsAtEnd() )
  {
  while ( !it.IsAtEndOfLine() )
    {
    *it += 100.0;
    ++it;
    }
  it.NextLine();
  }

As you can see from the same usage above, it uses two loops, unlike the ImageRegionIterator.

By using these two loops, all branching in side the iterator operations has been removed, this can result it better run-time execution, and enable advanced compiler optimizations such as auto-vectorization in some cases. When combine with only updating the progress on a per-scanline basis, it has been demonstrated a ~2X-3X performance in basic functor based filters.

If this iterator has the functionality you need I would use it.

You can see it's usage in the UnaryFunctorImageFilter [2].

It would be outstanding if you could update the documentation, with the information you expected to see there.

[1] http://www.itk.org/Doxygen/html/classitk_1_1ImageScanlineConstIterator.html
[2] https://github.com/Kitware/ITK/blob/master/Modules/Core/Common/include/itkUnaryFunctorImageFilter.hxx#L174

On Aug 1, 2013, at 4:59 AM, Joël Schaerer <joel.schaerer at gmail.com> wrote:

> Hi all,
> 
> I've just read in the Kitware source about the new ImageScanlineIterator which supposedly has better performance than the usual region iterators. Excited, I rush to the documentation to understand what this is about ... Unfortunately, this is all I get:
> 
> """
> A multi-dimensional iterator templated over image type that walks a region of pixels, scanline by scanline or in the direction of the fastest axis.
> 
> The itk::ImageScanlineConstIterator is optimized for iteration speed and is the first choice for pixel-wise operations on an image
> """
> 
> And this is what the documentation of the ImageRegionIterator claims:
> 
> """
> The itk::ImageRegionIterator is optimized for iteration speed and is the first choice for iterative, pixel-wise operations on an image
> """
> 
> So which is it? What are the limitations of the new iterator? When should you use one or the other? Why is it faster than the normal iterators, and why wasn't this change not applicable directly to the normal iterators?
> 
> After googling for a while, I found a little additional info in the commit: https://github.com/Kitware/ITK/commit/ab29cc59095d7448a1dbf1e09f96947036d2b118 , but it's still too sparse to understand without hunting in the source of the library.
> 
> If I get good answers, I'm willing to add them to the documentation, which should at the very least answer the following questions:
> 
> * Why is the new class needed?
> * How does it work, how does it differ from the existing iterators?
> * When should you use it and when should you not use it?
> 
> Thanks,
> 
> joel
> 
> _____________________________________
> Powered by www.kitware.com
> 
> Visit other Kitware open-source projects at
> http://www.kitware.com/opensource/opensource.html
> 
> Kitware offers ITK Training Courses, for more information visit:
> http://www.kitware.com/products/protraining.php
> 
> Please keep messages on-topic and check the ITK FAQ at:
> http://www.itk.org/Wiki/ITK_FAQ
> 
> Follow this link to subscribe/unsubscribe:
> http://www.itk.org/mailman/listinfo/insight-users

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://www.itk.org/pipermail/insight-users/attachments/20130801/827157bf/attachment.htm>