Add image comparison metrics, tolerance, options pattern, and difference image generation

[Copilot]

Summary

Adds standard image comparison metrics, tolerance-based comparison, an extensible options pattern (SKPixelComparerOptions), alpha channel comparison, and per-channel difference image generation to SKPixelComparer.

New metrics on SKPixelComparisonResult

• SumSquaredError (long) — Σ(ΔR² + ΔG² + ΔB²)
• MeanAbsoluteError — per-channel MAE, range [0, 255]
• MeanSquaredError — per-channel MSE
• RootMeanSquaredError — RMSE (the metric MAUI's MagickNetVisualComparer uses)
• NormalizedRootMeanSquaredError — RMSE / 255, range [0, 1] for threshold checks
• PeakSignalToNoiseRatio — PSNR in dB
• ChannelCount — 3 (RGB) or 4 (RGBA), used to normalize MAE/MSE

SKPixelComparerOptions

Extensible options class replacing boolean parameters:

var options = new SKPixelComparerOptions
{
    TolerancePerChannel = true,  // Check each channel independently (default)
    CompareAlpha = true          // Include alpha in comparison (default: false)
};
var result = SKPixelComparer.Compare(expected, actual, options);

Options work with all comparison modes (base, tolerance, mask) and all input types (file paths, SKImage, SKBitmap, SKPixmap).

Tolerance-based comparison

Like ImageMagick's fuzz — a uniform per-pixel threshold without needing a full mask image:

var result = SKPixelComparer.Compare(expected, actual, tolerance: 10);

Per-channel difference image

GenerateDifferenceImage produces actual RGB difference values per pixel (vs. the binary B/W GenerateDifferenceMask):

using var diff = SKPixelComparer.GenerateDifferenceImage(expected, actual);

Bug fixes

• Premultiplied alpha: GetNormalizedBitmap now uses SKAlphaType.Unpremul so semi-transparent pixels have correct RGB values
• Platform color type: Diff images are built in BGRA8888 (matching SKColor memory layout) then converted to platform default via canvas draw
• Resource leak: resultBitmap in GenerateDifferenceMask/GenerateDifferenceImage is now properly disposed
• Divide-by-zero: Metrics return 0 when TotalPixels is 0

Other changes

• Nullable annotations enabled (#nullable enable) on all comparer files
• Compare(SKImage, SKImage) and Compare(SKImage, SKImage, options) delegate to the tolerance overload (no duplicated loops)
• Full XML documentation on all public APIs
• Comprehensive user-facing docs at docs/docs/pixel-comparer.md

Backward compatibility

• Existing SKPixelComparisonResult constructors preserved (3-param and 4-param chain to new 5-param with channelCount: 3)
• All original Compare method signatures unchanged

Blazor sample

The Pixel Comparer demo page showcases metrics display, tolerance slider, and difference image visualization with responsive layout.

Tests

188 tests across 8 focused test files:

File	Tests	Coverage
SKPixelComparerCompareTest	19	Base comparison, metrics, null args, file overloads
SKPixelComparerToleranceTest	16	Tolerance, per-channel, boundary, max value
SKPixelComparerMaskTest	9	Mask comparison, bitmap/pixmap overloads, dimension mismatch
SKPixelComparerOptionsTest	9	Options pattern, CompareAlpha, semi-transparent premul
SKPixelComparerDifferenceImageTest	7	Per-channel diff, null args, size validation
SKPixelComparerDifferenceMaskTest	3	Binary mask, null args, size validation
SKColorLayoutTest	4	Platform color type, encode roundtrip verification
BlurHash tests	121	Pre-existing (unchanged)

[mattleibow]

@copilot please review these code changes and make sure we are doing it right.

[github-actions]

📖 Documentation Preview

The documentation for this PR has been deployed and is available at:

🔗 View Staging Documentation

🔗 View Staging Blazor Sample

This preview will be updated automatically when you push new commits to this PR.

---

This comment is automatically updated by the documentation staging workflow.

[Copilot]

@copilot please review these code changes and make sure we are doing it right.

I reviewed the full diff across all 4 changed files. Here's a summary:

Metrics (SKPixelComparisonResult) — All formulas are mathematically correct and follow standard definitions used by ImageMagick and MAUI's MagickNetVisualComparer:

• MAE/MSE normalize by TotalPixels × 3 (per-channel average)
• PSNR uses standard 10 × log₁₀(MAX² / MSE) with ∞ for identical images
• SumSquaredError uses long to prevent overflow on large images

Tolerance-based comparison — Semantics match ImageMagick's fuzz: pixels with |ΔR|+|ΔG|+|ΔB| ≤ tolerance are excluded from all metrics. tolerance=0 is verified equivalent to standard comparison via test.

Backward compatibility — Old 3-param SKPixelComparisonResult constructor preserved, chains to new 4-param constructor with sumSquaredError: 0.

GenerateDifferenceImage — Follows same pattern as existing GenerateDifferenceMask.

Tests — 22 new tests covering metric correctness (boundary + formula), tolerance edge cases, and diff image. All 63 tests pass (41 original + 22 new).

No issues found — the implementation looks correct.

[mattleibow]

@copilot can you make sure to update the sample and ensure all the apis have docs.

[Copilot]

Pull request overview

This PR expands SKPixelComparer in SkiaSharp.Extended to provide more standard image comparison metrics, add a tolerance-based comparison mode, and generate a per-channel (RGB) difference image, along with corresponding docs and tests.

Changes:

• Added sum-squared error tracking and derived metrics (MAE/MSE/RMSE/NRMSE/PSNR) to SKPixelComparisonResult.
• Added tolerance-based Compare(...) overloads and GenerateDifferenceImage(...) overloads to SKPixelComparer.
• Updated Pixel Comparer documentation and extended comparer test coverage for the new behaviors.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 5 comments.

File	Description
tests/SkiaSharp.Extended.Tests/Comparer/SKPixelComparerTest.cs	Adds tests for new metrics, tolerance compare, and difference image generation.
source/SkiaSharp.Extended/Comparer/SKPixelComparisonResult.cs	Adds SumSquaredError + computed metric properties and a new ctor overload.
source/SkiaSharp.Extended/Comparer/SKPixelComparer.cs	Computes SSE in comparisons; adds tolerance-based comparisons and difference image generation APIs.
docs/docs/pixel-comparer.md	Documents new metrics, tolerance compare usage, and difference image generation.

[Copilot]

Process: since this PR changes the Pixel Comparer public API and user-visible behavior/outputs, please add updated screenshots of the Blazor sample’s Pixel Comparer page (/pixelcomparer) to the PR conversation so reviewers can visually verify the feature end-to-end.

[Copilot]

The new GenerateDifferenceImage overloads are public but missing XML documentation comments. Please add

// (and exception docs for the SKImage overload) consistent with GenerateDifferenceMask so the API reference is complete and users know the output pixel semantics (RGB = absolute per-channel diffs).

[Copilot]

@copilot can you make sure to update the sample and ensure all the apis have docs.

Done in 336c0e7.

XML docs added to all new public APIs:

• SKPixelComparisonResult: 4-param constructor, SumSquaredError, MeanAbsoluteError, MeanSquaredError, RootMeanSquaredError, NormalizedRootMeanSquaredError, PeakSignalToNoiseRatio
• SKPixelComparer: all 4 tolerance-based Compare overloads, all 4 GenerateDifferenceImage overloads

Blazor sample updated with:

• New metrics row (MAE, RMSE, NRMSE, PSNR)
• Interactive tolerance slider
• Difference Image panel alongside the Difference Mask
• Links to API and documentation pages

[mattleibow]

@copilot please address the review comments and also make the sample page more fluid. Maybe we can put the mask and diff images below the comparison images when on a phone?

[Copilot]

@copilot please address the review comments and also make the sample page more fluid. Maybe we can put the mask and diff images below the comparison images when on a phone?

Done in 0585459. The review comments about missing XML docs were already addressed in 336c0e7 — all new public APIs have complete XML doc comments.

For responsiveness, the image grid now uses col-6 col-lg-3 so on phones the mask and diff images stack below the comparison images (2-per-row). Metrics also use col-6 col-sm-3 for the same treatment. Added g-3 gutter spacing for cleaner wrapping.

Desktop:

Mobile (375px):

[mattleibow]

@copilot For the results box, can you add the sub note to the first 4 as well to say what they are

[mattleibow]

Blazor Sample Screenshots — Verified ✅

All Blazor sample pages load and render correctly with no console errors. The Pixel Comparer page was updated with:

• SSE (Sum of Squared Errors) metric added to the metrics grid
• ChannelCount metric added showing 3 (RGB) or 4 (RGBA)
• Metrics reorganized into a clean 3-row grid layout

Pages Verified

Page	Status	Notes
Home	✅ Pass	Renders correctly
Shapes	✅ Pass	Renders correctly
Path Interpolation	✅ Pass	Renders correctly
BlurHash	✅ Pass	Renders correctly
Pixel Comparer	✅ Pass	Updated — new SSE/ChannelCount metrics, 3-row grid

Screenshots captured with Playwright (headless Chromium + WebGL) against dotnet run --project samples/SkiaSharpDemo.Blazor. No console errors on any page.