feat(analysis): add white-balance smoother

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_012iLMBNwBE2GnphAsu4cjaC
This commit is contained in:
Claude committed 2026-10-02 09:51:43 +00:00
1 parent f6adbf7a31
commit a50ad7deb0
2 files changed
+126

No files matched your search

@@ -0,0 +1,55 @@
using Titano.Core.Imaging;
using Titano.Core.Mathematics;
namespace Titano.Core.Analysis;
/// <summary>Per-frame white-balance smoothing result; ratios are log2(R/G) and log2(B/G).</summary>
public sealed record WhiteBalanceResult(
ChannelGains[] Gains,
double[] RedRatio,
double[] BlueRatio,
double[] SmoothedRedRatio,
double[] SmoothedBlueRatio);
/// <summary>
/// White-balance smoothing (BRIEF §11.2): the channel ratios log2(R/G) and log2(B/G) of each frame's mean colour are
/// smoothed with robust LOWESS, and each frame gets the channel gains that move its ratios onto the smoothed ones.
/// Gains are normalised so the Rec.709 luminance of the frame's mean colour is unchanged (WB never alters exposure).
/// Frames with a non-positive channel mean get identity gains.
/// </summary>
public static class WhiteBalanceSmoother
{
public static WhiteBalanceResult Smooth(ReadOnlySpan<double> meanRed, ReadOnlySpan<double> meanGreen, ReadOnlySpan<double> meanBlue, int window = 31, int robustIterations = 2)
{
var n = meanRed.Length;
if (meanGreen.Length != n || meanBlue.Length != n) throw new ArgumentException("Channel series lengths differ.", nameof(meanGreen));
var red = new double[n];
var blue = new double[n];
for (var i = 0; i < n; i++)
{
var valid = meanRed[i] > 0 && meanGreen[i] > 0 && meanBlue[i] > 0 && double.IsFinite(meanRed[i] + meanGreen[i] + meanBlue[i]);
red[i] = valid ? Math.Log2(meanRed[i] / meanGreen[i]) : double.NaN;
blue[i] = valid ? Math.Log2(meanBlue[i] / meanGreen[i]) : double.NaN;
}
var smoothRed = LocalRegression.Smooth(red, window, 1, robustIterations).Fitted;
var smoothBlue = LocalRegression.Smooth(blue, window, 1, robustIterations).Fitted;
var gains = new ChannelGains[n];
for (var i = 0; i < n; i++)
{
if (double.IsNaN(red[i]))
{
gains[i] = ChannelGains.Identity;
continue;
}
var gr = Math.Pow(2, smoothRed[i] - red[i]);
var gb = Math.Pow(2, smoothBlue[i] - blue[i]);
double r = meanRed[i], g = meanGreen[i], b = meanBlue[i];
var k = Luma(r, g, b) / Luma(gr * r, g, gb * b);
gains[i] = new ChannelGains(k * gr, k, k * gb);
}
return new WhiteBalanceResult(gains, red, blue, smoothRed, smoothBlue);
}
private static double Luma(double r, double g, double b) => ColorSpace.LumaR * r + ColorSpace.LumaG * g + ColorSpace.LumaB * b;
}
@@ -0,0 +1,71 @@
using System.Globalization;
using Titano.Core.Analysis;
using Titano.Core.Diagnostics.Synthetic;
using Titano.Testing;
namespace Titano.Core.Tests.Analysis;
public sealed class WhiteBalanceSmootherTests(TestContext context)
{
[Test]
public void RemovesJitterAndKeepsTheDrift()
{
var sequence = SyntheticSequence.Create(new SyntheticSequenceOptions
{
Width = 48,
Height = 32,
FrameCount = 150,
Seed = 21,
StartKelvin = 3500,
EndKelvin = 6500,
WhiteBalanceJitter = 0.08,
FlickerEv = 0.05,
});
var stats = Measure(sequence, null);
var result = WhiteBalanceSmoother.Smooth(stats.Select(s => s.MeanRed).ToArray(), stats.Select(s => s.MeanGreen).ToArray(), stats.Select(s => s.MeanBlue).ToArray());
var corrected = Measure(sequence, result.Gains);
// Truth: the ratio of the drifting light without jitter.
var truthRed = new double[sequence.Count];
var truthBlue = new double[sequence.Count];
for (var i = 0; i < sequence.Count; i++)
{
var rgb = ColorTemperature.PlanckianRgb(sequence.Kelvin[i]);
truthRed[i] = Math.Log2(rgb.X / rgb.Y);
truthBlue[i] = Math.Log2(rgb.Z / rgb.Y);
}
var before = AnalysisFixtures.FrameToFrameResidualRms(result.RedRatio, truthRed);
var after = AnalysisFixtures.FrameToFrameResidualRms(corrected.Select(s => Math.Log2(s.MeanRed / s.MeanGreen)).ToArray(), truthRed);
var afterBlue = AnalysisFixtures.FrameToFrameResidualRms(corrected.Select(s => Math.Log2(s.MeanBlue / s.MeanGreen)).ToArray(), truthBlue);
var drift = AnalysisFixtures.MaxDeviation(result.SmoothedBlueRatio, truthBlue);
context.Log(string.Create(CultureInfo.InvariantCulture, $"R/G jitter before {before:F4}, after {after:F4}; B/G after {afterBlue:F4}; drift deviation {drift:F4}"));
Assert.Less(after, 0.2 * before);
Assert.Less(afterBlue, 0.2 * before);
Assert.Less(drift, 0.03);
// Gains never change exposure.
for (var i = 0; i < sequence.Count; i++)
Assert.Approximately(stats[i].MeanLogLuminance, corrected[i].MeanLogLuminance, 0.01);
}
[Test]
public void InvalidFramesGetIdentityGains()
{
var result = WhiteBalanceSmoother.Smooth([0.5, 0, 0.5, 0.5], [0.5, 0, 0.5, 0.5], [0.5, 0, 0.5, 0.5], window: 3);
Assert.Equal(ChannelGains.Identity, result.Gains[1]);
Assert.Approximately(1, result.Gains[0].Red, 1e-12);
Assert.Throws<ArgumentException>(() => WhiteBalanceSmoother.Smooth([1.0], [1.0, 2.0], [1.0]));
}
private static FrameStatistics[] Measure(SyntheticSequence sequence, ChannelGains[]? gains)
{
var stats = new FrameStatistics[sequence.Count];
Parallel.For(0, sequence.Count, new ParallelOptions { MaxDegreeOfParallelism = 2 }, i =>
{
using var image = sequence.Render(i);
if (gains is not null) ExposureProcessor.Apply(image, 0, gains[i]);
stats[i] = FrameStatistics.Measure(image);
});
return stats;
}
}