ITK Release 4/Image Class Hierarchy Refactoring

Image Class Hierarchy Refactoring

Motivation

The goal of this proposal is to add support for additional image types in ITK.

ITK currently supports several types of image:

• Image
• VectorImage
• SpecialCoordinatesImage
  • PhasedArray3DSpecialCoordinatesImage
• BloxImage
• SparseImage
• LabelMap
• ImageAdaptors and subclasses

With the exception of the PhasedArray3DSpecialCoordinatesImage, all the image types assume that the image topology is an n-dimensional lattice and that voxels have regular spacing in each dimension. While it makes sense to preserve the topology assumption in this refactoring, the assumption of regular spacing should be relaxed wherever possible. The regular spacing assumption covers many cases in biomedical imaging, but it hinders ITK's use in certain applications such as microscopy and remote sensing images. For example, certain motorized stages used in confocal microscopes fail to achieve regular spacing in z when acquiring a 3D image (often called a stack of 2D images at different focal depths). Helpfully, these stages report the positions of z-planes acquired during image stack collection. Assuming a regular z-spacing in place of the actual z-plane positions may result in significant errors in image analysis algorithms run on the image.

Goals

In particular, this proposal aims to provide two new kinds of image classes:

• Digital Image - no physical embedding; raw lattice of voxel values
• Rectilinear Image - physically embedded image with origin, irregular spacing in each dimension, and orientation

The existing Image class will be preserved, but will aliased to a new type:

• Regular Image - physically embedded image with origin, regular spacing, and orientation; essentially ITK's current Image class regular spacing

Each of the physically embedded image types will properly calculate transforms from indices to physical coordinates and back.

Secondary Goals

Merge VectorImages into Images. An Image is merely a VectorImage with a single component per voxel.

Requirements

• Make changes fully backwards compatible (all examples and tests should compile and run without modification and all tests should pass)

Challenges and Potential Pitfalls

• ImageAdaptors should present the correct interface for the image type they adapt. This can be accomplished with partial template specialization of the ImageAdaptor class to avoid modifying any of the existing adaptors.
• These filters exploit regular spacing of images to achieve high performance and will need to be modified to handle the new image types or throw an exception when they encounter an unsupported type:
  • [Fill these in as they are encountered]
• Filters that require voxel positions should always use methods TransformIndexToPhysicalPoint, etc.

Design

All image types will be subclasses of ImageBase, as they are now. ImageBase will be stripped to the bare minimum functionality required to support images with lattice topology. Subclasses will provide support for additional features.

The class hierarchy will look like this:

• ImageBase< unsigned int VDimension >
  • DigitalImage < class TPixel, unsigned int VDimension >
  • PhysicalImageBase < unsigned int VDimension >
    • RegularImageBase < unsigned int VDimension >
      • RegularImage < class TPixel, unsigned int VDimension >
      • Image (aliased to RegularImage) < class TPixel, unsigned int VDimension >
    • RectilinearImageBase < unsigned int VDimension >
      • RectilinearImage <class TPixel, unsigned in VDimension >

All Base classes specify the interface for only the metadata of the image. This design is required to support the method CopyInformation(). For example, you may encounter a situation where you copy information from a RegularImage<float, 3> to a RegularImage<double, 3>. Dynamic casting from a RegularImage<float, 3> to a RegularImage<double, 3> won't work, so the method will throw an exception. Casting a RegularImage<float, 3> to a RegularImageBase< 3 > will work, enabling access to the metadata methods (GetSpacing(), GetOrigin(), etc.) from the source image.

Specific methods defined or overridden in each class are provided below.

ImageBase

Methods:

• Allocate()
• ComputeIndex()
• ComputeOffset()
• ComputeOffsetTable()
• CopyInformation()
• GetBufferedRegion()
• GetImageDimension()
• GetLargestPossibleRegion()
• GetNumberOfComponentsPerPixel()
• GetOffsetTable()
• GetRequestedRegion()
• Graft() ?
• Initialize()
• InitializeBufferedRegion()
• RequestedRegionIsOutsideOfTheBufferedRegion()
• SetBufferedRegion()
• SetLargestPossibleRegion()
• SetNumberOfComponentsPerPixel()
• SetRequestedRegion(const RegionType &region)
• SetRequestedRegion(DataObject *data)
• SetRequestedRegionToLargestPossibleRegion()
• UpdateOutputData()
• UpdateOutputInformation()

DigitalImage

Methods overridden from ImageBase

• Allocate()
• CopyInformation()
• Graft() ?
• Initialize()
• InitializeBufferedRegion() ?
• UpdateOutputData() ?
• UpdateOutputInformation() ?

Additional methods

• GetPixel(const IndexType &index) const
• GetPixel(const IndexType &index)
• GetPixelAccessor(void)
• GetPixelAccessor(void) const
• GetPixelContainer()
• GetPixelContainer() const
• SetPixel(const IndexType &index, const TPixel &value)
• SetPixelContainer(PixelContainer *container)

PhysicalImageBase

Methods overridden from ImageBase

• Allocate()
• CopyInformation()
• Graft() ?
• Initialize()
• InitializeBufferedRegion() ?
• UpdateOutputData() ?
• UpdateOutputInformation() ?

Additional methods

• GetPixel(const IndexType &index) const
• GetPixel(const IndexType &index)
• GetPixelAccessor(void)
• GetPixelAccessor(void) const
• GetPixelContainer()
• GetPixelContainer() const
• SetPixel(const IndexType &index, const TPixel &value)
• SetPixelContainer(PixelContainer *container)
• GetOrigin()
• SetOrigin()
• GetDirection()
• SetDirection()

RegularImageBase

Methods overridden from PhysicalImageBase

• Allocate()
• CopyInformation()
• Graft() ?
• Initialize()
• InitializeBufferedRegion() ?
• UpdateOutputData() ?
• UpdateOutputInformation() ?

Additional methods

• ComputeIndexToPhysicalPointMatrices()
• GetSpacing()
• SetSpacing()
• TransformContinuousIndexToPhysicalPoint(const ContinuousIndex< TCoordRep, VImageDimension > &index, Point< TCoordRep, VImageDimension > &point) const
• TransformIndexToPhysicalPoint(const IndexType &index, Point< TCoordRep, VImageDimension > &point) const
• TransformLocalVectorToPhysicalVector(const FixedArray< TCoordRep, VImageDimension > &inputGradient, FixedArray< TCoordRep, VImageDimension > &outputGradient) const
• TransformPhysicalPointToContinuousIndex(const Point< TCoordRep, VImageDimension > &point, ContinuousIndex< TCoordRep, VImageDimension > &index) const
• TransformPhysicalPointToIndex(const Point< TCoordRep, VImageDimension > &point, IndexType &index) const

RegularImage

Methods overridden from RegularImageBase

• Allocate()
• CopyInformation()
• Graft() ?
• Initialize()
• InitializeBufferedRegion() ?
• UpdateOutputData() ?
• UpdateOutputInformation() ?

Additional methods

• GetPixel(const IndexType &index) const
• GetPixel(const IndexType &index)
• GetPixelAccessor(void)
• GetPixelAccessor(void) const
• GetPixelContainer()
• GetPixelContainer() const
• SetPixel(const IndexType &index, const TPixel &value)
• SetPixelContainer(PixelContainer *container)

RectilinearImageBase

Methods overridden from PhysicalImageBase

• Allocate()
• CopyInformation()
• Graft() ?
• Initialize()
• InitializeBufferedRegion() ?
• UpdateOutputData() ?
• UpdateOutputInformation() ?

Additional methods

• GetDimensionSpacing(unsigned int dimension)
• SetDimensionSpacing(unsigned int dimension, Array<PointValueType>)
• TransformContinuousIndexToPhysicalPoint(const ContinuousIndex< TCoordRep, VImageDimension > &index, Point< TCoordRep, VImageDimension > &point) const
• TransformIndexToPhysicalPoint(const IndexType &index, Point< TCoordRep, VImageDimension > &point) const
• TransformLocalVectorToPhysicalVector(const FixedArray< TCoordRep, VImageDimension > &inputGradient, FixedArray< TCoordRep, VImageDimension > &outputGradient) const
• TransformPhysicalPointToContinuousIndex(const Point< TCoordRep, VImageDimension > &point, ContinuousIndex< TCoordRep, VImageDimension > &index) const
• TransformPhysicalPointToIndex(const Point< TCoordRep, VImageDimension > &point, IndexType &index) const

RectilinearImage

Methods overridden from RectilinearImageBase

• Allocate()
• CopyInformation()
• Graft() ?
• Initialize()
• InitializeBufferedRegion() ?
• UpdateOutputData() ?
• UpdateOutputInformation() ?

Additional methods

• GetPixel(const IndexType &index) const
• GetPixel(const IndexType &index)
• GetPixelAccessor(void)
• GetPixelAccessor(void) const
• GetPixelContainer()
• GetPixelContainer() const
• SetPixel(const IndexType &index, const TPixel &value)
• SetPixelContainer(PixelContainer *container)