ITK: itk::DataObject Class Reference

This is the base class for all data objects in the Insight data processing pipeline. A data object is an object that represents and provides access to data. ProcessObjects (i.e., filters) operate on input data objects, producing new data objects as output. ProcessObject and DataObject are connected together into data flow pipelines.

The data flow pipeline architecture requires that DataObjects and ProcessObjects negotiate the flow of information. When the tail of a pipeline is instructed to Update(), a series of requests are propagated up the pipeline (from a ProcessObject to its inputs (DataObjects), from these inputs to their sources (ProcessObjects), etc.). A call to Update() entails 3 passes up the pipeline (though not all passes will traverse the entire pipeline). The first pass up the pipeline determines when various components of the pipeline were last modified and hence which components will need to be updated. As this first pass in unwinding, meta information about the DataObjects (for instance image spacing and data size) are passed down the pipeline. The second pass up the pipeline propagates a request for a specific piece of information (for instance a sub-region of an image). A request for a piece of a DataObject is propagated to its source, from there to its inputs, etc. allowing each ProcessObject to determine whether (1) it can already satisfy the request (the requested block of data is already available) or (2) the ProcessObject will need to request a new block of data on input to satisfy the output request. Finally, a pass is made up the pipeline to actually calculate the values for the various blocks of data requested (i.e. pixel values are finally calculated). This final pass will only traverse up the pipeline as far as the first two passes have identified. For instance, to satisfy a given request at the tail of a pipeline, only the lower few ProcessObjects may have to re-execute.

There are three types of information negotiated by the pipeline (prior to actual calculation of the bulk data): modified times, meta data, and regions. The modified times keep track of when various data objects were last modified and/updated and the when the various process objects were modified. The meta data is any extra information about the data object that is not part of the bulk data. For instance, an Image maintains pixel spacing and origin meta data. Finally, the pipeline negotiation process passes requests up the pipeline in the form of Regions. A DataObject can have as many as three regions (which themselves could be considered meta data): LargestPossibleRegion, RequestedRegion, and BufferedRegion. The LargestPossibleRegion is the entirety of the dataset (for instance how big is the dataset on disk). LargestPossibleRegions are negotiated during the first pass of a pipeline update (via the method ProcessObject::GenerateOutputInformation() which is called from ProcessObject::UpdateOutputInformation(). The RequestedRegion is the amount of the DataObject that is requested by the user or pipeline. RequestedRegions are negotiated during the second pass of a pipeline update (via the methods ProcessObject::EnlargeOutputRequestedRegion(), ProcessObject::GenerateOutputRequestedRegion(), ProcessObject::GenerateInputRequestedRegion() which are called from ProcessObject::PropagateRequestedRegion()). The BufferedRegion is the amount of the DataObject that is currently in memory. BufferedRegions are defined during the final pass of a pipeline update (when ProcessObjects finally calculate the bulk data via the methods ProcessObject::GenerateData() or ProcessObject::ThreadedGenerateData() which are called by ProcessObject::UpdateOutputData()). These three regions can be different but must satisfy the relationship RequestedRegion <= BufferedRegion <= LargestPossibleRegion. For instance, an Image could be 512x512x200 on disk (LargestPossibleRegion) but the application may only have a 256x256x50 section of the dataset in memory (BufferedRegion) and the user wants to operate on a 100x100x1 section of the buffer (RequestedRegion).

Region negotiation is not applicable for all types of DataObjects. For instance, an EquivalencyTable of segmentation labels can be passed from ProcessObject to ProcessObject as any other DataObject but an EquivalencyTable does not support the concept of a sub-region. Therefore, the region negotiations at the DataObject (superclass) level are implemented as "abstract" concepts (not to be confused with a C++ abstract methods), allowing subclasses to provide specialized implementations on an as needed basis. There are five methods provided in DataObject that a subclass of DataObject may have to override for that particular type of DataObject to flow through the pipeline. These methods should only have to be specialized for DataObjects that do support regions. These methods are:

void UpdateOutputInformation(): This method implements the first pass of the pipeline update mechanism outlined above. It is responsible for identifying when upstream components of the pipeline have been change (ModifiedTimes and Pipeline ModifiedTimes) and is responsible for propagating meta data through the pipeline. In the simplest case, this method simply calls the DataObject's source's UpdateOutputInformation() method (this is the default implementation). For DataObjects that support streaming, this method also propagates LargestPossibleRegions to downstream ProcessObjects.

bool VerifyRequestedRegion(): Verify that the RequestedRegion is within the LargestPossibleRegion. For DataObjects that do not support Regions, this method always returns true.

bool RequestedRegionIsOutsideOfTheBufferedRegion(): Determine whether the RequestedRegion is outside of the current BufferedRegion. This method is used by the second pass of a pipeline update outlined above. It is used to determine whether a filter needs to re-execute in order to satisfy a given request. For DataObjects that do not support Regions, this method always returns false. By always returning false, these types of DataObjects will update solely on the basis of modified times (wherease Images update based on either modified times or the RequestedRegion needs). If this method always returned true, the DataObject would be updated on every single call to Update() (not recommended).

void SetRequestedRegion(DataObject *): Sets the RequestedRegion of this DataObject to match the RequestedRegion of the DataObject that is passed in as a parameter. This method is used by ProcessObject::GenerateOutputRequestedRegion() and by ProcessObject::SetNthOutput(). In the former case, it used as an abstract API so that a ProcessObject can copy a requested region from one output to all its outputs without knowing the particular subclass of DataObject. In the latter case, it used when a ProcessObject has to create an output object to replace one of its outputs (and needs to copy the former object's RequestedRegion). In either case, it allows ProcessObject to perform these actions without knowing the specifics about the particular subclass of DataObject. For DataObjects that do not support Regions, this method does nothing.

void SetRequestedRegionToLargestPossibleRegion(): Sets the RequestedRegion of this DataObject to match its LargestPossibleRegion. This method is used to force a filter to produce all of its output on the next call to Update(). For DataObjects that do not support Regions, this method does nothing.

Member Typedef Documentation

typedef SmartPointer<const Self> itk::DataObject::ConstPointer

Reimplemented from itk::Object.

Definition at line 269 of file itkDataObject.h.

typedef SmartPointer<Self> itk::DataObject::Pointer

Reimplemented from itk::Object.

Definition at line 268 of file itkDataObject.h.

typedef DataObject itk::DataObject::Self

Standard class typedefs.

Reimplemented from itk::Object.

Definition at line 266 of file itkDataObject.h.

typedef Object itk::DataObject::Superclass

Reimplemented from itk::Object.

Definition at line 267 of file itkDataObject.h.

Constructor & Destructor Documentation

itk::DataObject::DataObject ( ) [protected]

itk::DataObject::~DataObject ( ) [protected]

Member Function Documentation

unsigned long itk::Object::AddObserver	(	const EventObject &	event,
		Command *
	)			const `[inherited]`

unsigned long itk::Object::AddObserver	(	const EventObject &	event,
		Command *
	)			`[inherited]`

Allow people to add/remove/invoke observers (callbacks) to any ITK object. This is an implementation of the subject/observer design pattern. An observer is added by specifying an event to respond to and an itk::Command to execute. It returns an unsigned long tag which can be used later to remove the event or retrieve the command. The memory for the


void	GlobalReleaseDataFlagOff ()
void	GlobalReleaseDataFlagOn ()
static bool	GetGlobalReleaseDataFlag ()
static void	SetGlobalReleaseDataFlag (const bool val)
Public Types
typedef SmartPointer< const Self >	ConstPointer
typedef SmartPointer< Self >	Pointer
typedef DataObject	Self
typedef Object	Superclass
Public Member Functions
virtual void	CopyInformation (const DataObject *)
virtual LightObject::Pointer	CreateAnother () const
void	DataHasBeenGenerated ()
virtual void	DebugOff () const
virtual void	DebugOn () const
virtual void	Delete ()
void	DisconnectPipeline ()
Command *	GetCommand (unsigned long tag)
bool	GetDataReleased () const
bool	GetDebug () const
const MetaDataDictionary &	GetMetaDataDictionary (void) const
MetaDataDictionary &	GetMetaDataDictionary (void)
virtual unsigned long	GetMTime () const
virtual const char *	GetNameOfClass () const
virtual int	GetReferenceCount () const
SmartPointerForwardReference< ProcessObject >	GetSource () const
unsigned int	GetSourceOutputIndex () const
virtual unsigned long	GetUpdateMTime () const
virtual void	Graft (const DataObject *)
bool	HasObserver (const EventObject &event) const
virtual void	Initialize ()
void	InvokeEvent (const EventObject &) const
void	InvokeEvent (const EventObject &)
virtual void	Modified () const
virtual void	PrepareForNewData ()
void	Print (std::ostream &os, Indent indent=0) const
virtual void	Register () const
void	ReleaseData ()
void	RemoveAllObservers ()
void	RemoveObserver (unsigned long tag)
virtual bool	RequestedRegionIsOutsideOfTheBufferedRegion ()
virtual void	ResetPipeline ()
void	SetDebug (bool debugFlag) const
void	SetMetaDataDictionary (const MetaDataDictionary &rhs)
virtual void	SetReferenceCount (int)
virtual void	SetRequestedRegion (DataObject *)
virtual void	SetRequestedRegionToLargestPossibleRegion ()
bool	ShouldIReleaseData () const
virtual void	UnRegister () const
virtual void	Update ()
virtual void	UpdateOutputInformation ()
virtual bool	VerifyRequestedRegion ()

unsigned long	AddObserver (const EventObject &event, Command *) const
unsigned long	AddObserver (const EventObject &event, Command *)

virtual const unsigned long &	GetPipelineMTime ()
void	SetPipelineMTime (unsigned long time)

virtual const bool &	GetReleaseDataFlag ()
virtual void	ReleaseDataFlagOff ()
virtual void	ReleaseDataFlagOn ()
void	SetReleaseDataFlag (bool flag)

virtual void	PropagateRequestedRegion () throw (InvalidRequestedRegionError)
virtual void	UpdateOutputData ()
Static Public Member Functions
static void	BreakOnError ()
static Pointer	New ()

static bool	GetGlobalWarningDisplay ()
static void	GlobalWarningDisplayOff ()
static void	GlobalWarningDisplayOn ()
static void	SetGlobalWarningDisplay (bool flag)
Protected Member Functions
	DataObject ()
bool	PrintObservers (std::ostream &os, Indent indent) const
void	PrintSelf (std::ostream &os, Indent indent) const
virtual void	PropagateResetPipeline ()
	~DataObject ()

virtual void	PrintHeader (std::ostream &os, Indent indent) const
virtual void	PrintTrailer (std::ostream &os, Indent indent) const
Protected Attributes
volatile int	m_ReferenceCount
SimpleFastMutexLock	m_ReferenceCountLock
Friends
class	DataObjectError
class	ProcessObject

itk::DataObject Class Reference
[Data Representation Objects, ITK System Objects]

Detailed Description

Public Types

Public Member Functions

Static Public Member Functions

Protected Member Functions

Protected Attributes

Friends

Member Typedef Documentation

Constructor & Destructor Documentation

Member Function Documentation

itk::DataObject Class Reference [Data Representation Objects, ITK System Objects]

Detailed Description

Public Types

Public Member Functions

Static Public Member Functions

Protected Member Functions

Protected Attributes

Friends

Member Typedef Documentation

Constructor & Destructor Documentation

Member Function Documentation

itk::DataObject Class Reference
[Data Representation Objects, ITK System Objects]