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 #ifndef itkImageRegionConstIteratorWithIndex_h 19 #define itkImageRegionConstIteratorWithIndex_h 20 21 #include "itkImageConstIteratorWithIndex.h" 22 23 namespace itk 24 { 25 /** \class ImageRegionConstIteratorWithIndex 26 * \brief A multi-dimensional 27 * iterator templated over image type that walks an image region and is 28 * specialized to keep track of its index location. 29 * 30 * The "WithIndex" family of iteators was designed for algorithms that use both 31 * the values and locations of image pixels in calculations. Unlike 32 * ImageRegionIterator, which calculates an index only when requested, 33 * ImageRegionIteratorWithIndex maintains its index location as a member 34 * variable that is updated during increment and decrement operations. 35 * Iteration speed is penalized, but index queries become more efficient. 36 * 37 * ImageRegionConstIteratorWithIndex is a multi-dimensional iterator, 38 * requiring more information be specified before the iterator can be 39 * used than conventional iterators. Whereas the std::vector::iterator 40 * from the STL only needs to be passed a pointer to establish the 41 * iterator, the multi-dimensional image iterator needs a pointer, the 42 * size of the buffer, the size of the region, the start index of the 43 * buffer, and the start index of the region. To gain access to this 44 * information, ImageRegionConstIteratorWithIndex holds a reference to the 45 * image over which it is traversing. 46 * 47 * ImageRegionConstIteratorWithIndex assumes a particular layout of 48 * the image data. The is arranged in a 1D array as if it were 49 * [][][][slice][row][col] with Index[0] = col, Index[1] = row, 50 * Index[2] = slice, etc. 51 * 52 * operator++ provides a simple syntax for walking around a region of 53 * a multidimensional image. operator++ iterates across a row, constraining 54 * the movement to within a region of image. When the iterator reaches 55 * the boundary of the region along a row, the iterator automatically 56 * wraps to the next row, starting at the first pixel in the row that is 57 * part of the region. This allows for simple processing loops of the form: 58 * 59 \code 60 61 IteratorType it( image, image->GetRequestedRegion() ); 62 63 it.Begin(); 64 65 while( ! it.IsAtEnd() ) 66 { 67 it.Set( 100.0 + it.Get() ); 68 ++it; 69 } 70 71 \endcode 72 * 73 * It also can be used for walking in the reverse direction like 74 * 75 \code 76 77 IteratorType it( image, image->GetRequestedRegion() ); 78 79 it.End(); 80 81 while( !it.IsAtBegin() ) 82 { 83 it.Set( 100.0 ); 84 --it; 85 } 86 87 \endcode 88 * 89 * \par MORE INFORMATION 90 * 91 * For a complete description of the ITK Image Iterators and their API, please 92 * see the Iterators chapter in the ITK Software Guide. The ITK Software Guide 93 * is available in print and as a free .pdf download from https://www.itk.org. 94 * 95 * \ingroup ImageIterators 96 * 97 * \sa ImageConstIterator \sa ConditionalConstIterator 98 * \sa ConstNeighborhoodIterator \sa ConstShapedNeighborhoodIterator 99 * \sa ConstSliceIterator \sa CorrespondenceDataStructureIterator 100 * \sa FloodFilledFunctionConditionalConstIterator 101 * \sa FloodFilledImageFunctionConditionalConstIterator 102 * \sa FloodFilledImageFunctionConditionalIterator 103 * \sa FloodFilledSpatialFunctionConditionalConstIterator 104 * \sa FloodFilledSpatialFunctionConditionalIterator 105 * \sa ImageConstIterator \sa ImageConstIteratorWithIndex 106 * \sa ImageIterator \sa ImageIteratorWithIndex 107 * \sa ImageLinearConstIteratorWithIndex \sa ImageLinearIteratorWithIndex 108 * \sa ImageRandomConstIteratorWithIndex \sa ImageRandomIteratorWithIndex 109 * \sa ImageRegionConstIterator \sa ImageRegionConstIteratorWithIndex 110 * \sa ImageRegionExclusionConstIteratorWithIndex 111 * \sa ImageRegionExclusionIteratorWithIndex 112 * \sa ImageRegionIterator \sa ImageRegionIteratorWithIndex 113 * \sa ImageRegionReverseConstIterator \sa ImageRegionReverseIterator 114 * \sa ImageReverseConstIterator \sa ImageReverseIterator 115 * \sa ImageSliceConstIteratorWithIndex \sa ImageSliceIteratorWithIndex 116 * \sa NeighborhoodIterator \sa PathConstIterator \sa PathIterator 117 * \sa ShapedNeighborhoodIterator \sa SliceIterator 118 * \sa ImageConstIteratorWithIndex 119 * \ingroup ITKCommon 120 * 121 * 122 * \wiki 123 * \wikiexample{Iterators/ImageRegionConstIteratorWithIndex,Iterate over a region of an image with efficient access to the current index (without write access)} 124 * \endwiki 125 */ 126 template< typename TImage > 127 class ITK_TEMPLATE_EXPORT ImageRegionConstIteratorWithIndex:public ImageConstIteratorWithIndex< TImage > 128 { 129 public: 130 /** Standard class type aliases. */ 131 using Self = ImageRegionConstIteratorWithIndex; 132 using Superclass = ImageConstIteratorWithIndex< TImage >; 133 134 /** 135 * Index type alias support While these were already typdef'ed in the superclass 136 * they need to be redone here for this subclass to compile properly with gcc. 137 */ 138 /** Types inherited from the Superclass */ 139 using IndexType = typename Superclass::IndexType; 140 using SizeType = typename Superclass::SizeType; 141 using OffsetType = typename Superclass::OffsetType; 142 using RegionType = typename Superclass::RegionType; 143 using ImageType = typename Superclass::ImageType; 144 using PixelContainer = typename Superclass::PixelContainer; 145 using PixelContainerPointer = typename Superclass::PixelContainerPointer; 146 using InternalPixelType = typename Superclass::InternalPixelType; 147 using PixelType = typename Superclass::PixelType; 148 using AccessorType = typename Superclass::AccessorType; 149 150 /** Default constructor. Needed since we provide a cast constructor. */ ImageRegionConstIteratorWithIndex()151 ImageRegionConstIteratorWithIndex():ImageConstIteratorWithIndex< TImage >() {} 152 153 /** Constructor establishes an iterator to walk a particular image and a 154 * particular region of that image. */ ImageRegionConstIteratorWithIndex(const TImage * ptr,const RegionType & region)155 ImageRegionConstIteratorWithIndex(const TImage *ptr, 156 const RegionType & region): 157 ImageConstIteratorWithIndex< TImage >(ptr, region) {} 158 159 /** Constructor that can be used to cast from an ImageIterator to an 160 * ImageRegionConstIteratorWithIndex. Many routines return an ImageIterator but for a 161 * particular task, you may want an ImageRegionConstIteratorWithIndex. Rather than 162 * provide overloaded APIs that return different types of Iterators, itk 163 * returns ImageIterators and uses constructors to cast from an 164 * ImageIterator to a ImageRegionConstIteratorWithIndex. */ ImageRegionConstIteratorWithIndex(const ImageConstIteratorWithIndex<TImage> & it)165 ImageRegionConstIteratorWithIndex(const ImageConstIteratorWithIndex< TImage > & it) 166 { this->ImageConstIteratorWithIndex< TImage >::operator=(it); } 167 168 /** Increment (prefix) the fastest moving dimension of the iterator's index. 169 * This operator will constrain the iterator within the region (i.e. the 170 * iterator will automatically wrap from the end of the row of the region 171 * to the beginning of the next row of the region) up until the iterator 172 * tries to moves past the last pixel of the region. Here, the iterator 173 * will be set to be one pixel past the end of the region. 174 * \sa operator-- */ 175 Self & operator++(); 176 177 /** Decrement (prefix) the fastest moving dimension of the iterator's index. 178 * This operator will constrain the iterator within the region (i.e. the 179 * iterator will automatically wrap from the beginning of the row of the 180 * region to the end of the previous row of the region) up until the iterator 181 * tries to moves past the first pixel of the region. Here, the iterator 182 * will be set to be one pixel past the beginning of the region. 183 * \sa operator++ */ 184 Self & operator--(); 185 }; 186 } // end namespace itk 187 188 #ifndef ITK_MANUAL_INSTANTIATION 189 #include "itkImageRegionConstIteratorWithIndex.hxx" 190 #endif 191 192 #endif 193