Struct DiffmapResult 

#[non_exhaustive]
pub struct DiffmapResult { /* private fields */ }

Result containing both a zensim score and a per-pixel error map.

The diffmap is a multi-scale spatial error map using modified SSIM across all three XYB channels. SSIM error maps are computed at each pyramid scale (4 scales by default), then coarser scales are upsampled to full resolution and blended with the profile’s trained scale weights. This captures both fine-grained detail loss (scale 0) and structural/low-frequency distortions (scales 1-3).

It tells you WHERE perceptual error is concentrated, while the zensim score tells you HOW MUCH total error there is.

Diffmap signal

Each value is a weighted blend of per-scale SSIM errors:

per_channel_s = (1 − mean_term × structure_term).max(0)   [at scale s]
  mean_term      = 1 − (μ_src − μ_dst)²
  structure_term  = (2·σ_src_dst + C₂) / (σ²_src + σ²_dst + C₂)
  C₂ = 0.0009

scale_error_s[i] = Σ_c w_c_s × per_channel_s_c   (channel-weighted)
diffmap[i] = Σ_s blend_s × upsample(scale_error_s)[i]   (scale-blended)

With trained weights: scale 0 gets ~6%, scales 1-3 get ~28-35% each (matching the trained model’s emphasis on structural features).

• Range: [0, +∞). Zero means perceptually identical at that location. Values above ~0.5 indicate severe local distortion. On typical photo pairs, most values fall in [0, 0.3].
• Spatial smoothing: scale 0 reflects 11×11 neighborhoods, coarser scales reflect progressively larger areas (22×22, 44×44, 88×88).
• Color space: computed in XYB (perceptual luma + chroma). Channel combination weights are controlled by DiffmapWeighting.
• Not butteraugli distance: the values are unitless SSIM error, not butteraugli distance units. Use the global zensim score for overall quality.

Layout

Row-major, width × height elements: diffmap[y * width + x]. No padding — actual image dimensions, not SIMD-padded.

Implementations

impl DiffmapResult

pub fn result(&self) -> &ZensimResult

The full zensim comparison result (score, features, etc.).

pub fn score(&self) -> f64

The zensim score (convenience shorthand for result().score()).

pub fn diffmap(&self) -> &[f32]

Per-pixel perceptual error map. See DiffmapResult for signal definition, range, and layout.

pub fn into_parts(self) -> (ZensimResult, Vec<f32>, usize, usize)

Consume this result and return the diffmap as an owned Vec<f32>, along with the zensim result and dimensions.

pub fn width(&self) -> usize

Image width (actual, not SIMD-padded).

pub fn height(&self) -> usize

Image height.