feat(analysis): add deflicker engine and flicker spectrum

Robust LOWESS target curve with intentional exposure offsets removed,
blended by Tukey weight and surviving-window fraction; flicker spectrum
from the autocorrelation of detrended luminance recommends a window of
four periods.

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 353143b953
commit d6772d2602
4 files changed
+379

No files matched your search

+130
View File
@@ -0,0 +1,130 @@
using Titano.Core.Mathematics;
namespace Titano.Core.Analysis;
/// <summary>Parameters of <see cref="DeflickerEngine"/>.</summary>
public sealed record DeflickerOptions
{
public static DeflickerOptions Default { get; } = new();
/// <summary>Frames in each local fit (see <see cref="FlickerSpectrum"/> for a recommendation).</summary>
public int Window { get; init; } = 21;
/// <summary>Local polynomial degree, 1 or 2.</summary>
public int Degree { get; init; } = 1;
/// <summary>Tukey reweighting passes.</summary>
public int RobustIterations { get; init; } = 3;
/// <summary>1 lands every frame on the fitted curve; lower values let trusted frames keep part of their own deviation.</summary>
public double Strength { get; init; } = 1;
}
/// <summary>Flicker before and after correction, in EV.</summary>
/// <param name="FlickerBefore">RMS frame-to-frame step of the input relative to the fitted curve.</param>
/// <param name="FlickerAfter">The same measure on the target curve.</param>
/// <param name="ResidualRms">RMS of input minus fitted curve over valid frames.</param>
/// <param name="OutlierCount">Frames whose robust weight fell below ½.</param>
public sealed record DeflickerDiagnostics(double FlickerBefore, double FlickerAfter, double ResidualRms, int OutlierCount);
/// <summary>Per-frame deflicker result; arrays have one entry per frame.</summary>
public sealed record DeflickerResult(
double[] Target,
double[] CorrectionEv,
double[] Fitted,
double[] RobustWeights,
double[] SurvivingFraction,
DeflickerDiagnostics Diagnostics);
/// <summary>
/// Deflicker target curve (BRIEF §11.2): robust LOWESS (<see cref="LocalRegression"/>) 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.
/// </summary>
public static class DeflickerEngine
{
/// <param name="logLuminance">Measured log2 luminance per frame (NaN = unusable frame, corrected by 0).</param>
/// <param name="intentionalOffsets">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.</param>
public static DeflickerResult Compute(ReadOnlySpan<double> logLuminance, DeflickerOptions? options = null, ReadOnlySpan<double> 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));
}
/// <summary>
/// Luminance offsets implied by metadata exposure: −(EV − EV of the first known frame). Frames without EV
/// inherit the previous known value.
/// </summary>
public static double[] OffsetsFromExposure(ReadOnlySpan<double?> 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<double> offsets, int i) => offsets.IsEmpty || !double.IsFinite(offsets[i]) ? 0 : offsets[i];
private static DeflickerDiagnostics Diagnose(double[] flat, double[] fitted, double[] target, ReadOnlySpan<double> 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);
}
}
@@ -0,0 +1,87 @@
using Titano.Core.Mathematics;
namespace Titano.Core.Analysis;
/// <summary>Parameters of <see cref="FlickerSpectrum"/>.</summary>
public sealed record FlickerSpectrumOptions
{
public static FlickerSpectrumOptions Default { get; } = new();
/// <summary>Smallest recommended deflicker window (frames, odd).</summary>
public int MinimumWindow { get; init; } = 15;
/// <summary>Largest recommended deflicker window (frames, odd).</summary>
public int MaximumWindow { get; init; } = 151;
/// <summary>A periodic peak must reach this autocorrelation (and 3/√n) to count.</summary>
public double PeakThreshold { get; init; } = 0.25;
}
/// <param name="Autocorrelation">r(k) of the detrended luminance for k = 0 … max lag.</param>
/// <param name="DominantPeriod">Period of a periodic flicker component in frames (sub-frame), or null.</param>
/// <param name="CorrelationLength">Frames until r drops below 1/e: the time scale of aperiodic flicker.</param>
/// <param name="RecommendedWindow">4 × (period or correlation length), odd, clamped to the options' bounds.</param>
public sealed record FlickerSpectrumResult(double[] Autocorrelation, double? DominantPeriod, double PeakCorrelation, double CorrelationLength, int RecommendedWindow);
/// <summary>
/// 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.
/// </summary>
public static class FlickerSpectrum
{
public static FlickerSpectrumResult Analyze(ReadOnlySpan<double> 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<int>();
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);
}
}
@@ -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)
{
/// <summary>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).</summary>
[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<ArgumentOutOfRangeException>(() => 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);
}
}
@@ -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);
}
}