1 /*========================================================================= 2 * 3 * Copyright Insight Software Consortium 4 * 5 * Licensed under the Apache License, Version 2.0 (the "License"); 6 * you may not use this file except in compliance with the License. 7 * You may obtain a copy of the License at 8 * 9 * http://www.apache.org/licenses/LICENSE-2.0.txt 10 * 11 * Unless required by applicable law or agreed to in writing, software 12 * distributed under the License is distributed on an "AS IS" BASIS, 13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 14 * See the License for the specific language governing permissions and 15 * limitations under the License. 16 * 17 *=========================================================================*/ 18 /*========================================================================= 19 * 20 * Portions of this file are subject to the VTK Toolkit Version 3 copyright. 21 * 22 * Copyright (c) Ken Martin, Will Schroeder, Bill Lorensen 23 * 24 * For complete copyright, license and disclaimer of warranty information 25 * please refer to the NOTICE file at the top of the ITK source tree. 26 * 27 *=========================================================================*/ 28 #ifndef itkImageToImageFilter_h 29 #define itkImageToImageFilter_h 30 31 #include "itkImageSource.h" 32 #include "itkConceptChecking.h" 33 #include "itkImageToImageFilterDetail.h" 34 #include "itkImageToImageFilterCommon.h" 35 36 namespace itk 37 { 38 39 /** \class ImageToImageFilter 40 * \brief Base class for filters that take an image as input and produce an image as output. 41 * 42 * ImageToImageFilter is the base class for all process objects that output 43 * image data and require image data as input. Specifically, this class 44 * defines the SetInput() method for defining the input to a filter. 45 * 46 * This class provides the infrastructure for supporting multithreaded 47 * processing of images. If a filter provides an implementation of 48 * GenerateData(), the image processing will run in a single thread and the 49 * implementation is responsible for allocating its output data. If a filter 50 * provides an implementation of ThreadedGenerateData() instead, the image 51 * will be divided into a number of work units, a number of threads will be 52 * spawned, and ThreadedGenerateData() will be called in each thread. Here, 53 * the output memory will be allocated by this superclass prior to calling 54 * ThreadedGenerateData(). 55 * 56 * ImageToImageFilter provides an implementation of 57 * GenerateInputRequestedRegion(). The base assumption to this point in the 58 * hierarchy is that a process object would ask for the largest possible 59 * region on input in order to produce any output. Imaging filters, 60 * however, can usually answer this question more precisely. The default 61 * implementation of GenerateInputRequestedRegion() in this class is to 62 * request an input that matches the size of the requested output. If a 63 * filter requires more input (say a filter that uses neighborhood 64 * information) or less input (for instance a magnify filter), then these 65 * filters will have to provide another implmentation of this method. By 66 * convention, such implementations should call the Superclass' method 67 * first. 68 * 69 * All inputs to ImageToImageFilter (if there is more than one) are 70 * checked in the VerifyInputInformation method to verify that they 71 * occupy the same physical space. If the input images are in the 72 * same physical space, then the location of each voxel is identical, 73 * and the filter can operate voxel-by-voxel in index space. Some 74 * filters -- registration filters, for example -- will violate this 75 * precondition, in which case they should redefine 76 * VerifyInputInformation to relax or eliminate this requirement. 77 * 78 * Access methods -- Set/GetCoordinateTolerance and 79 * Set/GetDirectionTolerance -- are provided for cases where the 80 * default spatial-congruency tolerances are too fine, and images that 81 * are almost in the same space should be regard as being in the same 82 * space. This has come up, for example when comparing different 83 * on-disk image formats with differing digits of precision in the 84 * position, spacing, and orientation. 85 * 86 * The default tolerance is govern by the 87 * GlobalDefaultCoordinateTolerance and the 88 * GlobalDefaultDirectionTolerance properties, defaulting to 1.0e-6. 89 * The default tolerance for spatial comparison is then scaled by the 90 * voxelSpacing for coordinates (i.e. the coordinates must be the same 91 * to within one part per million). For the direction cosines the 92 * values must be within the current absolute tolerance. 93 * 94 * \ingroup ImageFilters 95 * \ingroup ITKCommon 96 * 97 * \wiki 98 * \wikiexample{Developer/ImageFilter,Filter an image} 99 * \wikiexample{Developer/ImageFilterMultipleInputs,Write a filter with multiple inputs of the same type.} 100 * \wikiexample{Developer/ImageFilterMultipleInputsDifferentType,Write a filter with multiple inputs of different types.} 101 * \wikiexample{Developer/ImageFilterMultipleOutputs,Write a filter with multiple outputs of the same type.} 102 * \wikiexample{Developer/OilPaintingImageFilter,Multi-threaded oil painting image filter} 103 * \wikiexample{Developer/ImageFilterMultipleOutputsDifferentType,Write a filter with multiple outputs of different types.} 104 * \endwiki 105 */ 106 template< typename TInputImage, typename TOutputImage > 107 class ITK_TEMPLATE_EXPORT ImageToImageFilter:public ImageSource< TOutputImage >, 108 private ImageToImageFilterCommon 109 { 110 public: 111 ITK_DISALLOW_COPY_AND_ASSIGN(ImageToImageFilter); 112 113 /** Standard class type aliases. */ 114 using Self = ImageToImageFilter; 115 using Superclass = ImageSource< TOutputImage >; 116 using Pointer = SmartPointer< Self >; 117 using ConstPointer = SmartPointer< const Self >; 118 119 /** Run-time type information (and related methods). */ 120 itkTypeMacro(ImageToImageFilter, ImageSource); 121 122 /** Superclass type alias. */ 123 using OutputImageRegionType = typename Superclass::OutputImageRegionType; 124 using OutputImagePixelType = typename Superclass::OutputImagePixelType; 125 126 /** Some convenient type alias. */ 127 using InputImageType = TInputImage; 128 using InputImagePointer = typename InputImageType::Pointer; 129 using InputImageConstPointer = typename InputImageType::ConstPointer; 130 using InputImageRegionType = typename InputImageType::RegionType; 131 using InputImagePixelType = typename InputImageType::PixelType; 132 133 /** ImageDimension constants */ 134 static constexpr unsigned int InputImageDimension = TInputImage::ImageDimension; 135 static constexpr unsigned int OutputImageDimension = TOutputImage::ImageDimension; 136 137 /** Set/Get the image input of this process object. */ 138 using Superclass::SetInput; 139 virtual void SetInput(const InputImageType *image); 140 141 virtual void SetInput(unsigned int, const TInputImage *image); 142 143 const InputImageType * GetInput() const; 144 145 const InputImageType * GetInput(unsigned int idx) const; 146 147 /** Push/Pop the input of this process object. These methods allow a 148 * filter to model its input vector as a queue or stack. These 149 * routines may not be appropriate for all filters, especially 150 * filters with different types of inputs. These routines follow 151 * the semantics of STL. 152 * 153 * The routines are useful for applications that need to process 154 * "rolling" sets of images. For instance, if an application has 10 155 * images and they need to run a filter on images 1, 2, 3, 4, then 156 * run the filter on images 2, 3, 4, 5, then run the filter on 157 * images 3, 4, 5, 6, the application can accomplish this by popping 158 * an input off the front of the input list and push a new image 159 * onto the back of input list. Again, this only makes sense for 160 * filters that single type of input. 161 * 162 * Other uses are also possible. For a single input filter, pushing 163 * and popping inputs allow the application to temporarily replace 164 * an input to a filter. 165 */ 166 virtual void PushBackInput(const InputImageType *image); 167 168 void PopBackInput() override; 169 170 virtual void PushFrontInput(const InputImageType *image); 171 172 void PopFrontInput() override; 173 174 /** get/set the Coordinate tolerance 175 * This tolerance is used when comparing the space defined 176 * by the input images. ITK has a requirement that multiple input 177 * images be congruent in space by default. 178 */ 179 itkSetMacro(CoordinateTolerance,double); 180 itkGetConstMacro(CoordinateTolerance,double); 181 182 /** get/set the direction tolerance 183 * This tolerance is used to make sure that all input 184 * images are oriented the same before performing the filter's 185 * transformations. 186 */ 187 itkSetMacro(DirectionTolerance,double); 188 itkGetConstMacro(DirectionTolerance,double); 189 190 /** get/set the global default direction tolerance 191 * 192 * This value is used to initialize the DirectionTolerance upon 193 * class construction of \b any ImageToImage filter. This has no 194 * effect on currently constructed classes. 195 */ 196 using ImageToImageFilterCommon::SetGlobalDefaultDirectionTolerance; 197 using ImageToImageFilterCommon::GetGlobalDefaultDirectionTolerance; 198 199 200 /** get/set the global default coordinate tolerance 201 * 202 * This value is used to initialize the CoordinateTolerance upon 203 * class construction of \b any ImageToImage filter. This has no 204 * effect on currently constructed classes. 205 */ 206 using ImageToImageFilterCommon::SetGlobalDefaultCoordinateTolerance; 207 using ImageToImageFilterCommon::GetGlobalDefaultCoordinateTolerance; 208 209 210 protected: 211 ImageToImageFilter(); ~ImageToImageFilter()212 ~ImageToImageFilter() override {}; 213 214 void PrintSelf(std::ostream & os, Indent indent) const override; 215 216 /** \brief Verifies that the input images occupy the same physical 217 * space and the each index is at the same physical location. 218 * 219 * The default implementation of the PropagateRequestedRegion 220 * methods copies the index and size from the output to the 221 * input. This makes an implicit assumption that the images occupy 222 * the same physical location at each voxel. This method enforces 223 * that they are the same. 224 * 225 * This implementation verifies that all input images of 226 * InputImageDimensions have the same origin, spacing and direction. 227 * 228 * Filters which do not expect all input images to be at the same 229 * physical location should over-ride this method. Also filters 230 * whose inputs are different dimensions may need to overide this 231 * method. 232 * 233 * \sa ProcessObject::VerifyInputInformation 234 */ 235 void VerifyInputInformation() ITKv5_CONST override; 236 237 /** What is the input requested region that is required to produce 238 * the output requested region? The base assumption for image 239 * processing filters is that the input requested region can be set 240 * to match the output requested region. If a filter requires more 241 * input (for instance a filter that uses neighborhoods needs more 242 * input than output to avoid introducing artificial boundary 243 * conditions) or less input (for instance a magnify filter) will 244 * have to override this method. In doing so, it should call its 245 * superclass' implementation as its first step. Note that imaging 246 * filters operate differently than the classes to this point in the 247 * class hierarchy. Up till now, the base assumption has been that 248 * the largest possible region will be requested of the input. 249 * 250 * This implementation of GenerateInputRequestedRegion() only 251 * processes the inputs that are a subclass of the 252 * ImageBase<InputImageDimension>. If an input is another type of 253 * DataObject (including an Image of a different dimension), they 254 * are skipped by this method. The subclasses of ImageToImageFilter 255 * are responsible for providing an implementation of 256 * GenerateInputRequestedRegion() when there are multiple inputs of 257 * different types. 258 * 259 * \sa ProcessObject::GenerateInputRequestedRegion(), 260 * ImageSource::GenerateInputRequestedRegion() */ 261 void GenerateInputRequestedRegion() override; 262 263 /** Typedef for the region copier function object that converts an 264 * input region to an output region. */ 265 using InputToOutputRegionCopierType = ImageToImageFilterDetail::ImageRegionCopier< 266 Self::OutputImageDimension, 267 Self::InputImageDimension >; 268 269 /** Typedef for the region copier function object that converts an 270 * output region to an input region. */ 271 using OutputToInputRegionCopierType = ImageToImageFilterDetail::ImageRegionCopier< 272 Self::InputImageDimension, 273 Self::OutputImageDimension >; 274 275 /** This function calls the actual region copier to do the mapping 276 * from output image space to input image space. It uses a Function 277 * object used for dispatching to various routines to copy an output 278 * region (start index and size) to an input region. For most 279 * filters, this is a trivial copy because most filters require the 280 * input dimension to match the output dimension. However, some 281 * filters like itk::ExtractImageFilter can support output images of 282 * a lower dimension that the input. 283 * 284 * This function object can be used by GenerateOutputInformation() 285 * to copy the input LargestPossibleRegion to the output 286 * LargestPossibleRegion and can also be used in GenerateData or 287 * ThreadedGenerateData() where a filter may need to map an 288 * output region to an input region. 289 * 290 * The default copier uses a "dispatch pattern" to call one of three 291 * overloaded functions depending on whether the input and output 292 * images are the same dimension, the input is a higher dimension 293 * that the output, or the input is of a lower dimension than the 294 * output. The use of an overloaded function is required for proper 295 * compilation of the various cases. 296 * 297 * For the latter two cases, trivial implementations are used. If 298 * the input image is a higher dimension than the output, the output 299 * region information is copied into the first portion of the input 300 * region and the rest of the input region is set to zero. If the 301 * input region is a lower dimension than the output, the first 302 * portion of the output region is copied to the input region. 303 * 304 * If a filter needs a different default behavior, it can override 305 * this method. The ExtractImageFilter overrides this function 306 * object so that if the input image is a higher dimension than the 307 * output image, the filter can control "where" in the input image 308 * the output subimage is extracted (as opposed to mapping to first 309 * few dimensions of the input). */ 310 virtual void CallCopyOutputRegionToInputRegion(InputImageRegionType & destRegion, 311 const OutputImageRegionType & srcRegion); 312 313 /** This function calls the actual region copier to do the mapping 314 * from input image space to output image space. It uses a Function 315 * object used for dispatching to various routines to copy an input 316 * region (start index and size) to an output region. For most 317 * filters, this is a trivial copy because most filters require the 318 * input dimension to match the output dimension. However, some 319 * filters like itk::UnaryFunctorImageFilter can support output 320 * images of a higher dimension that the input. 321 * 322 * This function object is used by the default implementation of 323 * GenerateOutputInformation(). It can also be used in routines 324 * like ThreadedGenerateData() where a filter may need to map an 325 * input region to an output region. 326 * 327 * The default copier uses a "dispatch pattern" to call one of three 328 * overloaded functions depending on whether the input and output 329 * images are the same dimension, the input is a higher dimension 330 * that the output, or the input is of a lower dimension than the 331 * output. The use of an overloaded function is required for proper 332 * compilation of the various cases. 333 * 334 * For the latter two cases, trivial implementations are used. If 335 * the input image is a higher dimension than the output, the first 336 * portion of the input region is copied to the output region. If 337 * the input region is a lower dimension than the output, the input 338 * region information is copied into the first portion of the output 339 * region and the rest of the output region is set to zero. 340 * 341 * If a filter needs a different default behavior, it can override 342 * this method. */ 343 virtual void CallCopyInputRegionToOutputRegion(OutputImageRegionType & destRegion, 344 const InputImageRegionType & srcRegion); 345 346 /** 347 * PushBackInput(), PushFronInput() in the public section force the 348 * input to be the type expected by an ImageToImageFilter. However, 349 * these methods end of "hiding" the versions from the superclass 350 * (ProcessObject) whose arguments are DataObjects. Here, we re-expose 351 * the versions from ProcessObject to avoid warnings about hiding 352 * methods from the superclass. 353 */ PushBackInput(const DataObject * input)354 void PushBackInput(const DataObject *input) override 355 { Superclass::PushBackInput(input); } PushFrontInput(const DataObject * input)356 void PushFrontInput(const DataObject *input) override 357 { Superclass::PushFrontInput(input); } 358 359 private: 360 /** 361 * Tolerances for checking whether input images are defined to 362 * occupy the same physical space. 363 */ 364 double m_CoordinateTolerance; 365 double m_DirectionTolerance; 366 }; 367 } // end namespace itk 368 369 #ifndef ITK_MANUAL_INSTANTIATION 370 #include "itkImageToImageFilter.hxx" 371 #endif 372 373 #endif 374