[Insight-users] Re: direction API misleading

[Simon Warfield]

The problem is that itk::Image inherits an API from itk::ImageBase to 
store and manipulate Directions, just like an OrientedImage,
but doesn't act on them.  It is particularly confusing for new users - 
what developer would expect us to design an image class that has 
directions but ignores them ?

Similarly, there has been some confusion as to whether a VectorImage or 
a VariableLengthVectorImage or VectorImageToImageAdaptor or an 
ImageAdaptor is supposed to correctly support orientation information. 
These classes have an API for storing Direction information, but have 
not utilized the Direction information in calculations involving 
physical space.

Until a few months ago, the ImageAdaptor also didn't correctly 
manipulate Direction:
http://www.itk.org/cgi-bin/viewcvs.cgi/Code/Common/itkImageAdaptor.txx?root=Insight&r1=1.42&r2=1.43
and
http://www.itk.org/cgi-bin/viewcvs.cgi/Code/Common/itkImageAdaptor.h?rev=1.64&root=Insight&view=markup

It has been hard to tell if the ImageAdaptor was implemented 
incorrectly, or if it was simply intended to have Direction information 
but not use it, because the interface that exposes direction information 
is used in classes that use direction information and in classes that do 
not use direction information (itkOrientedImage and itkImage).

As an example of a misleading API, VectorImage inherits from ImageBase 
the ability to store and manipulate Direction information.
When doing so, it has no impact whatsoever on the directions used by the 
class, and there is no compile time or run-time error generated.
This is because the TransformIndexToPhysicalPoint and 
TransformPhysicalPointToIndex do not make use of the available direction 
information.

It would be clear how these derived classes worked if ImageBase did not 
support Direction information, but instead only OrientedImage provided a 
Direction API. In this case, an attempt to utilize Direction information 
in a class that ignored that information would be a compile time error.
This would make it easier for new users to understand the intention of 
the developers.

Alternatively, it would be possible to implement:
itkOrientedVectorImage
itkOrientedVariableLengthVectorImage


Here is a quiz:
if you have coordinates in physical space, and you would like to access 
pixels at a certain index in a component of a vector image,
is VectorImageToImageAdaptor suitable for this or not ?

Answer:
ImageAdaptor now supports the correct storing and passing of direction 
information,  but inherits the transforming of physical indexes from the 
base image type.  If the base image type is OrientedImage then direction 
information is utilized, and physical coordinates can be used correctly.
 However, a VectorImageToImageAdaptor is defined as:
template<class TPixelType, unsigned int Dimension>
class ITK_EXPORT VectorImageToImageAdaptor : public
      ImageAdaptor< VectorImage< TPixelType, Dimension >,
        Accessor::VectorImageToImagePixelAccessor< TPixelType > >
so the base class is a VectorImage, and a VectorImage presents an API to 
transform from physical to index space that does not utilize the 
Direction information. Therefore, the index corresponding to a 
particular physical location returned by an VectorImageToImageAdaptor is 
not calculated taking into account any orientation information that may 
be stored in the m_Direction class member that the image holds.  
Although you may set the direction to be a non-identity transform, and 
manipulate it, it does not play a role in transforming coordinates.  If 
you thought it was going to, then the pixel indexes that are returned 
will be incorrect for you.

I would argue that the API for orientation in image classes should not 
be surprising in this way.

--
Simon


> The gradient problem is being corrected for itkOrientedImage. See:
> http://public.kitware.com/Bug/view.php?id=5081
>
> If you need to take into account orientation, you should use
> itkOrientedImage. Another option is to use itkImage and reorient the series
> with itkOrientImageFilter so that both series have the same orientation.
>
> Bill
> On Fri, Feb 1, 2008 at 4:18 AM, Stefan Klein <stefan at isi.uu.nl> wrote:
>
>   
>> > Hi,
>> >
>> > Jeroen: the Origin IS taken into account. The Direction indeed not. I
>> > agree
>> > with it that this should be emphasised somewhere in the documentation.
>> > It's
>> > very easy to make a mistake with that.
>> >
>> > Kind regards,
>> > Stefan.
>> >
>> >
>> >
>> > At 10:02 1-2-2008, J.S.Wijnhout at lumc.nl wrote:
>> >
>>     
>>> > >Hi,
>>> > >
>>> > >
>>> > >
>>> > >I have faced (or am facing actually) the same problem. I found it
>>> > >espacially confusing that the itk::Image has a GetDirection and GetOrigin
>>> > >method, however these are apparently not used in the
>>> > >TransformContinuousIndexToPhysicalPoint method. If you want that, you
>>> > >should use the itk::OrientedImage. But be warned, in the calculation of
>>> > >the metric the orientation is ignored while computing the gradient. I
>>> > >concluded that it is best to resample your image such that both images,
>>> > >fixed and moving, have the same orientation. It is a bit cumbersome, but
>>> > >it works and the results should not be too different from the results you
>>> > >would get if the registration would properly using the image orientation.
>>> > >Still I would like that orientation and origin are consistently used
>>> > >within ITK (at the very least this behavior should  be properly
>>>       
>> > documented!).
>>     
>>> > >
>>> > >
>>> > >
>>> > >best,
>>> > >
>>> > >Jeroen


-- 
Simon