| 1 |
|
/*========================================================================= |
| 2 |
|
|
| 3 |
|
Program: Insight Segmentation & Registration Toolkit |
| 4 |
|
Module: $RCSfile: itkImageSource.h.html,v $ |
| 5 |
|
Language: C++ |
| 6 |
|
Date: $Date: 2006/01/17 19:15:40 $ |
| 7 |
|
Version: $Revision: 1.4 $ |
| 8 |
|
|
| 9 |
|
Copyright (c) Insight Software Consortium. All rights reserved. |
| 10 |
|
See ITKCopyright.txt or http://www.itk.org/HTML/Copyright.htm for details. |
| 11 |
|
|
| 12 |
|
Portions of this code are covered under the VTK copyright. |
| 13 |
|
See VTKCopyright.txt or http://www.kitware.com/VTKCopyright.htm for details. |
| 14 |
|
|
| 15 |
|
This software is distributed WITHOUT ANY WARRANTY; without even |
| 16 |
|
the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR |
| 17 |
IND |
*****PURPOSE. See the above copyright notices for more information. |
| 18 |
|
|
| 19 |
|
=========================================================================*/ |
| 20 |
|
#ifndef __itkImageSource_h |
| 21 |
|
#define __itkImageSource_h |
| 22 |
|
|
| 23 |
|
#include "itkProcessObject.h" |
| 24 |
|
#include "itkImage.h" |
| 25 |
|
|
| 26 |
|
namespace itk |
| 27 |
|
{ |
| 28 |
|
|
| 29 |
|
/** \class ImageSource |
| 30 |
|
* \brief Base class for all process objects that output image data. |
| 31 |
|
* |
| 32 |
|
* ImageSource is the base class for all process objects that output |
| 33 |
|
* image data. Specifically, this class defines the GetOutput() method |
| 34 |
|
* that returns a pointer to the output image. The class also defines |
| 35 |
|
* some internal private data members that are used to manage streaming |
| 36 |
|
* of data. |
| 37 |
|
* |
| 38 |
|
* Memory management in an ImageSource is slightly different than a |
| 39 |
|
* standard ProcessObject. ProcessObject's always release the bulk |
| 40 |
|
* data associated with their output prior to GenerateData() being |
| 41 |
|
* called. ImageSources default to not releasing the bulk data incase |
| 42 |
|
* that particular memory block is large enough to hold the new output |
| 43 |
|
* values. This avoids unnecessary deallocation/allocation |
| 44 |
|
* sequences. ImageSource's can be forced to use a memory management |
| 45 |
|
* model similar to the default ProcessObject behaviour by calling |
| 46 |
|
* ProcessObject::ReleaseDataBeforeUpdateFlagOn(). A user may want to |
| 47 |
|
* set this flag to limit peak memory usage during a pipeline update. |
| 48 |
|
* |
| 49 |
|
* \ingroup DataSources |
| 50 |
|
*/ |
| 51 |
|
template <class TOutputImage> |
| 52 |
|
class ITK_EXPORT ImageSource : public ProcessObject |
| 53 |
|
{ |
| 54 |
|
public: |
| 55 |
|
/** Standard class typedefs. */ |
| 56 |
|
typedef ImageSource Self; |
| 57 |
TDA |
typedef ProcessObject Superclass; |
| 58 |
|
typedef SmartPointer<Self> Pointer; |
| 59 |
TDA |
typedef SmartPointer<const Self> ConstPointer; |
| 60 |
|
|
| 61 |
|
/** Smart Pointer type to a DataObject. */ |
| 62 |
|
typedef DataObject::Pointer DataObjectPointer; |
| 63 |
|
|
| 64 |
|
/** Run-time type information (and related methods). */ |
| 65 |
|
itkTypeMacro(ImageSource,ProcessObject); |
| 66 |
|
|
| 67 |
|
/** Some convenient typedefs. */ |
| 68 |
|
typedef TOutputImage OutputImageType; |
| 69 |
TDA |
typedef typename OutputImageType::Pointer OutputImagePointer; |
| 70 |
TDA |
typedef typename OutputImageType::RegionType OutputImageRegionType; |
| 71 |
TDA |
typedef typename OutputImageType::PixelType OutputImagePixelType; |
| 72 |
|
|
| 73 |
|
/** Get the output data of this process object. The output of this |
| 74 |
|
* function is not valid until an appropriate Update() method has |
| 75 |
|
* been called, either explicitly or implicitly. Both the filter |
| 76 |
|
* itself and the data object have Update() methods, and both |
| 77 |
|
* methods update the data. Here are three ways to use |
| 78 |
|
* GetOutput() and make sure the data is valid. In these |
| 79 |
|
* examples, \a image is a pointer to some Image object, and the |
| 80 |
|
* particular ProcessObjects involved are filters. The same |
| 81 |
|
* examples apply to non-image (e.g. Mesh) data as well. |
| 82 |
|
* |
| 83 |
|
* \code |
| 84 |
|
* anotherFilter->SetInput( someFilter->GetOutput() ); |
| 85 |
|
* anotherFilter->Update(); |
| 86 |
|
* \endcode |
| 87 |
|
* |
| 88 |
|
* In this situation, \a someFilter and \a anotherFilter are said |
| 89 |
|
* to constitute a \b pipeline. |
| 90 |
|
* |
| 91 |
|
* \code |
| 92 |
|
* image = someFilter->GetOutput(); |
| 93 |
|
* image->Update(); |
| 94 |
|
* \endcode |
| 95 |
|
* |
| 96 |
|
* \code |
| 97 |
|
* someFilter->Update(); |
| 98 |
|
* image = someFilter->GetOutput(); |
| 99 |
|
* \endcode |
| 100 |
|
* (In the above example, the two lines of code can be in |
| 101 |
|
* either order.) |
| 102 |
|
* |
| 103 |
|
* Note that Update() is not called automatically except within a |
| 104 |
|
* pipeline as in the first example. When \b streaming (using a |
| 105 |
|
* StreamingImageFilter) is activated, it may be more efficient to |
| 106 |
|
* use a pipeline than to call Update() once for each filter in |
| 107 |
|
* turn. |
| 108 |
|
* |
| 109 |
|
* For an image, the data generated is for the requested |
| 110 |
|
* Region, which can be set using ImageBase::SetRequestedRegion(). |
| 111 |
|
* By default, the largest possible region is requested. |
| 112 |
|
*/ |
| 113 |
|
OutputImageType * GetOutput(void); |
| 114 |
|
OutputImageType * GetOutput(unsigned int idx); |
| 115 |
|
|
| 116 |
|
/** Graft the specified DataObject onto this ProcessObject's output. |
| 117 |
|
* This method grabs a handle to the specified DataObject's bulk |
| 118 |
|
* data to used as its output's own bulk data. It also copies the |
| 119 |
|
* region ivars (RequestedRegion, BufferedRegion, |
| 120 |
|
* LargestPossibleRegion) and meta-data (Spacing, Origin) from the |
| 121 |
|
* specified data object into this filter's output data object. Most |
| 122 |
|
* importantly, however, it leaves the Source ivar untouched so the |
| 123 |
|
* original pipeline routing is intact. This method is used when a |
| 124 |
|
* process object is implemented using a mini-pipeline which is |
| 125 |
|
* defined in its GenerateData() method. The usage is: |
| 126 |
|
* |
| 127 |
|
* \code |
| 128 |
|
* // setup the mini-pipeline to process the input to this filter |
| 129 |
|
* firstFilterInMiniPipeline->SetInput( this->GetInput() ); |
| 130 |
|
|
| 131 |
|
* // setup the mini-pipeline to calculate the correct regions |
| 132 |
|
* // and write to the appropriate bulk data block |
| 133 |
|
* lastFilterInMiniPipeline->GraftOutput( this->GetOutput() ); |
| 134 |
|
* |
| 135 |
|
* // execute the mini-pipeline |
| 136 |
|
* lastFilterInMiniPipeline->Update(); |
| 137 |
|
* |
| 138 |
|
* // graft the mini-pipeline output back onto this filter's output. |
| 139 |
|
* // this is needed to get the appropriate regions passed back. |
| 140 |
|
* this->GraftOutput( lastFilterInMiniPipeline->GetOutput() ); |
| 141 |
|
* \endcode |
| 142 |
|
* |
| 143 |
|
* For proper pipeline execution, a filter using a mini-pipeline |
| 144 |
|
* must implement the GenerateInputRequestedRegion(), |
| 145 |
|
* GenerateOutputRequestedRegion(), GenerateOutputInformation() and |
| 146 |
|
* EnlargeOutputRequestedRegion() methods as necessary to reflect |
| 147 |
|
* how the mini-pipeline will execute (in other words, the outer |
| 148 |
|
* filter's pipeline mechanism must be consistent with what the |
| 149 |
|
* mini-pipeline will do). |
| 150 |
|
* */ |
| 151 |
|
virtual void GraftOutput(DataObject *output); |
| 152 |
|
|
| 153 |
|
/** Graft the specified data object onto this ProcessObject's idx'th |
| 154 |
|
* output. This is the similar to GraftOutput method except is |
| 155 |
|
* allows you specify which output is affected. The specified index |
| 156 |
|
* must be a valid output number (less than |
| 157 |
|
* ProcessObject::GetNumberOfOutputs()). See the GraftOutput for |
| 158 |
|
* general usage information. */ |
| 159 |
|
virtual void GraftNthOutput(unsigned int idx, DataObject *output); |
| 160 |
|
|
| 161 |
|
/** Make a DataObject of the correct type to used as the specified |
| 162 |
|
* output. Every ProcessObject subclass must be able to create a |
| 163 |
|
* DataObject that can be used as a specified output. This method |
| 164 |
|
* is automatically called when DataObject::DisconnectPipeline() is |
| 165 |
|
* called. DataObject::DisconnectPipeline, disconnects a data object |
| 166 |
|
* from being an output of its current source. When the data object |
| 167 |
|
* is disconnected, the ProcessObject needs to construct a replacement |
| 168 |
|
* output data object so that the ProcessObject is in a valid state. |
| 169 |
|
* So DataObject::DisconnectPipeline eventually calls |
| 170 |
|
* ProcessObject::MakeOutput. Note that MakeOutput always returns a |
| 171 |
|
* SmartPointer to a DataObject. If a subclass of ImageSource has |
| 172 |
|
* multiple outputs of different types, then that class must provide |
| 173 |
|
* an implementation of MakeOutput(). */ |
| 174 |
|
virtual DataObjectPointer MakeOutput(unsigned int idx); |
| 175 |
|
|
| 176 |
|
protected: |
| 177 |
|
ImageSource(); |
| 178 |
|
virtual ~ImageSource() {} |
| 179 |
|
|
| 180 |
|
/** A version of GenerateData() specific for image processing |
| 181 |
|
* filters. This implementation will split the processing across |
| 182 |
|
* multiple threads. The buffer is allocated by this method. Then |
| 183 |
|
* the BeforeThreadedGenerateData() method is called (if |
| 184 |
|
* provided). Then, a series of threads are spawned each calling |
| 185 |
|
* ThreadedGenerateData(). After all the threads have completed |
| 186 |
|
* processing, the AfterThreadedGenerateData() method is called (if |
| 187 |
|
* provided). If an image processing filter cannot be threaded, the |
| 188 |
|
* filter should provide an implementation of GenerateData(). That |
| 189 |
|
* implementation is responsible for allocating the output buffer. |
| 190 |
|
* If a filter an be threaded, it should NOT provide a |
| 191 |
|
* GenerateData() method but should provide a ThreadedGenerateData() |
| 192 |
|
* instead. |
| 193 |
|
* |
| 194 |
|
* \sa ThreadedGenerateData() */ |
| 195 |
|
virtual void GenerateData(); |
| 196 |
|
|
| 197 |
|
/** If an imaging filter can be implemented as a multithreaded |
| 198 |
|
* algorithm, the filter will provide an implementation of |
| 199 |
|
* ThreadedGenerateData(). This superclass will automatically split |
| 200 |
|
* the output image into a number of pieces, spawn multiple threads, |
| 201 |
|
* and call ThreadedGenerateData() in each thread. Prior to spawning |
| 202 |
|
* threads, the BeforeThreadedGenerateData() method is called. After |
| 203 |
|
* all the threads have completed, the AfterThreadedGenerateData() |
| 204 |
|
* method is called. If an image processing filter cannot support |
| 205 |
|
* threading, that filter should provide an implementation of the |
| 206 |
|
* GenerateData() method instead of providing an implementation of |
| 207 |
|
* ThreadedGenerateData(). If a filter provides a GenerateData() |
| 208 |
|
* method as its implementation, then the filter is responsible for |
| 209 |
|
* allocating the output data. If a filter provides a |
| 210 |
|
* ThreadedGenerateData() method as its implementation, then the |
| 211 |
|
* output memory will allocated automatically by this superclass. |
| 212 |
|
* The ThreadedGenerateData() method should only produce the output |
| 213 |
|
* specified by "outputThreadRegion" |
| 214 |
|
* parameter. ThreadedGenerateData() cannot write to any other |
| 215 |
|
* portion of the output image (as this is responsibility of a |
| 216 |
|
* different thread). |
| 217 |
|
* |
| 218 |
|
* \sa GenerateData(), SplitRequestedRegion() */ |
| 219 |
|
virtual |
| 220 |
|
void ThreadedGenerateData(const OutputImageRegionType& outputRegionForThread, |
| 221 |
|
int threadId ); |
| 222 |
|
|
| 223 |
|
|
| 224 |
|
/** The GenerateData method normally allocates the buffers for all of the |
| 225 |
|
* outputs of a filter. Some filters may want to override this default |
| 226 |
|
* behavior. For example, a filter may have multiple outputs with |
| 227 |
|
* varying resolution. Or a filter may want to process data in place by |
| 228 |
|
* grafting its input to its output.*/ |
| 229 |
|
virtual void AllocateOutputs(); |
| 230 |
|
|
| 231 |
|
/** If an imaging filter needs to perform processing after the buffer |
| 232 |
|
* has been allocated but before threads are spawned, the filter can |
| 233 |
|
* can provide an implementation for BeforeThreadedGenerateData(). The |
| 234 |
|
* execution flow in the default GenerateData() method will be: |
| 235 |
|
* 1) Allocate the output buffer |
| 236 |
|
* 2) Call BeforeThreadedGenerateData() |
| 237 |
|
* 3) Spawn threads, calling ThreadedGenerateData() in each thread. |
| 238 |
|
* 4) Call AfterThreadedGenerateData() |
| 239 |
|
* Note that this flow of control is only available if a filter provides |
| 240 |
|
* a ThreadedGenerateData() method and NOT a GenerateData() method. */ |
| 241 |
|
virtual void BeforeThreadedGenerateData() {}; |
| 242 |
|
|
| 243 |
|
/** If an imaging filter needs to perform processing after all |
| 244 |
WCM |
* processing threads have completed, the filter can can provide an |
| 245 |
|
* implementation for AfterThreadedGenerateData(). The execution |
| 246 |
|
* flow in the default GenerateData() method will be: |
| 247 |
|
* 1) Allocate the output buffer |
| 248 |
|
* 2) Call BeforeThreadedGenerateData() |
| 249 |
|
* 3) Spawn threads, calling ThreadedGenerateData() in each thread. |
| 250 |
|
* 4) Call AfterThreadedGenerateData() |
| 251 |
|
* Note that this flow of control is only available if a filter provides |
| 252 |
|
* a ThreadedGenerateData() method and NOT a GenerateData() method. */ |
| 253 |
|
virtual void AfterThreadedGenerateData() {}; |
| 254 |
|
|
| 255 |
|
/** Split the output's RequestedRegion into "num" pieces, returning |
| 256 |
|
* region "i" as "splitRegion". This method is called "num" times. The |
| 257 |
|
* regions must not overlap. The method returns the number of pieces that |
| 258 |
|
* the routine is capable of splitting the output RequestedRegion, |
| 259 |
|
* i.e. return value is less than or equal to "num". */ |
| 260 |
|
virtual |
| 261 |
|
int SplitRequestedRegion(int i, int num, OutputImageRegionType& splitRegion); |
| 262 |
|
|
| 263 |
|
/** Static function used as a "callback" by the MultiThreader. The threading |
| 264 |
|
* library will call this routine for each thread, which will delegate the |
| 265 |
|
* control to ThreadedGenerateData(). */ |
| 266 |
|
static ITK_THREAD_RETURN_TYPE ThreaderCallback( void *arg ); |
| 267 |
|
|
| 268 |
LEN |
/** Internal structure used for passing image data into the threading library */ |
| 269 |
|
struct ThreadStruct |
| 270 |
IND |
**{ |
| 271 |
IND |
***Pointer Filter; |
| 272 |
IND |
**}; |
| 273 |
|
|
| 274 |
|
private: |
| 275 |
|
ImageSource(const Self&); //purposely not implemented |
| 276 |
|
void operator=(const Self&); //purposely not implemented |
| 277 |
|
|
| 278 |
|
}; |
| 279 |
|
#ifdef ITK_EXPLICIT_INSTANTIATION |
| 280 |
IND |
***extern template class ImageSource<Image<float ,2> >; |
| 281 |
IND |
***extern template class ImageSource<Image<double ,2> >; |
| 282 |
IND |
***extern template class ImageSource<Image<unsigned char ,2> >; |
| 283 |
IND |
***extern template class ImageSource<Image<unsigned short,2> >; |
| 284 |
IND |
***extern template class ImageSource<Image<unsigned int ,2> >; |
| 285 |
IND |
***extern template class ImageSource<Image<signed char ,2> >; |
| 286 |
IND |
***extern template class ImageSource<Image<signed short ,2> >; |
| 287 |
IND |
***extern template class ImageSource<Image<signed int ,2> >; |
| 288 |
IND |
***extern template class ImageSource<Image<float ,3> >; |
| 289 |
IND |
***extern template class ImageSource<Image<double ,3> >; |
| 290 |
IND |
***extern template class ImageSource<Image<unsigned char ,3> >; |
| 291 |
IND |
***extern template class ImageSource<Image<unsigned short,3> >; |
| 292 |
IND |
***extern template class ImageSource<Image<unsigned int ,3> >; |
| 293 |
IND |
***extern template class ImageSource<Image<signed char ,3> >; |
| 294 |
IND |
***extern template class ImageSource<Image<signed short ,3> >; |
| 295 |
IND |
***extern template class ImageSource<Image<signed int ,3> >; |
| 296 |
|
#endif |
| 297 |
|
|
| 298 |
|
} // end namespace itk |
| 299 |
|
|
| 300 |
|
#ifndef ITK_MANUAL_INSTANTIATION |
| 301 |
|
#include "itkImageSource.txx" |
| 302 |
|
#endif |
| 303 |
|
|
| 304 |
|
#endif |
| 305 |
|
|
| 306 |
EOF |
|
