Merge pull request #6137 from hjmjohnson/ingest-MGHIO

ENH: Ingest ITKMGHIO into Modules/IO

Author: hjmjohnson

Modules/IO/MGHIO/CMakeLists.txt

@@ -0,0 +1,3 @@
+project(MGHIO)
+set(MGHIO_LIBRARIES MGHIO)
+itk_module_impl()

Modules/IO/MGHIO/README.md

@@ -0,0 +1,66 @@
+# MGHIO
+
+In-tree ITK module providing an `itk::MGHImageIO` plugin for the
+`.mgh` / `.mgz` (MGH) volume format used by the FreeSurfer
+neuroimaging toolchain. The factory `itk::MGHImageIOFactory`
+auto-registers with `itk::ImageIOFactory` so any
+`itk::ImageFileReader` / `itk::ImageFileWriter` transparently picks
+up `.mgh` / `.mgz` files when the module is enabled.
+
+## Origin
+
+Ingested from the standalone remote module
+[**InsightSoftwareConsortium/itkMGHImageIO**](https://github.com/InsightSoftwareConsortium/itkMGHImageIO)
+on 2026-04-27, at upstream commit
+[`af74507c`](https://github.com/InsightSoftwareConsortium/itkMGHImageIO/commit/af74507c1ddc82722637c37d1f5d169e3000553a).
+The upstream repository will be archived read-only after this PR
+merges; it remains reachable at the URL above.
+
+## What lives here
+
+Per the v3 ingestion strategy (see
+`Utilities/Maintenance/RemoteModuleIngest/INGESTION_STRATEGY.md`), only
+paths matching the narrow whitelist (code, headers, tests, wrapping,
+module CMake) crossed the merge boundary:
+
+- `include/` — public C++ headers (`itkMGHImageIO.h`, `itkMGHImageIOFactory.h`).
+- `src/` — non-template implementation.
+- `test/` — CTest drivers and content-link stubs.
+- `wrapping/` — Python wrapping descriptors.
+- `CMakeLists.txt`, `itk-module.cmake` — build + module descriptors.
+
+Every surviving commit preserves original authorship; `git blame`
+walks across the merge boundary to upstream authors going back to the
+module's earliest history.
+
+## What was intentionally left upstream
+
+Everything outside the whitelist stays in the archived upstream repo.
+If you need any of it, clone
+<https://github.com/InsightSoftwareConsortium/itkMGHImageIO>.
+
+| Content in upstream | Why it did not ingest |
+|---|---|
+| `.github/`, `azure-pipelines.yml`, `Dockerfile` | Standalone-build CI scaffolding; not useful in-tree. |
+| `CTestConfig.cmake`, `pyproject.toml`, `LICENSE`, `.clang-format` | Packaging / CI / style scaffolding superseded by ITK root. |
+| Historical `Old/`, `paper/`, `docs/`, demo asset trees | Stripped by the whitelist to protect ITK's git pack from bloat. |
+
+## Long-form documentation
+
+- **Format reference** — see the FreeSurfer documentation:
+  <https://surfer.nmr.mgh.harvard.edu/fswiki/FsTutorial/MghFormat>.
+- **Standalone build + history** — see the archived upstream at
+  <https://github.com/InsightSoftwareConsortium/itkMGHImageIO>.
+
+## Compliance level
+
+Compliance Level 2 (Alpha — niche execution environment dependence:
+FreeSurfer-format I/O). Carried forward from the
+`MODULE_COMPLIANCE_LEVEL 2` declaration in the previous
+`Modules/Remote/MGHIO.remote.cmake`.
+
+## Content-link status
+
+The 3 input content-links under `test/MD5/` are already in `.cid`
+(IPFS Content Identifier) form; no `.md5` → `.cid` normalization is
+required for this module.

Modules/IO/MGHIO/include/itkMGHImageIO.h

@@ -0,0 +1,160 @@
+/*=========================================================================
+ *
+ *  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 itkMGHImageIO_h
+#define itkMGHImageIO_h
+
+#include "itkMatrix.h"
+#include "itkImageIOBase.h"
+#include <fstream>
+#include "itk_zlib.h"
+
+#include "MGHIOExport.h"
+
+namespace itk
+{
+/** \class MGHImageIO
+ *
+ * \author Hans J. Johnson
+ * \brief Class that defines how to read MGH file format.
+ * Originally developed as part of the Slicer software
+ * package under grants XXXX
+ *
+ * \ingroup IOFilters
+ * \ingroup MGHIO
+ */
+class MGHIO_EXPORT MGHImageIO : public ImageIOBase
+{
+public:
+  /** Standard class type alias. */
+  using Self = MGHImageIO;
+  using Superclass = ImageIOBase;
+  using Pointer = SmartPointer<Self>;
+
+  /** Method for creation through the object factory. */
+  itkNewMacro(Self);
+
+  /** Run-time type information (and related methods). */
+  itkOverrideGetNameOfClassMacro(MGHImageIO);
+
+  /*-------- This part of the interfaces deals with reading data. ----- */
+
+  /** Determine if the file can be read with this ImageIO implementation.
+   * \param FileNameToRead The name of the file to test for reading.
+   * \post Sets classes ImageIOBase::m_FileName variable to be FileNameToWrite
+   * \return Returns true if this ImageIO can read the file specified.
+   */
+  bool
+  CanReadFile(const char * FileNameToRead) override;
+
+  /** Set the spacing and dimension information for the set filename. */
+  void
+  ReadImageInformation() override;
+
+  /** Reads the data from disk into the memory buffer provided. */
+  void
+  Read(void * pData) override;
+
+  /*-------- This part of the interfaces deals with writing data. ----- */
+
+  /** Determine if the file can be written with this ImageIO implementation.
+   * \param FileNameToWrite The name of the file to test for writing.
+   * \post Sets classes ImageIOBase::m_FileName variable to be FileNameToWrite
+   * \return Returns true if this ImageIO can write the file specified.
+   */
+  bool
+  CanWriteFile(const char * name) override;
+
+  /** Set the spacing and dimension information for the set filename. */
+  void
+  WriteImageInformation() override;
+
+  /** Writes the data to disk from the memory buffer provided. Make sure
+   * that the IORegions has been set properly. */
+  void
+  Write(const void * buffer) override;
+
+protected:
+  MGHImageIO();
+  ~MGHImageIO() override;
+  void
+  PrintSelf(std::ostream & os, Indent indent) const override;
+
+  void
+  ReadVolumeHeader();
+
+private:
+  static const int          MRI_UCHAR = 0;
+  static const int          MRI_INT = 1;
+  static const int          MRI_FLOAT = 3;
+  static const int          MRI_SHORT = 4;
+  static const int          MRI_TENSOR = 6;
+  static const unsigned int FS_DIMENSION_HEADER_SIZE = sizeof(int) * 7;
+  static const unsigned int FS_RAS_HEADER_SIZE = (sizeof(float) * 15) + sizeof(short);
+  static const unsigned int FS_UNUSED_HEADER_SIZE = 256 - FS_RAS_HEADER_SIZE;
+  static const unsigned int FS_WHOLE_HEADER_SIZE =
+    FS_RAS_HEADER_SIZE + FS_DIMENSION_HEADER_SIZE + FS_UNUSED_HEADER_SIZE;
+
+  /** check if a filename is for a compressed file */
+  bool
+  IsCompressedFilename(const std::string fname);
+  /// processes the actual data buffer
+  void
+  SwapBytesIfNecessary(void * const buffer, const unsigned long numberOfPixels);
+
+  /// examines the direction cosines and creates encapsulation data
+  // void MriDirCos();
+
+  void
+  WriteHeader();
+
+  void
+  WriteData(const void * buffer);
+
+  void
+  PermuteFrameValues(const void * buffer, char * tempmemory);
+
+  unsigned int
+  GetComponentSize() const override;
+
+  std::string
+  GetOrientation(itk::Matrix<double> directions);
+
+  bool          m_IsCompressed;
+  gzFile        m_GZFile;
+  std::ofstream m_Output;
+
+  // Utility function to assist with writing to disk in the
+  // proper format.  TInType is static_cast<TDiskType> type.
+  template <typename TInType, typename TDiskType>
+  int
+  TWrite(const TInType inValue);
+  template <typename TDiskType, typename TOutType>
+  int
+  TRead(TOutType & outValue);
+
+  int
+  TWrite(const char * buf, const unsigned long count);
+  void
+  OpenFile();
+  void
+  CloseFile();
+};
+} // end namespace itk
+
+#endif // itkMGHImageIO_h

Modules/IO/MGHIO/include/itkMGHImageIOFactory.h

@@ -0,0 +1,74 @@
+/*=========================================================================
+ *
+ *  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 itkMGHImageIOFactory_h
+#define itkMGHImageIOFactory_h
+
+#include "itkObjectFactoryBase.h"
+#include "itkImageIOBase.h"
+
+#include "MGHIOExport.h"
+
+namespace itk
+{
+/** \class MGHImageIOFactory
+ * \brief Create instances of MGHImageIO objects using an object factory.
+ * \ingroup MGHIO
+ */
+class MGHIO_EXPORT MGHImageIOFactory : public ObjectFactoryBase
+{
+public:
+  ITK_DISALLOW_COPY_AND_MOVE(MGHImageIOFactory);
+
+  /** Standard class type alias */
+  using Self = MGHImageIOFactory;
+  using Superclass = ObjectFactoryBase;
+  using Pointer = SmartPointer<Self>;
+  using ConstPointer = SmartPointer<const Self>;
+
+  /** Class methods used to interface with the registered factories **/
+  const char *
+  GetITKSourceVersion() const override;
+
+  const char *
+  GetDescription() const override;
+
+  /** Method for class instantiation **/
+  itkFactorylessNewMacro(Self);
+
+  /** Run-time type information (and related methods). */
+  itkOverrideGetNameOfClassMacro(MGHImageIOFactory);
+
+  /** Register one factory of this type */
+  static void
+  RegisterOneFactory()
+  {
+    MGHImageIOFactory::Pointer MGHFactory = MGHImageIOFactory::New();
+
+    ObjectFactoryBase::RegisterFactoryInternal(MGHFactory);
+  }
+
+protected:
+  MGHImageIOFactory();
+  ~MGHImageIOFactory() override;
+  void
+  PrintSelf(std::ostream & os, Indent indent) const override;
+};
+} // end namespace itk
+
+#endif /// itkMGHImageIOFactory_h

Modules/IO/MGHIO/itk-module.cmake

@@ -0,0 +1,20 @@
+set(
+  DOCUMENTATION
+  "This modules contains an ImageIO class to read or write the
+  MGH file format that is an integral part of FreeSurfer based tools."
+)
+
+itk_module(
+  MGHIO
+  ENABLE_SHARED
+  DEPENDS
+    ITKIOImageBase
+    ITKZLIB
+  TEST_DEPENDS
+    ITKTestKernel
+    ITKTransform
+  EXCLUDE_FROM_DEFAULT
+  FACTORY_NAMES
+    ImageIO::MGH
+  DESCRIPTION "${DOCUMENTATION}"
+)

Modules/IO/MGHIO/src/CMakeLists.txt

@@ -0,0 +1,7 @@
+set(
+  MGHIO_SRC
+  itkMGHImageIOFactory.cxx
+  itkMGHImageIO.cxx
+)
+
+itk_module_add_library(MGHIO ${MGHIO_SRC})