Skip to content

Add debug visualization for dynamic predictor selection #7

Description

@jotoft

Summary

Add a debug overlay option to visualize which predictor (average vs MED) was selected for each scanline when using Dynamic mode.

Motivation

When debugging or analyzing compression behavior, it's useful to see which predictor was chosen for each scanline. This helps understand:

  • Why certain images compress better with dynamic mode
  • How image content (edges, gradients, textures) affects predictor selection
  • Verify correct implementation against C++ reference

Technical Details

Predictor Bitmap Storage

The dynamic predictor selection is stored as a compact bitmap:

  • 1 bit per scanline
  • Bit = 0: Average predictor (left + top) / 2
  • Bit = 1: MED predictor (JPEG-LS) median(left, top, left + top - topleft)
  • Stored at start of compressed data, aligned to 4 bytes: ((height + 7) / 8 + 3) & ~3

Where It Applies

Compression Type Dynamic Applies To
Entropy-coded lossless Image scanlines (height rows)
Tile-based (lossless/lossy) Header scanlines ((height/4)*2 rows for min+dist streams)

Visualization Options

  1. Scanline highlight overlay: Color-code each row based on predictor used

    • Blue = Average predictor
    • Orange = MED predictor
  2. Side panel indicator: Vertical strip showing predictor choice per row

  3. Statistics display: Show percentage of rows using each predictor

Implementation Suggestions

1. Expose predictor bitmap from decompression

pub struct DecompressResult {
    pub quality: Quality,
    pub mode: Mode,
    pub predictor_bitmap: Option<Vec<u8>>,  // Only present for Dynamic mode
}

2. Add visualization function

/// Generate a visualization overlay showing predictor selection.
/// Returns RGBA image where each row is colored by predictor choice.
pub fn visualize_predictor_selection(
    predictor_bitmap: &[u8],
    width: usize,
    height: usize,
) -> Vec<u8> {
    // ...
}

3. Demo UI integration

Add checkbox in Debug Overlay section:

  • Show Predictor Selection (only enabled when mode=Dynamic)

Complexity

Easy - Once #5 (Dynamic mode) is implemented, this is straightforward visualization.

Related

Metadata

Metadata

Assignees

No one assigned

    Labels

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions