nx_ssim.nx

nx_ssim.nx -- Structural Similarity (SSIM) metric, Wang 2004. Closes the per-pixel fidelity half of action item #6 in docs/VRAM_OPTIMIZATION_REALISTIC_TRACKING.md ("quality measurement protocol -- LPIPS + CLIP-similarity primitives"). SSIM is the substrate-native canonical metric the literature uses to say "the quantized output matches the f16 reference." PER THE BITS-UP CARDINAL: this primitive composes against the canonical `*Image` type from nx_image.nx -- the same type used by nx_scale (gauss pyramid), nx_aesthetics, nx_self_similarity, etc. MS-SSIM in nx_ms_ssim.nx then composes nx_scale_pyramid_down with this kernel rather than reinventing downsample inline. Why not LPIPS directly: canonical LPIPS uses trained VGG/AlexNet features (Zhang et al. 2018). Substrate has no trained vision network yet (gated on autodiff or pretrained-weight loader). SSIM is the pre-LPIPS canonical metric -- pure algorithmic, well- calibrated against human judgment for fidelity-class comparisons (Wang & Bovik 2009 _Mean Squared Error: Love It or Leave It?_), and the standard for the kind of A/B-bench we actually need (does q4_K weight quantization change the rendered pixels significantly vs f16 reference?). ===== Math ======================================================= For two images X, Y and a window W centred at (i, j): μ_x = mean of W over X μ_y = mean of W over Y σ_x² = variance of W over X σ_y² = variance of W over Y σ_xy = covariance of W over X and Y Stability constants for 8-bit dynamic range L = 255: C1 = (0.01 * L)^2 = 6.5025 C2 = (0.03 * L)^2 = 58.5225 Local SSIM: SSIM(i, j) = (2 μ_x μ_y + C1) (2 σ_xy + C2)