ITK  4.0.0
Insight Segmentation and Registration Toolkit
Public Types | Public Member Functions | Static Public Member Functions | Static Public Attributes | Protected Member Functions | Private Member Functions | Private Attributes
itk::WatershedImageFilter< TInputImage > Class Template Reference

A low-level image analysis algorithm that automatically produces a hierarchy of segmented, labeled images from a scalar-valued image input. More...

#include <itkWatershedImageFilter.h>

Inheritance diagram for itk::WatershedImageFilter< TInputImage >:
Collaboration diagram for itk::WatershedImageFilter< TInputImage >:

List of all members.

Public Types

typedef InputImageType::IndexType IndexType
typedef TInputImage InputImageType
typedef Image< IdentifierType,
itkGetStaticConstMacro(ImageDimension) > 
OutputImageType
typedef SmartPointer< SelfPointer
typedef InputImageType::RegionType RegionType
typedef InputImageType::PixelType ScalarType
typedef WatershedImageFilter Self
typedef InputImageType::SizeType SizeType
typedef ImageToImageFilter
< InputImageType,
OutputImageType
Superclass

Public Member Functions

virtual ::itk::LightObject::Pointer CreateAnother (void) const
void EnlargeOutputRequestedRegion (DataObject *data)
void GenerateData ()
virtual const char * GetNameOfClass () const
watershed::SegmentTreeGenerator
< ScalarType >
::SegmentTreeType * 
GetSegmentTree ()
 typedef (Concept::LessThanComparable< ScalarType >) InputLessThanComparableCheck
 typedef (Concept::AdditiveOperators< ScalarType >) InputAdditiveOperatorsCheck
 typedef (Concept::MultiplyOperator< double, ScalarType, ScalarType >) DoubleInputMultiplyOperatorCheck
 typedef (Concept::EqualityComparable< ScalarType >) InputEqualityComparableCheck
void SetInput (const InputImageType *input)
virtual void SetInput (unsigned int i, const TInputImage *image)
void SetThreshold (double)
virtual double GetThreshold () const
void SetLevel (double)
virtual double GetLevel () const
watershed::Segmenter
< InputImageType >
::OutputImageType
GetBasicSegmentation ()

Static Public Member Functions

static Pointer New ()

Static Public Attributes

static const unsigned int ImageDimension = TInputImage::ImageDimension

Protected Member Functions

virtual void PrepareOutputs ()
 WatershedImageFilter ()
virtual ~WatershedImageFilter ()
void PrintSelf (std::ostream &os, Indent indent) const

Private Member Functions

void operator= (const Self &)
 WatershedImageFilter (const Self &)

Private Attributes

TimeStamp m_GenerateDataMTime
bool m_InputChanged
double m_Level
bool m_LevelChanged
unsigned long m_ObserverTag
watershed::Relabeler
< ScalarType,
itkGetStaticConstMacro(ImageDimension) >
::Pointer 
m_Relabeler
watershed::Segmenter
< InputImageType >::Pointer 
m_Segmenter
double m_Threshold
bool m_ThresholdChanged
watershed::SegmentTreeGenerator
< ScalarType >::Pointer 
m_TreeGenerator

Detailed Description

template<class TInputImage>
class itk::WatershedImageFilter< TInputImage >

A low-level image analysis algorithm that automatically produces a hierarchy of segmented, labeled images from a scalar-valued image input.

Overview and terminology
This filter implements a non-streaming version of an image segmentation algorithm commonly known as ``watershed segmentation''. Watershed segmentation gets its name from the manner in which the algorithm segments regions into catchment basins. If a function $ f $ is a continuous height function defined over an image domain, then a catchment basin is defined as the set of points whose paths of steepest descent terminate at the same local minimum of $ f $.
The choice of height function (input) depends on the application, and the basic watershed algorithm operates independently of that choice. For intensity-based image data, you might typically use some sort of gradient magnitude calculation as input. (see itk::GradientMagnitudeImageFilter)
The watershed algorithm proceeds in several steps. First, an initial classification of all points into catchment basin regions is done by tracing each point down its path of steepest descent to a local minima. Next, neighboring regions and the boundaries between them are analyzed according to some saliency measure (such as minimum boundary height) to produce a tree of merges among adjacent regions. These merges occur at different maximum saliency values. The collective set of all possible merges up to a specified saliency ``flood level'' is referred to in this documentation as a ``merge tree''. Metaphorically, the flood level is a value that reflects the amount of precipitation that is rained into the catchment basins. As the flood level rises, boundaries between adjacent segments erode and those segments merge. The minimum value of the flood level is zero and the maximum value is the difference between the highest and lowest values in the input image.
Note that once the initial analysis and segmentation is done to produce the merge tree, it is trivial to produce a hierarchy of labeled images in constant time. The complexity of the algorithm is in the computation of the merge tree. Once that tree has been created, the initial segmented image can be relabeled to reflect any maximum saliency value found in the tree by simply identifying a subset of segment merges from the tree.
Implementational details
This filter is a wrapper for several lower level process objects (watershed algorithm components in the namespace ``watershed''). For a more complete picture of the implementation, refer to the documentation of those components. The component classes were designed to operate in either a data-streaming or a non-data-streaming mode. The pipeline constructed in this class' GenerateData() method does not support streaming, but is the common use case for the components.
Description of the input to this filter
The input to this filter is a scalar itk::Image of any dimensionality. This input image is assumed to represent some sort of height function or edge map based on the original image that you want to segment (such as would be produced by itk::GradientMagnitudeImageFilter). This filter does not do any pre-processing on its input other than a thresholding step. The algorithm does not explicitly require that the input be of any particular data type, but floating point or double precision data is recommended.
The recommended pre-processing for scalar image input to this algorithm is to use one of the itk::AnisotropicDiffusionImageFilter subclasses to smooth the original image and then perform some sort of edge calculation based on gradients or curvature.
Description of the output of this filter
This filter will produce an itk::Image of IdentifierType integer type and of the same dimensionality as the input image. The IdentifierType output image is referred to as the ``labeled image'' in this documentation. Each pixel in the image is assigned an IdentifierType integer label that groups it within a connected region.
Some notes on filter parameters
Two parameters control the output of this filter, Threshold and Level. The units of both parameters are percentage points of the maximum height value in the input.
Threshold is used to set the absolute minimum height value used during processing. Raising this threshold percentage effectively decreases the number of local minima in the input, resulting in an initial segmentation with fewer regions. The assumption is that the shallow regions that thresholding removes are of of less interest.
The Level parameter controls the depth of metaphorical flooding of the image. That is, it sets the maximum saliency value of interest in the result. Raising and lowering the Level influences the number of segments in the basic segmentation that are merged to produce the final output. A level of 1.0 is analogous to flooding the image up to a depth that is 100 percent of the maximum value in the image. A level of 0.0 produces the basic segmentation, which will typically be very oversegmented. Level values of interest are typically low (i.e. less than about 0.40 or 40% ), since higher values quickly start to undersegment the image.
The Level parameter can be used to create a hierarchy of output images in constant time once an initial segmentation is done. A typical scenario might go like this: For the initial execution of the filter, set the Level to the maximum saliency value that you anticipate might be of interest. Once the initial Update() of this process object has finished, the Level can be manipulated anywhere below the initial setting without triggering a full update of the segmentation mini-pipeline. All that is now be required to produce the new output is a simple relabeling of the output image.
Threshold and Level parameters are controlled through the class' Get/SetThreshold() and Get/SetLevel() methods.
Notes on streaming the watershed segmentation code
Coming soon... 12/06/01

Definition at line 150 of file itkWatershedImageFilter.h.


Member Typedef Documentation

template<class TInputImage >
typedef InputImageType::IndexType itk::WatershedImageFilter< TInputImage >::IndexType

Definition at line 171 of file itkWatershedImageFilter.h.

template<class TInputImage >
typedef TInputImage itk::WatershedImageFilter< TInputImage >::InputImageType
template<class TInputImage >
typedef Image< IdentifierType, itkGetStaticConstMacro(ImageDimension) > itk::WatershedImageFilter< TInputImage >::OutputImageType
template<class TInputImage >
typedef SmartPointer< Self > itk::WatershedImageFilter< TInputImage >::Pointer
template<class TInputImage >
typedef InputImageType::RegionType itk::WatershedImageFilter< TInputImage >::RegionType

Other convenient typedefs

Definition at line 169 of file itkWatershedImageFilter.h.

template<class TInputImage >
typedef InputImageType::PixelType itk::WatershedImageFilter< TInputImage >::ScalarType

Typedef support for the input image scalar value type.

Definition at line 177 of file itkWatershedImageFilter.h.

template<class TInputImage >
typedef WatershedImageFilter itk::WatershedImageFilter< TInputImage >::Self
template<class TInputImage >
typedef InputImageType::SizeType itk::WatershedImageFilter< TInputImage >::SizeType

Definition at line 170 of file itkWatershedImageFilter.h.

template<class TInputImage >
typedef ImageToImageFilter< InputImageType, OutputImageType > itk::WatershedImageFilter< TInputImage >::Superclass

Constructor & Destructor Documentation

template<class TInputImage >
itk::WatershedImageFilter< TInputImage >::WatershedImageFilter ( ) [protected]

End concept checking

template<class TInputImage >
virtual itk::WatershedImageFilter< TInputImage >::~WatershedImageFilter ( ) [inline, protected, virtual]

End concept checking

Definition at line 263 of file itkWatershedImageFilter.h.

template<class TInputImage >
itk::WatershedImageFilter< TInputImage >::WatershedImageFilter ( const Self ) [private]

Member Function Documentation

template<class TInputImage >
virtual::itk::LightObject::Pointer itk::WatershedImageFilter< TInputImage >::CreateAnother ( void  ) const [virtual]

Create an object from an instance, potentially deferring to a factory. This method allows you to create an instance of an object that is exactly the same type as the referring object. This is useful in cases where an object has been cast back to a base class.

Reimplemented from itk::Object.

template<class TInputImage >
void itk::WatershedImageFilter< TInputImage >::EnlargeOutputRequestedRegion ( DataObject ) [virtual]

Give the process object a chance to indictate that it will produce more output than it was requested to produce. For example, many imaging filters must compute the entire output at once or can only produce output in complete slices. Such filters cannot handle smaller requested regions. These filters must provide an implementation of this method, setting the output requested region to the size they will produce. By default, a process object does not modify the size of the output requested region.

Reimplemented from itk::ProcessObject.

template<class TInputImage >
void itk::WatershedImageFilter< TInputImage >::GenerateData ( ) [virtual]

Standard process object method. This filter is not multithreaded.

Reimplemented from itk::ImageSource< Image< IdentifierType,::itk::GetImageDimension< TInputImage >::ImageDimension > >.

template<class TInputImage >
watershed::Segmenter< InputImageType >::OutputImageType* itk::WatershedImageFilter< TInputImage >::GetBasicSegmentation ( ) [inline]

Get the basic segmentation from the Segmenter member filter.

Definition at line 231 of file itkWatershedImageFilter.h.

References itk::DataObject::Update().

template<class TInputImage >
virtual double itk::WatershedImageFilter< TInputImage >::GetLevel ( ) const [virtual]

Set/Get the input thresholding parameter. Units are a percentage of the maximum depth in the image.

template<class TInputImage >
virtual const char* itk::WatershedImageFilter< TInputImage >::GetNameOfClass ( ) const [virtual]
template<class TInputImage >
watershed::SegmentTreeGenerator< ScalarType >::SegmentTreeType* itk::WatershedImageFilter< TInputImage >::GetSegmentTree ( ) [inline]

Get the segmentation tree from from the TreeGenerator member filter.

Definition at line 240 of file itkWatershedImageFilter.h.

template<class TInputImage >
virtual double itk::WatershedImageFilter< TInputImage >::GetThreshold ( ) const [virtual]

Set/Get the input thresholding parameter. Units are a percentage of the maximum depth in the image.

template<class TInputImage >
static Pointer itk::WatershedImageFilter< TInputImage >::New ( ) [static]

Method for creation through the object factory.

Reimplemented from itk::Object.

template<class TInputImage >
void itk::WatershedImageFilter< TInputImage >::operator= ( const Self ) [private]

PushBackInput(), PushFronInput() in the public section force the input to be the type expected by an ImageToImageFilter. However, these methods end of "hiding" the versions from the superclass (ProcessObject) whose arguments are DataObjects. Here, we re-expose the versions from ProcessObject to avoid warnings about hiding methods from the superclass.

Reimplemented from itk::ImageToImageFilter< TInputImage, Image< IdentifierType,::itk::GetImageDimension< TInputImage >::ImageDimension > >.

template<class TInputImage >
virtual void itk::WatershedImageFilter< TInputImage >::PrepareOutputs ( ) [protected, virtual]

An opportunity to Allocate/Deallocate bulk data.

Reimplemented from itk::ProcessObject.

template<class TInputImage >
void itk::WatershedImageFilter< TInputImage >::PrintSelf ( std::ostream &  os,
Indent  indent 
) const [protected, virtual]
template<class TInputImage >
virtual void itk::WatershedImageFilter< TInputImage >::SetInput ( unsigned int  i,
const TInputImage *  image 
) [inline, virtual]

Set/Get the input thresholding parameter. Units are a percentage of the maximum depth in the image.

Reimplemented from itk::ImageToImageFilter< TInputImage, Image< IdentifierType,::itk::GetImageDimension< TInputImage >::ImageDimension > >.

Definition at line 209 of file itkWatershedImageFilter.h.

References itkExceptionMacro.

template<class TInputImage >
void itk::WatershedImageFilter< TInputImage >::SetInput ( const InputImageType input) [inline, virtual]

Set/Get the input thresholding parameter. Units are a percentage of the maximum depth in the image.

Reimplemented from itk::ImageToImageFilter< TInputImage, Image< IdentifierType,::itk::GetImageDimension< TInputImage >::ImageDimension > >.

Definition at line 194 of file itkWatershedImageFilter.h.

References itk::ProcessObject::SetNthInput().

template<class TInputImage >
void itk::WatershedImageFilter< TInputImage >::SetLevel ( double  )

Set/Get the flood level for generating the merge tree from the initial segmentation

template<class TInputImage >
void itk::WatershedImageFilter< TInputImage >::SetThreshold ( double  )

Set/Get the input thresholding parameter. Units are a percentage of the maximum depth in the image.

template<class TInputImage >
itk::WatershedImageFilter< TInputImage >::typedef ( Concept::AdditiveOperators< ScalarType )

This class requires InputAdditiveOperatorsCheck in the form of ( Concept::AdditiveOperators< ScalarType > )

template<class TInputImage >
itk::WatershedImageFilter< TInputImage >::typedef ( Concept::MultiplyOperator< double, ScalarType, ScalarType )

This class requires DoubleInputMultiplyOperatorCheck in the form of ( Concept::MultiplyOperator< double, ScalarType, ScalarType > )

template<class TInputImage >
itk::WatershedImageFilter< TInputImage >::typedef ( Concept::EqualityComparable< ScalarType )

Begin concept checking This class requires InputEqualityComparableCheck in the form of ( Concept::EqualityComparable< ScalarType > )

template<class TInputImage >
itk::WatershedImageFilter< TInputImage >::typedef ( Concept::LessThanComparable< ScalarType )

This class requires InputLessThanComparableCheck in the form of ( Concept::LessThanComparable< ScalarType > )


Member Data Documentation

template<class TInputImage >
const unsigned int itk::WatershedImageFilter< TInputImage >::ImageDimension = TInputImage::ImageDimension [static]

Dimension of the input and output images.

Definition at line 163 of file itkWatershedImageFilter.h.

template<class TInputImage >
TimeStamp itk::WatershedImageFilter< TInputImage >::m_GenerateDataMTime [private]

Definition at line 302 of file itkWatershedImageFilter.h.

template<class TInputImage >
bool itk::WatershedImageFilter< TInputImage >::m_InputChanged [private]

Definition at line 300 of file itkWatershedImageFilter.h.

template<class TInputImage >
double itk::WatershedImageFilter< TInputImage >::m_Level [private]

The percentage of the maximum saliency value among adjacencies in the segments of the initial segmentation to which ``flooding'' of the image should occur. A tree of segment merges is calculated up to this level.

Definition at line 284 of file itkWatershedImageFilter.h.

template<class TInputImage >
bool itk::WatershedImageFilter< TInputImage >::m_LevelChanged [private]

Definition at line 298 of file itkWatershedImageFilter.h.

template<class TInputImage >
unsigned long itk::WatershedImageFilter< TInputImage >::m_ObserverTag [private]

Definition at line 296 of file itkWatershedImageFilter.h.

template<class TInputImage >
watershed::Relabeler< ScalarType, itkGetStaticConstMacro(ImageDimension) >::Pointer itk::WatershedImageFilter< TInputImage >::m_Relabeler [private]

Definition at line 294 of file itkWatershedImageFilter.h.

template<class TInputImage >
watershed::Segmenter< InputImageType >::Pointer itk::WatershedImageFilter< TInputImage >::m_Segmenter [private]

The component parts of the segmentation algorithm. These objects must save state between calls to GenerateData() so that the computationally expensive execution of segment tree generation is not unneccessarily repeated.

Definition at line 290 of file itkWatershedImageFilter.h.

template<class TInputImage >
double itk::WatershedImageFilter< TInputImage >::m_Threshold [private]

A Percentage of the maximum depth (max - min pixel value) in the input image. This percentage will be used to threshold the minimum values in the image.

Definition at line 278 of file itkWatershedImageFilter.h.

template<class TInputImage >
bool itk::WatershedImageFilter< TInputImage >::m_ThresholdChanged [private]

Definition at line 299 of file itkWatershedImageFilter.h.

template<class TInputImage >
watershed::SegmentTreeGenerator< ScalarType >::Pointer itk::WatershedImageFilter< TInputImage >::m_TreeGenerator [private]

Definition at line 292 of file itkWatershedImageFilter.h.


The documentation for this class was generated from the following file: