ENH: Add StructuralSimilarity Beta module (SSIM image filter) — stacked on #6085

[hjmjohnson]

Adds Modules/Beta/StructuralSimilarity/ containing StructuralSimilarityImageFilter (SSIM, Wang et al. 2004). Stacked on #6085 — relocating out of Modules/Filtering/ImageCompare/ into the new Modules/Beta/ container so the API can stabilize before promotion to a core module. Merge #6085 first; this PR's base is still main only because GitHub won't accept a base branch from a fork.

What changed vs. the previous revision of this PR

Previous revision placed the filter in Modules/Filtering/ImageCompare/ and touched that module's itk-module.cmake (adding ITKSmoothing / ITKGoogleTest deps). That perturbed a core module's dependency surface for a brand-new filter whose API has not yet been exercised by downstream users.

This revision:

• Moves all SSIM files into a self-contained Modules/Beta/StructuralSimilarity/ module
• Leaves Modules/Filtering/ImageCompare/ completely untouched
• Adds a Modules/Beta/StructuralSimilarity.beta.cmake provenance manifest
• Renames \ingroup ITKImageCompare → \ingroup StructuralSimilarity in the header
• Unchanged: filter implementation (.h/.hxx), GoogleTest suite, Python .wrap

Module layout

Modules/Beta/
├── StructuralSimilarity.beta.cmake         # provenance manifest
└── StructuralSimilarity/
    ├── itk-module.cmake                    # DEPENDS ITKImageIntensity
    │                                       # COMPILE_DEPENDS ITKImageFilterBase, ITKSmoothing
    │                                       # TEST_DEPENDS ITKTestKernel, ITKGoogleTest
    ├── CMakeLists.txt
    ├── include/
    │   ├── itkStructuralSimilarityImageFilter.h
    │   └── itkStructuralSimilarityImageFilter.hxx
    ├── test/
    │   ├── CMakeLists.txt                  # creategoogletestdriver
    │   └── itkStructuralSimilarityImageFilterGTest.cxx
    └── wrapping/
        ├── CMakeLists.txt
        └── itkStructuralSimilarityImageFilter.wrap   # WRAP_ITK_REAL, 2D

[greptile-apps]

Greptile Summary

This PR adds a new StructuralSimilarityImageFilter implementing the Wang et al. 2004 SSIM metric as an N-dimensional, multi-threaded composite ITK filter. The implementation is thorough: five internal DiscreteGaussianImageFilter passes feed a parallelized per-pixel combination stage, with mean SSIM averaged over the cropped interior region matching the scikit-image/MATLAB reference. All 30 GTests pass locally. Two minor correctness edge-cases are worth noting before merge.

Confidence Score: 5/5

Safe to merge; all findings are P2 style/edge-case suggestions that do not affect the default use case.

The algorithm is correct for the default configuration (σ=1.5, 11×11 kernel, K1=0.01, K2=0.03, L from NumericTraits). The two flagged gaps — border-crop formula for even kernel widths, and no guard against K1/K2=0 NaN — are P2 edge cases that do not affect any of the 30 passing tests or the documented API. The test coverage is comprehensive and the implementation closely follows Wang 2004 and scikit-image.

itkStructuralSimilarityImageFilter.hxx lines 106–122 (K1/K2 validation) and line 240 (border-crop formula).

Important Files Changed

Filename	Overview
Modules/Filtering/ImageCompare/include/itkStructuralSimilarityImageFilter.h	Public API and class declaration; well-structured with standard ITK macros. Documentation note: header comment still says "BeforeGenerate" though validation is in VerifyPreconditions (flagged in previous thread).
Modules/Filtering/ImageCompare/include/itkStructuralSimilarityImageFilter.hxx	Core implementation; simplified and general SSIM paths are correct. Two edge-case gaps: K1/K2=0 produces silent NaN for constant/zero-mean inputs, and the border-crop formula diverges from scikit-image for even MaximumKernelWidth values.
Modules/Filtering/ImageCompare/test/itkStructuralSimilarityImageFilterGTest.cxx	30 GTest cases covering identities, analytic constant-image checks, input validation, qualitative properties, scikit-image cross-checks, code-path equivalence, and multi-dimensional/pixel-type coverage. Well-designed and comprehensive.
Modules/Filtering/ImageCompare/itk-module.cmake	Adds ITKSmoothing as COMPILE_DEPENDS (correct for template-only dependency) and ITKGoogleTest as TEST_DEPENDS. No issues.
Modules/Filtering/ImageCompare/test/CMakeLists.txt	Adds creategoogletestdriver for the new GTest file; GTest auto-discovery handles CTest registration, confirmed by author's ctest run showing 30 tests.
Modules/Filtering/ImageCompare/wrapping/itkStructuralSimilarityImageFilter.wrap	Wraps for WRAP_ITK_REAL (float/double) in 2D, consistent with SimilarityIndexImageFilter's wrapping pattern. Appropriate starting point.

_{Reviews (3): Last reviewed commit: "ENH: Add StructuralSimilarityImageFilter..." | Re-trigger Greptile}

[hjmjohnson]

The lone failing check (ITK.Linux on Azure DevOps build 15505) appears to be a pipeline-side flake rather than a real build/test issue:

• ✅ CDash reports "All builds completed successfully" for SHA 46fabd3525 — meaning the same Linux ITK build that Azure ran successfully completed, ran its tests, and submitted the green results to CDash.
• ✅ Every other Linux build passes:
  • Pixi-Cxx (ubuntu-22.04) ✓
  • ARMBUILD-Ubuntu-24.04-arm ✓
  • ARMBUILD-x86_64-rosetta ✓ (macOS but same toolchain class)
• ✅ Every other Azure pipeline passes:
  • ITK.Windows ✓
  • ITK.macOS ✓
  • ITK.Linux.Python ✓
  • ITK.macOS.Python ✓
• ✅ The 30 new SSIM GTests run and pass on ARMBUILD-Python (verified in the run log: tests FindPython3.cmake unavailable before CMake 3.12 #1700–Add lambda function command #1735 all Passed).

The pattern (lone Azure pipeline failing, CDash green, all duplicate-coverage Linux builds green) almost always means the failure is in a post-CTest infrastructure step in the Azure pipeline (cache save, artifact upload, agent cleanup), not in the build itself. Re-triggering.

[hjmjohnson]

/azp run ITK.Linux

[blowekamp]

Some comment on pipeline management details.

The implementation this feeling is going to be rather memory intensive with the number of image converted and processed to real type.

Is this a 2D only implementation?

[hjmjohnson]

Updated diagnosis: the ITK.Linux failure was a real one in the legacy-removed Linux build (the Azure pipeline runs both a normal and an ITK_LEGACY_REMOVE=ON configuration; the normal one was green on CDash, hence the misleading "all builds completed successfully" CDash summary, but the legacy-removed one promoted a deprecation warning into an error).

The root cause:

itkStructuralSimilarityImageFilter.hxx:342:87:
warning: 'itk::ImageConstIterator<TImage>::IndexType
itk::ImageConstIterator<TImage>::GetIndex() const' is deprecated:
Please use ComputeIndex() instead, or use an iterator with index,
like ImageIteratorWithIndex! [-Wdeprecated-declarations]

  342 |   if (subInterior.GetNumberOfPixels() > 0 && subInterior.IsInside(outIt.GetIndex()))

The output iterator was a plain ImageRegionIterator, and the per-pixel loop called outIt.GetIndex() to test interior-region membership for the mean accumulator. GetIndex() on the index-less iterator is wrapped in #ifndef ITK_FUTURE_LEGACY_REMOVE (Modules/Core/Common/include/itkImageConstIterator.h:306-317) and emits a deprecation warning under ITK_LEGACY_REMOVE. CI promotes that warning to an error.

Fix (commit f4316869e7): switch the output iterator to ImageRegionIteratorWithIndex, which tracks the index natively and exposes a non-deprecated GetIndex(). One-line change: replace the using OutputIteratorType = ImageRegionIterator<OutputImageType> typedef and add the corresponding header include.

Local verification:

$ cmake -B build-ssim-legacy -S . -G Ninja \
       -DITK_LEGACY_REMOVE=ON -DITK_LEGACY_SILENT=OFF ...
$ cmake --build build-ssim-legacy -j 4 \
       --target ITKImageCompareHeaderTest1 ITKImageCompareGTestDriver
[1/4] Building CXX object .../ITKImageCompareHeaderTest1.dir/test/ITKImageCompareHeaderTest1.cxx.o
[2/4] Linking CXX executable bin/ITKImageCompareHeaderTest1
[3/4] Building CXX object .../itkStructuralSimilarityImageFilterGTest.cxx.o
[4/4] Linking CXX executable bin/ITKImageCompareGTestDriver

No deprecation warnings, clean build.

$ ./bin/ITKImageCompareGTestDriver --gtest_filter='StructuralSimilarityImageFilter.*'
[==========] 30 tests from 1 test suite ran. (333 ms total)
[  PASSED  ] 30 tests.

All 30 SSIM GTests still pass under the legacy-removed build with the new iterator.

[hjmjohnson]

@greptileai review this draft before I make it official

[hjmjohnson]

Superseded by #6094, which places the SSIM filter as a standalone module at Modules/Filtering/StructuralSimilarity/ based directly on upstream/main — no dependency on the rejected Modules/Beta/ approach (#6085). All reviewer feedback from this PR has been incorporated.