Repository: InsightSoftwareConsortium/ITK (language: python)

Issue:
Document that Iterator(image, region) constructors initialize at the begin, add GTest unit test
Documented that `Iterator(image, region)` constructors initialize the iterator at the beginning of the region. Added a GoogleTest unit test to checks this added specification. 

STYLE: Remove unused "itkFrequencyImageRegion*IteratorWithIndex.h" files
Both `FrequencyImageRegionIteratorWithIndex` and `FrequencyImageRegionConstIteratorWithIndex` appear unused and untested. Attempts to use them would trigger compile errors.

An attempt to use `FrequencyImageRegionIteratorWithIndex` triggered:

    error C3210: 'ImageRegionIteratorWithIndex<itk::Image<int,2> >': a member using-declaration can only be applied to a base class member

An attempt to use `FrequencyImageRegionConstIteratorWithIndex` triggered:

    error C2679: binary '=': no operator found which takes a right-hand operand of type 'const itk::Point<T,3>' (or there is no acceptable conversion)

This commit removes their header files. It also removes the suggestion to use `FrequencyImageRegionIteratorWithIndex` from the documentation of UnaryFrequencyDomainFilter.


Discussion / hints:

Fix patch:
diff --git a/Modules/Filtering/ImageFrequency/include/itkFrequencyFFTLayoutImageRegionConstIteratorWithIndex.h b/Modules/Filtering/ImageFrequency/include/itkFrequencyFFTLayoutImageRegionConstIteratorWithIndex.h
index 22542adb93b..150466deb9d 100644
--- a/Modules/Filtering/ImageFrequency/include/itkFrequencyFFTLayoutImageRegionConstIteratorWithIndex.h
+++ b/Modules/Filtering/ImageFrequency/include/itkFrequencyFFTLayoutImageRegionConstIteratorWithIndex.h
@@ -141,8 +141,8 @@ class ITK_TEMPLATE_EXPORT FrequencyFFTLayoutImageRegionConstIteratorWithIndex
     this->Init();
   }
 
-  /** Constructor establishes an iterator to walk a particular image and a
-   * particular region of that image. */
+  /** Constructor establishes an iterator to walk a particular image and a particular region of that image. Initializes
+   * the iterator at the begin of the region. */
   FrequencyFFTLayoutImageRegionConstIteratorWithIndex(const TImage * ptr, const RegionType & region)
     : ImageRegionConstIteratorWithIndex<TImage>(ptr, region)
   {
diff --git a/Modules/Filtering/ImageFrequency/include/itkFrequencyFFTLayoutImageRegionIteratorWithIndex.h b/Modules/Filtering/ImageFrequency/include/itkFrequencyFFTLayoutImageRegionIteratorWithIndex.h
index 20ec5b7b5d9..657ec73c49c 100644
--- a/Modules/Filtering/ImageFrequency/include/itkFrequencyFFTLayoutImageRegionIteratorWithIndex.h
+++ b/Modules/Filtering/ImageFrequency/include/itkFrequencyFFTLayoutImageRegionIteratorWithIndex.h
@@ -88,8 +88,8 @@ class FrequencyFFTLayoutImageRegionIteratorWithIndex
     : FrequencyFFTLayoutImageRegionConstIteratorWithIndex<TImage>()
   {}
 
-  /** Constructor establishes an iterator to walk a particular image and a
-   * particular region of that image. */
+  /** Constructor establishes an iterator to walk a particular image and a particular region of that image. Initializes
+   * the iterator at the begin of the region. */
   FrequencyFFTLayoutImageRegionIteratorWithIndex(TImage * ptr, const RegionType & region)
     : FrequencyFFTLayoutImageRegionConstIteratorWithIndex<TImage>(ptr, region)
   {}
diff --git a/Modules/Filtering/ImageFrequency/include/itkFrequencyHalfHermitianFFTLayoutImageRegionConstIteratorWithIndex.h b/Modules/Filtering/ImageFrequency/include/itkFrequencyHalfHermitianFFTLayoutImageRegionConstIteratorWithIndex.h
index 509d4115474..332c3b0b38d 100644
--- a/Modules/Filtering/ImageFrequency/include/itkFrequencyHalfHermitianFFTLayoutImageRegionConstIteratorWithIndex.h
+++ b/Modules/Filtering/ImageFrequency/include/itkFrequencyHalfHermitianFFTLayoutImageRegionConstIteratorWithIndex.h
@@ -147,8 +147,8 @@ class FrequencyHalfHermitianFFTLayoutImageRegionConstIteratorWithIndex
     this->Init();
   }
 
-  /** Constructor establishes an iterator to walk a particular image and a
-   * particular region of that image. */
+  /** Constructor establishes an iterator to walk a particular image and a particular region of that image. Initializes
+   * the iterator at the begin of the region. */
   FrequencyHalfHermitianFFTLayoutImageRegionConstIteratorWithIndex(const TImage * ptr, const RegionType & region)
     : ImageRegionConstIteratorWithIndex<TImage>(ptr, region)
   {
diff --git a/Modules/Filtering/ImageFrequency/include/itkFrequencyHalfHermitianFFTLayoutImageRegionIteratorWithIndex.h b/Modules/Filtering/ImageFrequency/include/itkFrequencyHalfHermitianFFTLayoutImageRegionIteratorWithIndex.h
index 28ae44b399f..004bd40a370 100644
--- a/Modules/Filtering/ImageFrequency/include/itkFrequencyHalfHermitianFFTLayoutImageRegionIteratorWithIndex.h
+++ b/Modules/Filtering/ImageFrequency/include/itkFrequencyHalfHermitianFFTLayoutImageRegionIteratorWithIndex.h
@@ -88,8 +88,8 @@ class FrequencyHalfHermitianFFTLayoutImageRegionIteratorWithIndex
     : FrequencyHalfHermitianFFTLayoutImageRegionConstIteratorWithIndex<TImage>()
   {}
 
-  /** Constructor establishes an iterator to walk a particular image and a
-   * particular region of that image. */
+  /** Constructor establishes an iterator to walk a particular image and a particular region of that image. Initializes
+   * the iterator at the begin of the region. */
   FrequencyHalfHermitianFFTLayoutImageRegionIteratorWithIndex(TImage * ptr, const RegionType & region)
     : FrequencyHalfHermitianFFTLayoutImageRegionConstIteratorWithIndex<TImage>(ptr, region)
   {}
diff --git a/Modules/Filtering/ImageFrequency/include/itkFrequencyShiftedFFTLayoutImageRegionConstIteratorWithIndex.h b/Modules/Filtering/ImageFrequency/include/itkFrequencyShiftedFFTLayoutImageRegionConstIteratorWithIndex.h
index 055c729c46a..f3034fbf3a2 100644
--- a/Modules/Filtering/ImageFrequency/include/itkFrequencyShiftedFFTLayoutImageRegionConstIteratorWithIndex.h
+++ b/Modules/Filtering/ImageFrequency/include/itkFrequencyShiftedFFTLayoutImageRegionConstIteratorWithIndex.h
@@ -141,8 +141,8 @@ class ITK_TEMPLATE_EXPORT FrequencyShiftedFFTLayoutImageRegionConstIteratorWithI
     this->Init();
   }
 
-  /** Constructor establishes an iterator to walk a particular image and a
-   * particular region of that image. */
+  /** Constructor establishes an iterator to walk a particular image and a particular region of that image. Initializes
+   * the iterator at the begin of the region. */
   FrequencyShiftedFFTLayoutImageRegionConstIteratorWithIndex(const TImage * ptr, const RegionType & region)
     : ImageRegionConstIteratorWithIndex<TImage>(ptr, region)
   {
diff --git a/Modules/Filtering/ImageFrequency/include/itkFrequencyShiftedFFTLayoutImageRegionIteratorWithIndex.h b/Modules/Filtering/ImageFrequency/include/itkFrequencyShiftedFFTLayoutImageRegionIteratorWithIndex.h
index 732f751dc42..0abc0a047d0 100644
--- a/Modules/Filtering/ImageFrequency/include/itkFrequencyShiftedFFTLayoutImageRegionIteratorWithIndex.h
+++ b/Modules/Filtering/ImageFrequency/include/itkFrequencyShiftedFFTLayoutImageRegionIteratorWithIndex.h
@@ -88,8 +88,8 @@ class FrequencyShiftedFFTLayoutImageRegionIteratorWithIndex
     : FrequencyShiftedFFTLayoutImageRegionConstIteratorWithIndex<TImage>()
   {}
 
-  /** Constructor establishes an iterator to walk a particular image and a
-   * particular region of that image. */
+  /** Constructor establishes an iterator to walk a particular image and a particular region of that image. Initializes
+   * the iterator at the begin of the region. */
   FrequencyShiftedFFTLayoutImageRegionIteratorWithIndex(TImage * ptr, const RegionType & region)
     : FrequencyShiftedFFTLayoutImageRegionConstIteratorWithIndex<TImage>(ptr, region)
   {}


Test patch:
diff --git a/Modules/Filtering/ImageFrequency/test/itkFrequencyIteratorsGTest.cxx b/Modules/Filtering/ImageFrequency/test/itkFrequencyIteratorsGTest.cxx
index c8c8ed033ad..58de2552b1e 100644
--- a/Modules/Filtering/ImageFrequency/test/itkFrequencyIteratorsGTest.cxx
+++ b/Modules/Filtering/ImageFrequency/test/itkFrequencyIteratorsGTest.cxx
@@ -27,8 +27,11 @@
 #include "itkFFTShiftImageFilter.h"
 #include "itkFrequencyBandImageFilter.h" // Simplest of frequency filters for testing
 #include "itkFrequencyFFTLayoutImageRegionConstIteratorWithIndex.h"
-#include "itkFrequencyShiftedFFTLayoutImageRegionIteratorWithIndex.h"
+#include "itkFrequencyFFTLayoutImageRegionIteratorWithIndex.h"
+#include "itkFrequencyHalfHermitianFFTLayoutImageRegionConstIteratorWithIndex.h"
 #include "itkFrequencyHalfHermitianFFTLayoutImageRegionIteratorWithIndex.h"
+#include "itkFrequencyShiftedFFTLayoutImageRegionConstIteratorWithIndex.h"
+#include "itkFrequencyShiftedFFTLayoutImageRegionIteratorWithIndex.h"
 #include "itkImage.h"
 #include "itkImageFileWriter.h"
 #include "itkTestingComparisonImageFilter.h"
@@ -51,6 +54,49 @@ class FrequencyIterators : public ::testing::Test
     RegisterRequiredFactories();
   }
 };
+
+
+template <typename TIterator>
+void
+CheckConstructedAtBegin()
+{
+  using ImageType = typename TIterator::ImageType;
+  using IndexType = typename TIterator::IndexType;
+  using SizeType = typename TIterator::SizeType;
+  using RegionType = typename TIterator::RegionType;
+
+  const auto image = ImageType::New();
+
+  // Use a small image size, so that the unit test won't take a long time.
+  static constexpr itk::SizeValueType imageSizeValue{ 4 };
+
+  image->SetRegions(SizeType::Filled(imageSizeValue));
+  image->Allocate();
+
+  // Check various regions, specified by the following `indexValue` and `sizeValue` combinations:
+  for (const itk::IndexValueType indexValue : { 0, 1 })
+  {
+    for (const auto sizeValue : { itk::SizeValueType{ 1 }, imageSizeValue - 1 })
+    {
+      const RegionType imageRegion(IndexType::Filled(indexValue), SizeType::Filled(sizeValue));
+
+      const TIterator iterator(image, imageRegion);
+      TIterator       iteratorThatGoesToBegin = iterator;
+      iteratorThatGoesToBegin.GoToBegin();
+      EXPECT_EQ(iterator, iteratorThatGoesToBegin);
+    }
+  }
+}
+
+
+template <template <typename> typename... TIteratorTemplate>
+void
+CheckIteratorsConstructedAtBegin()
+{
+  (CheckConstructedAtBegin<TIteratorTemplate<itk::Image<int>>>(), ...);
+  (CheckConstructedAtBegin<TIteratorTemplate<itk::Image<double, 3>>>(), ...);
+}
+
 } // namespace
 
 template <typename TOutputImageType>
@@ -214,6 +260,19 @@ compareAllTypesOfIterators(typename TImageType::Pointer image, double difference
   EXPECT_TRUE(fullAndHermitian);
 }
 
+
+// Checks that an iterator that is just constructed by `IteratorType(image, region)` is at the begin.
+TEST_F(FrequencyIterators, AreConstructedAtBegin)
+{
+  CheckIteratorsConstructedAtBegin<itk::FrequencyFFTLayoutImageRegionConstIteratorWithIndex,
+                                   itk::FrequencyFFTLayoutImageRegionIteratorWithIndex,
+                                   itk::FrequencyHalfHermitianFFTLayoutImageRegionConstIteratorWithIndex,
+                                   itk::FrequencyHalfHermitianFFTLayoutImageRegionIteratorWithIndex,
+                                   itk::FrequencyShiftedFFTLayoutImageRegionConstIteratorWithIndex,
+                                   itk::FrequencyShiftedFFTLayoutImageRegionIteratorWithIndex>();
+}
+
+
 TEST_F(FrequencyIterators, Even3D)
 {
   constexpr unsigned int ImageDimension = 3;