ENH: Ingest ITKMultipleImageIterator into Modules/Core

Brings MultipleImageIterator from a configure-time remote fetch into the ITK
source tree at Modules/Core/MultipleImageIterator/ using the v4 ingestion
pipeline (whitelist filter-repo + per-commit clang-format + black +
commit-prefix sanitization).

Upstream repo:  https://github.com/KitwareMedical/MultipleImageIterator.git
Upstream tip:   32f67c75cce9be0ceac7876428930be64d99a57b
Ingest date:    2026-05-12
Whitelist:      MultipleImageIterator.list

Per-commit transforms applied across all 16 commits:
  - filter-repo --paths-from-file (whitelist)
  - filter-repo --to-subdirectory-filter Modules/Core/MultipleImageIterator
  - clang-format -style=file (ITK main's .clang-format) for *.cxx/.h/.hxx/...
  - black for *.py
  - heuristic ITK prefix added to commit subjects without one

Merge topology preserved: 8 -> 3 merge(s).

Primary author: Dženan Zukić <dzenan.zukic@kitware.com>

Co-authored-by: Bradley Lowekamp <blowekamp@mail.nih.gov>
Co-authored-by: Hans J. Johnson <hans-johnson@uiowa.edu>
Co-authored-by: Hans Johnson <hans-johnson@uiowa.edu>
Co-authored-by: Hans Johnson <hans.j.johnson@gmail.com>
Co-authored-by: Tom Birdsong <tom.birdsong@kitware.com>

Author: 3 people

Modules/Core/MultipleImageIterator/CMakeLists.txt

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

Modules/Core/MultipleImageIterator/include/itkMultipleImageIterator.h

@@ -0,0 +1,98 @@
+/*=========================================================================
+ *
+ *  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 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 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,28 @@
+set(
+  DOCUMENTATION
+  "Several applications such as multi-atlas segmentation
+require frequent iteration over multiple image volumes at the same time.
+Doing so with the regular ITK iterators is tedious and error prone
+as it requires updating each iterator at end of each iteration.
+Failing to do so results in hard to debug errors and crashes.
+The MultipleImageIterator is a simple wrapper class that tries to make this more convenient.
+
+A more detailed description can be found in the Insight Journal article::
+Schaerer J. \"A MultipleImageIterator for iterating over multiple images simultaneously\".
+  https://hdl.handle.net/10380/3455
+  https://www.insight-journal.org/browse/publication/915
+  December, 2014.
+"
+)
+
+itk_module(
+  MultipleImageIterator
+  # DEPENDS
+  # ITKCommon
+  COMPILE_DEPENDS
+    ITKCommon
+  TEST_DEPENDS
+    ITKTestKernel
+  EXCLUDE_FROM_DEFAULT
+  DESCRIPTION "${DOCUMENTATION}"
+)

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,96 @@
+/*=========================================================================
+ *
+ *  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
+using namespace std;
+
+int
+DumpIntensities(int argc, char * argv[])
+{
+  if (argc < 3)
+  {
+    cerr << "Usage: DumpIntensities outfile inImage [inImage ...]" << 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;
+
+  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>;
+  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