ENH: Add StructuralSimilarityImageFilter at Modules/Filtering

[hjmjohnson]

Adds Modules/Filtering/StructuralSimilarity/ containing StructuralSimilarityImageFilter (SSIM, Wang et al. 2004). Standalone module under Filtering — does not touch ImageCompare or any other existing module. Enabled in CI via configure-ci. Supersedes #6034 (which was stacked on the now-rejected Modules/Beta/ approach in #6085).

What changed from PR #6034

• Previous: SSIM lived at Modules/Beta/StructuralSimilarity/, stacked on ENH: Add Modules/Beta/ container (infra-only for stacked beta-module ingests) #6085 (Modules/Beta/ container, rejected by reviewers)
• Now: Standalone module at Modules/Filtering/StructuralSimilarity/, based directly on upstream/main. No dependency on ENH: Add Modules/Beta/ container (infra-only for stacked beta-module ingests) #6085 or WIP: ENH: Ingest 10 beta modules inline under Modules/Beta/ (stacked on #6085) #6086.
• Module contents unchanged: same filter implementation, same GoogleTest suite, same Python wrapping
• Added -DModule_StructuralSimilarity:BOOL=ON to configure-ci in pyproject.toml

Module layout

Modules/Filtering/StructuralSimilarity/
├── CMakeLists.txt
├── itk-module.cmake          # DEPENDS      ITKImageFilterBase, ITKImageIntensity, ITKSmoothing
│                              # TEST_DEPENDS ITKTestKernel, ITKGoogleTest
├── include/
│   ├── itkStructuralSimilarityImageFilter.h
│   └── itkStructuralSimilarityImageFilter.hxx
├── test/
│   ├── CMakeLists.txt
│   └── itkStructuralSimilarityImageFilterGTest.cxx   # 31 GTest cases
└── wrapping/
    ├── CMakeLists.txt
    └── itkStructuralSimilarityImageFilter.wrap

Local verification

• Configure: clean
• Build: no errors, no warnings
• Tests: 33/33 pass
• Pre-commit: all hooks pass

Reviewer feedback addressed

From #6034:

• @blowekamp: VerifyPreconditions override (moved all param/input checks there)
• @blowekamp: Mini-pipeline reconnection using CompositeFilterExample pattern
• @blowekamp: Standalone module — does not perturb ImageCompare's dependency surface
• @thewtex: No Beta staging — direct integration into Filtering/

From #6094:

• @N-Dekker: Initialize m_ScaleWeights via the Array(SizeValueType, const ValueType &) ctor directly in the header NSDMI; collapse declare-then-Fill patterns in tests to ImageType::SizeType::Filled(size); use CTAD on iterators and drop redundant GoToBegin().
• Greptile (P1): Added m_MaximumKernelWidth == 0 guard in VerifyPreconditions() plus a new ZeroMaximumKernelWidth_Throws test case.
• Greptile (P2): Hoisted subInterior.GetNumberOfPixels() > 0 out of the per-pixel inner loop into const bool subInteriorIsNonEmpty.
• Greptile (P2): Promoted ITKImageFilterBase and ITKSmoothing from COMPILE_DEPENDS to DEPENDS (parallel to the fix in COMP: Fix COMPILE_DEPENDS → DEPENDS in three Filtering module declara… #6097).

AI assistance

• Tool: Claude Code (claude-opus-4-7)
• Role: filter design, GoogleTest suite generation, reviewer-feedback fixups
• Contribution:
  • SSIM mini-pipeline (five-Gaussian composite filter, per-pixel parallelized SSIM combination, interior-region mean accumulation)
  • 31-case GoogleTest suite (identities, analytic closed-form checks, error-throw paths, N-D and multi-pixel-type variants, scikit-image cross-validation)
  • Review-pass fixups: N-Dekker style cleanups (Array(SizeValueType, const ValueType &) ctor, ::Filled(size), iterator CTAD); Greptile P1 MaximumKernelWidth == 0 guard + regression test; Greptile P2 loop-invariant hoisting; COMPILE_DEPENDS → DEPENDS alignment with COMP: Fix COMPILE_DEPENDS → DEPENDS in three Filtering module declara… #6097
• All code was reviewed locally, built without warnings, and validated against the 33-test suite before each commit

[greptile-apps]

Greptile Summary

This PR adds a new StructuralSimilarityImageFilter module at Modules/Filtering/StructuralSimilarity/ implementing the Wang et al. 2004 SSIM metric as an N-dimensional, multi-threaded ITK filter. The SSIM formula (both simplified and general exponent paths), the Gaussian mini-pipeline, and the interior-region mean accumulation are all mathematically correct and well tested across 30 GTest cases.

• P1 – VerifyPreconditions() validates sigma and dynamic-range but not m_MaximumKernelWidth; a zero value would silently produce a degenerate Gaussian kernel.
• P2 – ITKSmoothing and ITKImageFilterBase are declared COMPILE_DEPENDS, but GenerateData() instantiates and updates filters from both modules at runtime, which may require them to be DEPENDS for correct downstream linking.

Confidence Score: 4/5

Safe to merge after addressing the missing MaximumKernelWidth>0 guard; remaining findings are P2 dependency and style concerns.

One P1 finding exists: VerifyPreconditions() does not reject MaximumKernelWidth==0, which would silently produce a degenerate Gaussian. All other findings (dependency classification, inner-loop micro-optimisation, wrapping coverage) are P2. The algorithm itself is mathematically sound and thoroughly tested.

itkStructuralSimilarityImageFilter.hxx (missing kernel-width guard) and itk-module.cmake (COMPILE_DEPENDS vs DEPENDS classification for ITKSmoothing / ITKImageFilterBase).

Important Files Changed

Filename	Overview
Modules/Filtering/StructuralSimilarity/include/itkStructuralSimilarityImageFilter.h	Adds the SSIM filter header; well-structured ITK class with clean type aliases, itkSetMacro/itkGetConstMacro accessors, and proper concept check for numeric traits.
Modules/Filtering/StructuralSimilarity/include/itkStructuralSimilarityImageFilter.hxx	Implements SSIM via a five-Gaussian mini-pipeline; algorithm is mathematically correct but VerifyPreconditions() misses a MaximumKernelWidth==0 guard, and subInterior.GetNumberOfPixels() is re-evaluated every inner-loop iteration.
Modules/Filtering/StructuralSimilarity/itk-module.cmake	Module descriptor compiles cleanly but classifies ITKSmoothing and ITKImageFilterBase as COMPILE_DEPENDS when they are instantiated at runtime inside GenerateData(), which may require them to be DEPENDS for correct downstream linking.
Modules/Filtering/StructuralSimilarity/test/itkStructuralSimilarityImageFilterGTest.cxx	Comprehensive 30-case GTest suite covering identities, analytic closed-form checks, error-throw paths, multi-dimensional support, pixel-type variants, and cross-validation against scikit-image reference values.
Modules/Filtering/StructuralSimilarity/wrapping/itkStructuralSimilarityImageFilter.wrap	Wraps WRAP_ITK_REAL types with 2 template parameters, producing only same-type pairs; missing the (double→float) combination that matches the C++ default output type.
pyproject.toml	Adds -DModule_StructuralSimilarity:BOOL=ON to the configure-ci task; correctly scoped to the CI preset without altering the default configure task.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A["Input1: TInputImage"] --> C1["Cast to RealImage x"]
    B["Input2: TInputImage"] --> C2["Cast to RealImage y"]
    C1 --> G_x["Gaussian → mu_x"]
    C2 --> G_y["Gaussian → mu_y"]
    C1 --> MXX["x times x"]
    C2 --> MYY["y times y"]
    C1 --> MXY["x times y"]
    C2 --> MXY
    MXX --> G_xx["Gaussian → E_xx"]
    MYY --> G_yy["Gaussian → E_yy"]
    MXY --> G_xy["Gaussian → E_xy"]
    G_x --> COMBINE["Per-pixel SSIM combination\nParallelizeImageRegion\nvar_x = E_xx - mu_x^2\nvar_y = E_yy - mu_y^2\ncov_xy = E_xy - mu_x*mu_y"]
    G_y --> COMBINE
    G_xx --> COMBINE
    G_yy --> COMBINE
    G_xy --> COMBINE
    COMBINE --> OUT["Output SSIM map"]
    COMBINE --> MEAN["m_MeanSSIM over interior region"]

Loading

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

[blowekamp]

Looks OK after my looks.