Merge pull request #6263 from hjmjohnson/ingest-MultipleImageIterator

ENH: Ingest MultipleImageIterator into Modules/Core

Author: hjmjohnson

Modules/Core/MultipleImageIterator/CMakeLists.txt

@@ -0,0 +1,3 @@
+project(MultipleImageIterator)
+
+itk_module_impl()

Modules/Core/MultipleImageIterator/README.md

@@ -0,0 +1,24 @@
+# MultipleImageIterator
+
+In-tree ITK module providing `itk::MultipleImageIterator`, a single
+iterator that walks any number of co-registered images in lockstep.
+The iterator returns a `std::vector` of pixel values (or references)
+at each position, simplifying multi-channel processing without the
+boilerplate of synchronizing N separate iterators.
+
+## Origin
+
+Ingested from the standalone remote module
+[**KitwareMedical/MultipleImageIterator**](https://github.com/KitwareMedical/MultipleImageIterator)
+on 2026-05-12, following the v4 ingestion guidelines defined in
+InsightSoftwareConsortium/ITK#6204. Placed under `Modules/Core/` to
+match the placement of other ITK iterators (`itkImageRegionIterator`,
+`itkNeighborhoodIterator`). The upstream repository will be archived
+read-only after this PR merges; it remains reachable at the URL above
+for historical reference.
+
+## References
+
+- Schaerer J. *A MultipleImageIterator for iterating over multiple
+  images simultaneously.* The Insight Journal. December 2014.
+  <https://doi.org/10.54294/e5lmyz>

Modules/Core/MultipleImageIterator/include/itkMultipleImageIterator.h

@@ -0,0 +1,99 @@
+/*=========================================================================
+ *
+ *  Copyright NumFOCUS
+ *
+ *  Licensed under the Apache License, Version 2.0 (the "License");
+ *  you may not use this file except in compliance with the License.
+ *  You may obtain a copy of the License at
+ *
+ *         https://www.apache.org/licenses/LICENSE-2.0.txt
+ *
+ *  Unless required by applicable law or agreed to in writing, software
+ *  distributed under the License is distributed on an "AS IS" BASIS,
+ *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ *  See the License for the specific language governing permissions and
+ *  limitations under the License.
+ *
+ *=========================================================================*/
+
+#ifndef itkMultipleImageIterator_h
+#define itkMultipleImageIterator_h
+#include <vector>
+#include <itkImageRegionIterator.h>
+
+
+namespace itk
+{
+/** \class MultipleImageIterator
+ * \brief An wrapper around image iterators to iterate over several images simultaneously
+ * All iterators must
+ *  - point to images of the same type
+ *  - be of the same size (number of values from begin to end)
+ * \ingroup ImageIterators
+ * \ingroup MultipleImageIterator */
+template <typename TIterator>
+class MultipleImageIterator
+{
+public:
+  using Self = MultipleImageIterator;
+  using IteratorType = TIterator;
+  using ImageType = typename IteratorType::ImageType;
+  /// Access one of the iterators
+  IteratorType &
+  operator[](const unsigned int i)
+  {
+    return m_Iterators[i];
+  }
+  /// Add a new iterator
+  void
+  AddIterator(const IteratorType & it)
+  {
+    m_Iterators.push_back(it);
+  }
+  /// Advance all iterators
+  Self &
+  operator++()
+  {
+    for (auto it = m_Iterators.begin(); it != m_Iterators.end(); ++it)
+    {
+      ++(*it);
+    }
+    return *this;
+  }
+  /// Rewind all iterators
+  void
+  GoToBegin()
+  {
+    for (auto it = m_Iterators.begin(); it != m_Iterators.end(); ++it)
+    {
+      it->GoToBegin();
+    }
+  }
+  /** Check if the first iterator is at end. In debug mode, additionally check
+   * that at least one iterator is present and that all iterators' IsAtEnd()
+   * methods return the same thing */
+  bool
+  IsAtEnd()
+  {
+#ifdef NDEBUG
+    return m_Iterators[0].IsAtEnd();
+#else
+    assert(m_Iterators.size());
+    bool retval = m_Iterators[0].IsAtEnd();
+    for (unsigned int i = 0; i < m_Iterators.size(); ++i)
+      assert(m_Iterators[i].IsAtEnd() == retval);
+    return retval;
+#endif
+  }
+  /// Returns the number of iterators
+  unsigned int
+  Size() const
+  {
+    return m_Iterators.size();
+  }
+
+protected:
+  std::vector<IteratorType> m_Iterators;
+};
+} // namespace itk
+#endif // itkMultipleImageIterator_h

Modules/Core/MultipleImageIterator/itk-module.cmake

@@ -0,0 +1,11 @@
+# Maintainer: Joel Schaerer
+itk_module(
+  MultipleImageIterator
+  DEPENDS
+    ITKCommon
+  TEST_DEPENDS
+    ITKTestKernel
+  EXCLUDE_FROM_DEFAULT
+  DESCRIPTION
+    "An iterator wrapper that walks multiple co-registered images in lockstep, returning a std::vector of pixel values at each position. https://doi.org/10.54294/e5lmyz"
+)

Modules/Core/MultipleImageIterator/test/CMakeLists.txt

@@ -0,0 +1,19 @@
+itk_module_test()
+
+set(MultipleImageIteratorTests DumpIntensities.cxx)
+
+createtestdriver(MultipleImageIterator "${MultipleImageIterator-Test_LIBRARIES}" "${MultipleImageIteratorTests}")
+
+itk_add_test(
+  NAME MultipleImageIteratorTest
+  COMMAND
+    MultipleImageIteratorTestDriver
+    --compare
+    DATA{randBase.nrrd}
+    "${ITK_TEST_OUTPUT_DIR}/randOut.nrrd"
+    DumpIntensities
+    "${ITK_TEST_OUTPUT_DIR}/randOut.nrrd"
+    DATA{img1.png}
+    DATA{img2.png}
+    DATA{img3.png}
+)

Modules/Core/MultipleImageIterator/test/DumpIntensities.cxx

@@ -0,0 +1,95 @@
+/*=========================================================================
+ *
+ *  Copyright NumFOCUS
+ *
+ *  Licensed under the Apache License, Version 2.0 (the "License");
+ *  you may not use this file except in compliance with the License.
+ *  You may obtain a copy of the License at
+ *
+ *         https://www.apache.org/licenses/LICENSE-2.0.txt
+ *
+ *  Unless required by applicable law or agreed to in writing, software
+ *  distributed under the License is distributed on an "AS IS" BASIS,
+ *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ *  See the License for the specific language governing permissions and
+ *  limitations under the License.
+ *
+ *=========================================================================*/
+
+#include <iostream>
+#include <vector>
+#include <string>
+#include <cstdlib>
+#include <itkImageFileReader.h>
+#include <itkImageFileWriter.h>
+#include "itkMultipleImageIterator.h"
+
+// Dumps random samples from files into a csv file
+
+int
+DumpIntensities(int argc, char * argv[])
+{
+  if (argc < 3)
+  {
+    std::cerr << "Usage: DumpIntensities outfile inImage [inImage ...]" << std::endl;
+    return 1;
+  }
+  using PixelType = unsigned short;
+  using ImageType = itk::Image<PixelType, 3>;
+  using ReaderType = itk::ImageFileReader<ImageType>;
+
+  using IteratorType = itk::ImageRegionIterator<ImageType>;
+  itk::MultipleImageIterator<IteratorType> it;
+
+  std::vector<ImageType::Pointer> images; // Need to keep a reference as iterators only have weak references
+  for (int i = 2; i < argc; ++i)
+  {
+    ReaderType::Pointer r = ReaderType::New();
+    r->SetFileName(argv[i]);
+    r->Update();
+    ImageType::Pointer im = r->GetOutput();
+    im->DisconnectPipeline();
+    images.push_back(im);
+    it.AddIterator(itk::ImageRegionIterator<ImageType>(im, im->GetLargestPossibleRegion()));
+  }
+
+  unsigned long long c = 0;
+  using Vec3 = itk::FixedArray<PixelType, 3>;
+  std::vector<Vec3> values;
+  for (it.GoToBegin(); !it.IsAtEnd(); ++it, ++c)
+  {
+    if (c % 42 == 0)
+    {
+      Vec3 v;
+      for (unsigned int i = 0; i < it.Size(); ++i)
+      {
+        v[i] = it[i].Get();
+      }
+      values.push_back(v);
+    }
+  }
+
+  using Image1D = itk::Image<Vec3, 1>;
+  Image1D::RegionType region;
+  region.SetIndex(0, 0);
+  region.SetSize(0, values.size());
+  Image1D::Pointer randImage = Image1D::New();
+  randImage->SetRegions(region);
+  randImage->Allocate();
+
+  int                               index = 0;
+  itk::ImageRegionIterator<Image1D> oIt(randImage, randImage->GetLargestPossibleRegion());
+  while (!oIt.IsAtEnd())
+  {
+    oIt.Set(values[index++]);
+    ++oIt;
+  }
+
+  using WriterType = itk::ImageFileWriter<Image1D>;
+  WriterType::Pointer writer = WriterType::New();
+  writer->SetInput(randImage);
+  writer->SetFileName(argv[1]);
+  writer->Update();
+
+  return 0;
+}

Modules/Core/MultipleImageIterator/test/img1.png.cid

@@ -0,0 +1 @@
+bafkreicd6xi33oatbqzspxkeszliv3mmjnnmiiu6dj6qj6wuclkv7uokda

Modules/Core/MultipleImageIterator/test/img2.png.cid

@@ -0,0 +1 @@
+bafkreiactetnzqheknc2zjeg6aoo6y7uqbid7oukpwttfjuj52stok6wbe

Modules/Core/MultipleImageIterator/test/img3.png.cid

@@ -0,0 +1 @@
+bafkreibqkbie3ezhl2y2kvgfizpoj5qfz3y5xdbe5rqtjo35pb5zn5geti

Modules/Core/MultipleImageIterator/test/randBase.nrrd.cid

@@ -0,0 +1 @@
+bafkreihso7ziayrcpwm22dbjctew7ju3a7egxdyoytdn4ueuwggu26tscq