NA-MIC National Alliance for Medical Image Computing ITK Workshop October 5-8, 2005 Software Design.

NA-MICNational Alliance for Medical Image Computing http://na-mic.org

ITK Workshop

October 5-8, 2005

Software Design

National Alliance for Medical Image Computing http://na-mic.org

ITK Workshop – Open Source Viewers

• Design Patterns– Pipeline– Decorators– Iterators– Adaptors– Accessors– Functors– Factories– Traits

The Data Pipeline

Insight Toolkit - Advanced Course

The Data Pipeline

DataObject

ProcessObject

DataObject

ProcessObject

DataObject

Who owns the Output ?

DataObject

ProcessObject

The ProcessObject allocates and owns its output

Therefore the output is const

• Instantiate the filters types

• Construct the filters with New()

• Connect SetInput() GetOutput()

• Set filter Parameters

• Invoke Update() in the last filter

How to use the Pipeline ?

• Modify the filter parameters

• Invoke Update() in the last filter

The Pipeline is intended to be Re-Executed

Only the filters that need to re-compute their output will be re-executed

Updating the Pipeline

ImageReader

FilterA

FilterB

FilterC

FilterD

ImageWriter

ImageReader

FilterA

FilterB

FilterC

FilterD

ImageWriter

Execute

Execute Execute

Execute

Update()

ImageReader

FilterA

FilterB

FilterC

FilterD

ImageWriter

ExecuteExecute Execute Execute

Update()

ImageReader

FilterA

FilterB

FilterC

FilterD

ImageWriter

Execute Execute

Update()SetParameter

I’m OK I’m OK

• itk::Object has a TimeStamp

• Invoking Modified() updates the stamp

• SetParameter() methods calls Modified()

• Most Set() methods use itkSetMacro()

• If you write your own SetParameter() you must remember to invoke Modified()

How it works internally

What will go wrong with your filter if you create a SetParameter() method and forget to invoke Modified() from it ?

Quiz !

It will run fine the first time but if you call SetParameter() and then call Update() the filter will not re-execute.

Open the itkMacro.h file in

Insight/Code/Common

Exercise

Find the itkSetMacro() and identify the line where Modified() is invoked

Pervasive Pipelining

(or the Ode to Intelligent Design)

In the Beginning… there was the itk::DataObject

The itk::DataObject originated the itk::Image and the itk::Mesh

Only the the itk::DataObject and his sons were admited in the Pipeline garden

The float, ints, Transforms and Pointsgrew jealous of the DataObject

Since they could not promenade in the Pipeline Garden

So in chorus they asked to change the ways of the Pipeline garden

And from the darkness of the abyss the itk::DataObjectDecorator was born.

With it,the float, ints, Transforms and Points became as DataObjects and walked at their will in the Pipeline Garden.

#include “itkDataObject.h”

template<class T>class SimpleDataObjectDecorator : public DataObject{public: typedef SimpleDataObjectDecorator Self; typedef DataObject Superclass; typedef SmartPointer< Self > Pointer; typedef SmartPointer< const Self > ConstPointer;

itkNewMacro( Self );

itkTypeMacro( SimpleDataObjectDecorator, DataObject );

private: T m_Component;

The SimpleDataObjectDecorator

public: virtual void Set( const T & value ) { if( m_Component != value ) { m_Component = value; this->Modified(); } }

virtual const T & Get() const { return m_Component }

The SimpleDataObjectDecorator

#include “itkDataObject.h”

template<class T>class DataObjectDecorator : public DataObject{public: typedef DataObjectDecorator Self; typedef DataObject Superclass; typedef SmartPointer< Self > Pointer; typedef SmartPointer< const Self > ConstPointer;

itkNewMacro( Self );

itkTypeMacro(DataObjectDecorator, DataObject );

private: typename T::Pointer m_Component;

The DataObjectDecorator

public: virtual void Set( const T * value ) { if( m_Component != value ) { m_Component = value; this->Modified(); } }

virtual const T * Get() const { return m_Component }

The DataObjectDecorator

Iterators

• STL Iterators

• Image Iterators– Region– Linear– Slice

• Mesh Iterators– VectorContainer– MapContainer

Iterators

#include <vector>

typedef std::vector< float > VectorType;

VectorType myVector;

myVector.push_back( 4 );myVector.push_back( 7 );myVector.push_back( 19 );

VectorType::const_iterator itr = myVector.begin();

while( itr != myVector.end() ) { std::cout << *itr << std::endl; ++itr; }

STL Iterators

for( unsigned int z = 0; z < Nz; z++ ) { for( unsigned int y = 0; y < Ny; y++ ) { for( unsigned int x = 0; x < Nx; x++ ) {

image[z][y][x] = … // pixel access

Image Iterators

The Evil nested loop and the Dimensional Trap

How to generalize this code to 2D, 3D, 4D …?

#include “itkImage.h”#include “itkImageRegionIterator.h”

typedef itk::Image< float, 3 > ImageType;typedef itk::ImageRegionConstIterator< ImageType > IteratorType;

ImageType::ConstPointer image = GetConstImageSomeHow();

ImageType::RegionType region = image->GetLargestPossibleRegion();

IteratorType itr( image, region );itr.GoToBegin();

while( ! itr.IsAtEnd() ) { std::cout << itr.Get() << std::endl; ++itr; }

Image Iterators (const)

#include “itkImage.h”#include “itkImageRegionIterator.h”

typedef itk::Image< float, 3 > ImageType;typedef itk::ImageRegionIterator< ImageType > IteratorType;

ImageType::Pointer image = GetNonConstImageSomeHow();

ImageType::RegionType region = image->GetLargestPossibleRegion();

IteratorType itr( image, region );itr.GoToBegin();

while( ! itr.IsAtEnd() ) { itr.Set( 0 ); ++itr; }

Image Iterators (non-const)

#include “itkImage.h”#include “itkImageLinearIteratorWithIndex.h”

typedef itk::Image< float, 3 > ImageType;typedef itk::ImageLinearConstIteratorWithIndex< ImageType > IteratorType;

ImageType::ConstPointer image = GetConstImageSomeHow();ImageType::RegionType region = GetImageRegionSomeHow();IteratorType itr( image, region );

for( itr.GoToBegin(); !itr.IsAtEnd(); itr.NextLine() ) { while( ! itr.IsAtEndOfLine() ) { std::cout << itr.Get() << “:“ << itr.GetIndex() << std::endl; ++itr; } }

Image Linear Iterator (const)

#include “itkImageSliceIteratorWithIndex.h”

typedef itk::ImageSliceConstIteratorWithIndex<ImageType> IteratorType;

ImageType::ConstPointer image = GetConstImageSomeHow();ImageType::RegionType region = GetImageRegionSomeHow();IteratorType itr( image, region );

for( itr.GoToBegin(); !itr.IsAtEnd(); itr.NextSlice() ) { for( ; ! itr.IsAtEndOfSlice(); itr.NextLine() ) { for( ; ! itr.IsAtEndOfLine(); ++itr ) { std::cout << itr.Get() << “:“ << itr.GetIndex() << std::endl; } } }

Image Slice Iterator (const)

Using the ImageLinearIterator

Exercise 28

Use two ImageLinearIterators in order to flip and image across its diagonal

• Reflective Image Iterator

• Neighborhood Iterator

• Shaped Neighborhood Iterator

• Image Random Iterator

• Image Random Non Repeating Iterator

• Flood Filled Function Conditional Iterator

• Path Iterator

Other Image Iterators

• Iterators absorb a large portion of the complexity in an Image Filter

• Iterators made possible to generalize ITK to N-Dimensional images

• Iterators allows to have fast access to pixel data

• Iterators made ImageAdaptors possible (see later)

Importance of Image Iterators

#include “itkMesh.h”

typedef itk::Mesh< float, 3 > MeshType;

MeshType::ConstPointer mesh = GetConstMeshSomeHow();

typedef MeshType::PointsContainer PointsContainer;typedef PointsContainer::ConstIterator PointsIterator;

PointsContainer points = mesh->GetPoints();PointsIterator pointItr = points->Begin();

while( pointItr != points->End() ) { MeshType::PointsType point = pointItr.Value(); std::cout << “point “ << point << std::endl; ++pointItr; }

Mesh Iterators (const)

Image Adaptors

(Things are not always what they seem)

Some operations are too simple for a filter

Image ImageProcessObject

Image Filter

ImageFake

ImageImage

Adaptor

Image Adaptor

Pixel Accessor

ImageFake

ImageImage

Adaptor

Image Adaptors = Image Iterators + Pixel Accessors

Pixel Accessor Pixel Accessor

Where the transformation is done

Pixel Accessor and Image Iterators

Image Image Iterator

Pixel Accessor and Image Iterators

Image Image Iterator

itr.Get()

m_PixelAccessorFunctor.Get( *( m_Buffer + m_Offset ));

namespace Accessor {

class RedChannel { public: typedef itk::RGBPixel<float> InternalType; typedef float ExternalType; static ExternalType Get()( const InternalType & A ) { return static_cast< ExternalType >( A.GetRed() ); } };

} // end of Accessor namespace

Pixel Accessor : Red Channel from RGB Image

int main() {typedef Accessor::RedChannel::InternalType InternalPixelType;

typedef itk::Image< InternalPixelType, 2 > AdaptedImageType;

typedef itk::ImageAdaptor< AdaptedImageType, Accessor::RedChannel >ImageAdaptorType; ImageAdaptorType::Pointer adaptor = ImageAdaptorType::New();

typedef itk::ImageFilterReader< AdaptedImageType > ReaderType; ReaderType::Pointer reader = ReaderType::New();

adaptor->SetImage( reader->GetOutput() );

Using the Pixel Accessor in the Image Adaptor

• Image Adaptors are like Images

• Image Adaptors are not Filters

• Image Adaptors do not have Buffers

• Not all Iterators support Image Adaptors

• Not all Filters support Image Adaptors

Image Adaptors

typedef itk::Image< unsigned char, 2 > OutputImageType;

typedef itk::RescaleIntensityImageFilter< ImageAdaptorType, OutputImageType > FilterType; FilterType::Pointer filter = FilterType::New();

filter->SetInput( adaptor ); // Adaptors are like Images !!

writer->SetInput( filter->GetOutput() );

writer->Update(); }

Using the Pixel Accessor in the Image Adaptor

Image Adaptors

Pierce the Illusion…

to see the Void.

• Writers access Image’s buffer directly,They are not fooled by Image Adaptors.

• Neigborhood Iterators do not call theGet() method…They are not fooled by Image Adaptors.

Image Adaptors

Exercise 27

Write a Pixel Accessor that will invert the intensities in an image.

Instantiate its corresponding Image Adaptor

namespace Accessor {

class Inversor { public: typedef unsigned char InternalType; typedef unsigned char ExternalType; static ExternalType Get()( const InternalType & A ) { return static_cast< ExternalType >( 255 - A ); } };

} // end of Accessor namespace

Pixel Accessor : Invert 8-bits intensities.

Functors

The Way takes no action, but leaves nothing undone

namespace Functor {

template< class TInput, class TOutput> class Doubler { public: Doubler() {}; ~Doubler() {}; inline TOutput operator()( const TInput & A ) { return static_cast<TOutput>( 2.0 * A ); } };

} // end of Functor namespace

Functors

A Functor is a class that looks like a Function

typedef Functor::Doubler< int, int > FunctorType;

FunctorType iDouble;

int input = 197.0;

int result = iDouble( input );

Functors

Functors are used as functions

Functors are used by

• UnaryFuncturImageFilter<>• BinaryFunctorImageFilter<>• TernaryFunctorImageFilter<>

Functors make possible to factorize all other operations of an image filter

Factories

The origin of the world is its mother;Understand the mother, and you understand the child

Tao Te Ching

The Class Hierarchy of Factories

itk::ObjectFactoryBaseitk::DataObject

itk::Object

itk::ObjectFactory

itk::LightObject

itk::ProcessObject

What happens when we invoke ::New() ?

itk::LightObject

itk::ObjectFactory<T>

Create()

CreateInstance( typeid(T) )

itk::ObjectFactoryBase

Iterate over Registered Factories

CreateObject( classname)return pointer, or NULL

if NULL call “new”

Factories

RegisteredFactories std::list< ObjectFactoryBase *>static

static void RegisteredFactory( ObjectFactoryBase *)

ObjectFactory X

ObjectFactory Y

ObjectFactory Z

ObjectFactory W

Factories can be loaded as Dynamic Libraries

LoadLibrariesInPath( char * path )static

itk::DynamicLoader

From pathget all filenamesthat are shared libraries

GetSymbolAddress()

OpenLibrary( fname)

RegisterFactory( ObjectFactoryBase* )static

Loading Dynamic Factories

• Set environment variable ITK_AUTOLOAD_PATH

• In the Shared library create an itkLoad() functionthat returns an itk::ObjectFactoryBase *

• Compile the shared library using CMake commandADD_LIBRARY( Name SHARED …sources…)

• Copy the shared library in one of the directories in ITK_AUTOLOAD_PATH

Image Adaptors

Exercise 29

Create a simple Factory

Use the same structure for replacingan existing ITK class

Creating my own Factory

itk::MyOwnFactory

• static itkLoad();• FactoryLessNewMacro();• FactoryNew();• GetITKSourceVersion();• GetDescription();• RegisterOneFactory();• MyOwnFactory(); // constructor• ~MyOwnFactory(); // destructor

Traits

Knowing others is Wisdom

Knowing the Self is Enlightenment

Tao Te Ching

Traits

• Types declared inside another Type

• Fundamental for enforcing consitency

#include “itkImageBase.h”

template<class TPixel, unsigned int VDimension>class Image : public ImageBase< VDimension >{public: typedef Image Self; typedef ImageBase< VDimension > Superclass; typedef SmartPointer< Self > Pointer; typedef SmartPointer< const Self > ConstPointer;

itkNewMacro( Self ); itkTypeMacro(Image, ImageBase );

typedef TPixel PixelType;

itkStaticConstMacro(ImageDimension, unsigned int, VDimension);

Traits Examples

#include “itkImage.h”

int main( int, char * argv []) {typedef itk::Image< unsigned char, 2 > ImageType;

typedef itk::ImageFilterReader< ImageType > ReaderType; ReaderType::Pointer reader = ReaderType::New();reader->SetFileName( argv[1] );

ImageType::ConstPointer image = reader->GetOutput();

ImageType::IndexType index;index.Fill(0);

ImageType::PixelType pixel = reader->GetPixel( index );

Use Traits instead of redundant declarations !

template <class TImage>class ImageFilter {public: typedef TImage ImageType; const ImageType * GetImage() const;private: typename ImageType::ConstPointer m_Image;};

template <class TImage>const typename ImageFilter<TImage>::ImageType *ImageFilter<TImage>::GetImage() const{ return m_Image;}

Very Important in Return Types…

template <class TImage>class ImageFilter { typename TImage::ConstPointer m_Image;};

Note the use of typename

You need typename if all the following applies

• You are in a templated class• You are accessing a trait from a class that

depends on the template arguments of your current class.

Compilers and typename

The keyword typename is supported differenty by different compilers

• Totally ignored by Visual Studio 6.0• Supported in Visual Studio 7.0 and 7.1• Required in gcc 3.2, gcc 3.3• Implicit typenames not supported in gcc 3.4

NA-MIC National Alliance for Medical Image Computing ITK Workshop October 5-8, 2005 Software Design.

medical image computing

pipeline image reader

update slide

pipeline garden slide

namic national alliance

mesh slide

reexecuted slide

intelligent design slide

Documents

NA-MIC National Alliance for Medical Image Computing ...

NA-MIC National Alliance for Medical Image Computing ...

NA-MIC National Alliance for Medical Image Computing 3D...

NA-MIC National Alliance for Medical Image Computing ...

NA-MIC National Alliance for Medical Image Computing...

NA-MIC National Alliance for Medical Image Computing Slicer...

NA-MIC National Alliance for Medical Image Computing ...

NA-MIC National Alliance for Medical Image Computing ...

NA-MIC National Alliance for Medical Image Computing Skull....

VFPI - ITK

NA-MIC National Alliance for Medical Image Computing ITK...

ITK - InTheKnow

NA-MIC National Alliance for Medical Image Computing ...

NA-MIC National Alliance for Medical Image Computing ...

UNIVERGE SV9100 DT930/DT920 (ITK-8TCGX/ITK-8LCX) User...

NA-MIC National Alliance for Medical Image Computing