diff --git a/src/Titano.Core/Analysis/WhiteBalanceSmoother.cs b/src/Titano.Core/Analysis/WhiteBalanceSmoother.cs new file mode 100644 index 00000000..293503e1 --- /dev/null +++ b/src/Titano.Core/Analysis/WhiteBalanceSmoother.cs @@ -0,0 +1,55 @@ +using Titano.Core.Imaging; +using Titano.Core.Mathematics; + +namespace Titano.Core.Analysis; + +/// Per-frame white-balance smoothing result; ratios are log2(R/G) and log2(B/G). +public sealed record WhiteBalanceResult( + ChannelGains[] Gains, + double[] RedRatio, + double[] BlueRatio, + double[] SmoothedRedRatio, + double[] SmoothedBlueRatio); + +/// +/// 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. +/// +public static class WhiteBalanceSmoother +{ + public static WhiteBalanceResult Smooth(ReadOnlySpan meanRed, ReadOnlySpan meanGreen, ReadOnlySpan 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; +} diff --git a/tests/Titano.Core.Tests/Analysis/WhiteBalanceSmootherTests.cs b/tests/Titano.Core.Tests/Analysis/WhiteBalanceSmootherTests.cs new file mode 100644 index 00000000..dad739b9 --- /dev/null +++ b/tests/Titano.Core.Tests/Analysis/WhiteBalanceSmootherTests.cs @@ -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(() => 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; + } +}