diff --git a/src/Titano.Core/Analysis/DeflickerEngine.cs b/src/Titano.Core/Analysis/DeflickerEngine.cs new file mode 100644 index 00000000..634dff88 --- /dev/null +++ b/src/Titano.Core/Analysis/DeflickerEngine.cs @@ -0,0 +1,130 @@ +using Titano.Core.Mathematics; + +namespace Titano.Core.Analysis; + +/// Parameters of . +public sealed record DeflickerOptions +{ + public static DeflickerOptions Default { get; } = new(); + + /// Frames in each local fit (see for a recommendation). + public int Window { get; init; } = 21; + + /// Local polynomial degree, 1 or 2. + public int Degree { get; init; } = 1; + + /// Tukey reweighting passes. + public int RobustIterations { get; init; } = 3; + + /// 1 lands every frame on the fitted curve; lower values let trusted frames keep part of their own deviation. + public double Strength { get; init; } = 1; +} + +/// Flicker before and after correction, in EV. +/// RMS frame-to-frame step of the input relative to the fitted curve. +/// The same measure on the target curve. +/// RMS of input minus fitted curve over valid frames. +/// Frames whose robust weight fell below ½. +public sealed record DeflickerDiagnostics(double FlickerBefore, double FlickerAfter, double ResidualRms, int OutlierCount); + +/// Per-frame deflicker result; arrays have one entry per frame. +public sealed record DeflickerResult( + double[] Target, + double[] CorrectionEv, + double[] Fitted, + double[] RobustWeights, + double[] SurvivingFraction, + DeflickerDiagnostics Diagnostics); + +/// +/// Deflicker target curve (BRIEF §11.2): robust LOWESS () of per-frame log2 luminance +/// after removing intentional exposure offsets, then blended per frame. A frame keeps +/// (1 − Strength)·ρ·S of its deviation from the fit, where ρ is its own Tukey weight and S the surviving fraction of +/// its window, so outliers and frames in contaminated windows are pulled fully onto the fit. Corrections are +/// target − measured, in EV. +/// +public static class DeflickerEngine +{ + /// Measured log2 luminance per frame (NaN = unusable frame, corrected by 0). + /// Optional luminance change in EV caused on purpose (e.g. exposure steps); + /// it is removed before fitting and restored in the target so it is never treated as flicker. + public static DeflickerResult Compute(ReadOnlySpan logLuminance, DeflickerOptions? options = null, ReadOnlySpan intentionalOffsets = default) + { + options ??= DeflickerOptions.Default; + if (!(options.Strength >= 0 && options.Strength <= 1)) throw new ArgumentOutOfRangeException(nameof(options), "Strength must lie in [0, 1]."); + var n = logLuminance.Length; + if (!intentionalOffsets.IsEmpty && intentionalOffsets.Length != n) throw new ArgumentException("Offsets must have one value per frame.", nameof(intentionalOffsets)); + + var flat = new double[n]; + for (var i = 0; i < n; i++) flat[i] = logLuminance[i] - Offset(intentionalOffsets, i); + var fit = LocalRegression.Smooth(flat, options.Window, options.Degree, options.RobustIterations); + + var target = new double[n]; + var correction = new double[n]; + var keepScale = 1 - options.Strength; + for (var i = 0; i < n; i++) + { + var offset = Offset(intentionalOffsets, i); + var curve = fit.Fitted[i]; + if (!double.IsFinite(flat[i])) + { + target[i] = curve + offset; + continue; + } + var keep = keepScale * fit.RobustWeights[i] * fit.SurvivingFraction[i]; + target[i] = curve + keep * (flat[i] - curve) + offset; + correction[i] = target[i] - logLuminance[i]; + } + + return new DeflickerResult(target, correction, fit.Fitted, fit.RobustWeights, fit.SurvivingFraction, + Diagnose(flat, fit.Fitted, target, intentionalOffsets, fit.RobustWeights)); + } + + /// + /// Luminance offsets implied by metadata exposure: −(EV − EV of the first known frame). Frames without EV + /// inherit the previous known value. + /// + public static double[] OffsetsFromExposure(ReadOnlySpan exposureValues) + { + var offsets = new double[exposureValues.Length]; + double? reference = null; + double current = 0; + for (var i = 0; i < exposureValues.Length; i++) + { + if (exposureValues[i] is { } ev && double.IsFinite(ev)) + { + reference ??= ev; + current = reference.Value - ev; + } + offsets[i] = current; + } + return offsets; + } + + private static double Offset(ReadOnlySpan offsets, int i) => offsets.IsEmpty || !double.IsFinite(offsets[i]) ? 0 : offsets[i]; + + private static DeflickerDiagnostics Diagnose(double[] flat, double[] fitted, double[] target, ReadOnlySpan offsets, double[] robust) + { + double before = 0, after = 0, residual = 0; + int steps = 0, valid = 0, outliers = 0; + for (var i = 0; i < flat.Length; i++) + { + if (!double.IsFinite(flat[i])) continue; + valid++; + residual += (flat[i] - fitted[i]) * (flat[i] - fitted[i]); + if (robust[i] < 0.5) outliers++; + if (i == 0 || !double.IsFinite(flat[i - 1])) continue; + var curveStep = fitted[i] - fitted[i - 1]; + var inputStep = flat[i] - flat[i - 1] - curveStep; + var outputStep = target[i] - Offset(offsets, i) - (target[i - 1] - Offset(offsets, i - 1)) - curveStep; + before += inputStep * inputStep; + after += outputStep * outputStep; + steps++; + } + return new DeflickerDiagnostics( + steps > 0 ? Math.Sqrt(before / steps) : 0, + steps > 0 ? Math.Sqrt(after / steps) : 0, + valid > 0 ? Math.Sqrt(residual / valid) : 0, + outliers); + } +} diff --git a/src/Titano.Core/Analysis/FlickerSpectrum.cs b/src/Titano.Core/Analysis/FlickerSpectrum.cs new file mode 100644 index 00000000..47484cff --- /dev/null +++ b/src/Titano.Core/Analysis/FlickerSpectrum.cs @@ -0,0 +1,87 @@ +using Titano.Core.Mathematics; + +namespace Titano.Core.Analysis; + +/// Parameters of . +public sealed record FlickerSpectrumOptions +{ + public static FlickerSpectrumOptions Default { get; } = new(); + + /// Smallest recommended deflicker window (frames, odd). + public int MinimumWindow { get; init; } = 15; + + /// Largest recommended deflicker window (frames, odd). + public int MaximumWindow { get; init; } = 151; + + /// A periodic peak must reach this autocorrelation (and 3/√n) to count. + public double PeakThreshold { get; init; } = 0.25; +} + +/// r(k) of the detrended luminance for k = 0 … max lag. +/// Period of a periodic flicker component in frames (sub-frame), or null. +/// Frames until r drops below 1/e: the time scale of aperiodic flicker. +/// 4 × (period or correlation length), odd, clamped to the options' bounds. +public sealed record FlickerSpectrumResult(double[] Autocorrelation, double? DominantPeriod, double PeakCorrelation, double CorrelationLength, int RecommendedWindow); + +/// +/// Flicker time scale from the autocorrelation of luminance residuals (BRIEF §10.2): the series is detrended with a +/// wide robust LOWESS, its autocorrelation searched for the strongest peak that follows a negative lobe (a true +/// oscillation), and the deflicker window set to four periods so each local fit averages several cycles. +/// +public static class FlickerSpectrum +{ + public static FlickerSpectrumResult Analyze(ReadOnlySpan logLuminance, FlickerSpectrumOptions? options = null) + { + options ??= FlickerSpectrumOptions.Default; + if (options.MinimumWindow < 3 || options.MaximumWindow < options.MinimumWindow) + throw new ArgumentOutOfRangeException(nameof(options), "Window bounds are invalid."); + var n = logLuminance.Length; + var maxLag = Math.Max(1, n / 4); + var detrendWindow = Math.Clamp(n / 3, 15, 501); + var trend = LocalRegression.Smooth(logLuminance, detrendWindow, degree: 2, robustIterations: 2).Fitted; + var residual = new double[n]; + for (var i = 0; i < n; i++) residual[i] = logLuminance[i] - trend[i]; + var r = new double[maxLag + 1]; + Statistics.Autocorrelation(residual, r); + + var threshold = Math.Max(options.PeakThreshold, 3 / Math.Sqrt(Math.Max(1, n))); + var seenNegative = false; + var peaks = new List(); + for (var k = 1; k < maxLag; k++) + { + if (r[k] < 0) seenNegative = true; + if (k >= 2 && seenNegative && r[k] >= threshold && r[k] >= r[k - 1] && r[k] > r[k + 1]) peaks.Add(k); + } + // The fundamental is the first peak close to the strongest: when the period falls between lags, a multiple + // of it can land on a lag and outscore it. + var best = -1; + if (peaks.Count > 0) + { + var strongest = peaks.Max(k => r[k]); + best = peaks.First(k => r[k] >= 0.8 * strongest); + } + + double? period = null; + if (best > 0) + { + var denominator = r[best - 1] - 2 * r[best] + r[best + 1]; + var shift = denominator < 0 ? 0.5 * (r[best - 1] - r[best + 1]) / denominator : 0; + period = best + Math.Clamp(shift, -0.5, 0.5); + } + + var correlationLength = (double)maxLag; + for (var k = 1; k <= maxLag; k++) + { + if (r[k] >= 1 / Math.E) continue; + // Linear interpolation of the 1/e crossing between k − 1 and k. + correlationLength = k - 1 + (r[k - 1] - 1 / Math.E) / (r[k - 1] - r[k]); + break; + } + + var scale = period ?? correlationLength; + var window = (int)Math.Round(4 * scale); + window = Math.Clamp(window, options.MinimumWindow, options.MaximumWindow); + if (window % 2 == 0) window = window + 1 <= options.MaximumWindow ? window + 1 : window - 1; + return new FlickerSpectrumResult(r, period, best > 0 ? r[best] : 0, correlationLength, window); + } +} diff --git a/tests/Titano.Core.Tests/Analysis/DeflickerEngineTests.cs b/tests/Titano.Core.Tests/Analysis/DeflickerEngineTests.cs new file mode 100644 index 00000000..874bc701 --- /dev/null +++ b/tests/Titano.Core.Tests/Analysis/DeflickerEngineTests.cs @@ -0,0 +1,96 @@ +using System.Globalization; +using Titano.Core.Analysis; +using Titano.Core.Diagnostics.Synthetic; +using Titano.Testing; + +namespace Titano.Core.Tests.Analysis; + +public sealed class DeflickerEngineTests(TestContext context) +{ + /// BRIEF §20.4: flicker reduction ≥ 60 % on the synthetic ramp with the ramp preserved within 0.05 EV, + /// measured end to end (measure → target curve → apply gains → re-measure). + [Test] + public void RampSequenceMeetsTheRegressionGate() + { + var sequence = SyntheticSequence.Create(new SyntheticSequenceOptions + { + FrameCount = 200, + Seed = 3, + StartEv = -2, + EndEv = 1, + FlickerEv = 0.1, + }); + var measured = AnalysisFixtures.MeasureSeries(sequence); + var result = DeflickerEngine.Compute(measured, new DeflickerOptions { Window = 21 }); + var corrected = AnalysisFixtures.MeasureSeries(sequence, (i, image) => + { + ExposureProcessor.Apply(image, result.CorrectionEv[i]); + return image; + }); + + var before = AnalysisFixtures.FrameToFrameResidualRms(measured, sequence.SceneEv); + var after = AnalysisFixtures.FrameToFrameResidualRms(corrected, sequence.SceneEv); + var reduction = 1 - after / before; + var rampError = AnalysisFixtures.MaxDeviation(corrected, sequence.SceneEv); + context.Log(string.Create(CultureInfo.InvariantCulture, + $"flicker before {before:F4} EV, after {after:F4} EV, reduction {reduction:P1}, max ramp deviation {rampError:F4} EV, diagnostics {result.Diagnostics}")); + Assert.GreaterOrEqual(reduction, 0.60); + Assert.LessOrEqual(rampError, 0.05); + Assert.Approximately(after, result.Diagnostics.FlickerAfter, 0.01); + Assert.Approximately(before, result.Diagnostics.FlickerBefore, 0.02); + } + + [Test] + public void IntentionalOffsetsAreNotTreatedAsFlicker() + { + var n = 120; + var ramp = Enumerable.Range(0, n).Select(i => -0.01 * i).ToArray(); + var offsets = Enumerable.Range(0, n).Select(i => i >= 60 ? 1.0 : 0.0).ToArray(); + var measured = ramp.Select((v, i) => v + offsets[i]).ToArray(); + var withOffsets = DeflickerEngine.Compute(measured, intentionalOffsets: offsets); + for (var i = 0; i < n; i++) Assert.Approximately(measured[i], withOffsets.Target[i], 1e-9); + + // Without them the step is smeared into a ramp over the window. + var naive = DeflickerEngine.Compute(measured); + Assert.Greater(Math.Abs(naive.CorrectionEv[59]), 0.2); + } + + [Test] + public void OutliersArePulledOntoTheFitAndStrengthBlendsTheRest() + { + var random = new Random(8); + var n = 150; + var truth = Enumerable.Range(0, n).Select(i => 0.02 * i).ToArray(); + var measured = truth.Select(v => v + 0.05 * (2 * random.NextDouble() - 1)).ToArray(); + measured[70] += 2.5; + var half = DeflickerEngine.Compute(measured, new DeflickerOptions { Strength = 0.5 }); + Assert.Less(half.RobustWeights[70], 0.01); + Assert.Approximately(truth[70], half.Target[70], 0.05); + Assert.Equal(1, half.Diagnostics.OutlierCount); + + // An inlier keeps about half of its own deviation from the fit. + var inlier = Enumerable.Range(0, n).First(i => i is > 10 and < 140 && Math.Abs(measured[i] - half.Fitted[i]) > 0.02 && half.RobustWeights[i] > 0.8); + var kept = (half.Target[inlier] - half.Fitted[inlier]) / (measured[inlier] - half.Fitted[inlier]); + Assert.InRange(kept, 0.5 * half.RobustWeights[inlier] * half.SurvivingFraction[inlier] - 1e-9, 0.5 + 1e-9); + Assert.Greater(kept, 0.35); + } + + [Test] + public void UnusableFramesGetTargetsButNoCorrection() + { + var measured = Enumerable.Range(0, 40).Select(i => 0.1 * i).ToArray(); + measured[12] = double.NaN; + var result = DeflickerEngine.Compute(measured, new DeflickerOptions { Window = 9 }); + Assert.Approximately(1.2, result.Target[12], 1e-9); + Assert.Equal(0.0, result.CorrectionEv[12]); + Assert.Throws(() => DeflickerEngine.Compute(measured, new DeflickerOptions { Strength = 2 })); + } + + [Test] + public void OffsetsFromExposureFollowMetadata() + { + double?[] ev = [null, 12, 12, 11.5, null, 13]; + var offsets = DeflickerEngine.OffsetsFromExposure(ev); + Assert.SequenceEqual([0.0, 0, 0, 0.5, 0.5, -1], offsets); + } +} diff --git a/tests/Titano.Core.Tests/Analysis/FlickerSpectrumTests.cs b/tests/Titano.Core.Tests/Analysis/FlickerSpectrumTests.cs new file mode 100644 index 00000000..33fa43f0 --- /dev/null +++ b/tests/Titano.Core.Tests/Analysis/FlickerSpectrumTests.cs @@ -0,0 +1,66 @@ +using System.Globalization; +using Titano.Core.Analysis; +using Titano.Core.Diagnostics.Synthetic; +using Titano.Testing; + +namespace Titano.Core.Tests.Analysis; + +public sealed class FlickerSpectrumTests(TestContext context) +{ + [Theory] + [Case(12.0)] + [Case(7.5)] + [Case(20.0)] + public void RecoversAKnownPeriodFromRenderedFrames(double period) + { + var sequence = SyntheticSequence.Create(new SyntheticSequenceOptions + { + Width = 48, + Height = 32, + FrameCount = 240, + Seed = 12, + StartEv = 0, + EndEv = -2, + FlickerEv = 0.1, + FlickerPeriodFrames = period, + LandFlickerEv = 0.02, + }); + var measured = AnalysisFixtures.MeasureSeries(sequence); + var result = FlickerSpectrum.Analyze(measured); + context.Log(string.Create(CultureInfo.InvariantCulture, + $"true period {period}, found {result.DominantPeriod:F3} (r = {result.PeakCorrelation:F3}), window {result.RecommendedWindow}")); + var found = Assert.NotNull(result.DominantPeriod); + Assert.Approximately(period, found, 0.5); + Assert.Equal(1, result.RecommendedWindow % 2); + Assert.InRange(result.RecommendedWindow, 4 * period - 1, 4 * period + 2); + } + + [Test] + public void WhiteFlickerHasNoPeriodAndGetsTheMinimumWindow() + { + var random = new Random(2); + var series = Enumerable.Range(0, 300).Select(i => -0.01 * i + 0.1 * (2 * random.NextDouble() - 1)).ToArray(); + var result = FlickerSpectrum.Analyze(series); + Assert.Null(result.DominantPeriod); + Assert.Less(result.CorrelationLength, 1.5); + Assert.Equal(FlickerSpectrumOptions.Default.MinimumWindow, result.RecommendedWindow); + } + + [Test] + public void SlowCorrelatedFlickerWidensTheWindow() + { + // AR(1) flicker with correlation 0.9 per frame: e-folding length about 9.5 frames. + var random = new Random(4); + var series = new double[400]; + var state = 0.0; + for (var i = 0; i < series.Length; i++) + { + state = 0.9 * state + 0.05 * (2 * random.NextDouble() - 1); + series[i] = state; + } + var result = FlickerSpectrum.Analyze(series); + Assert.InRange(result.CorrelationLength, 4, 15); + Assert.Greater(result.RecommendedWindow, 15); + Assert.Equal(1, result.RecommendedWindow % 2); + } +}