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