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:
4 files changed
+379
No files matched your search
@@ -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);
|
||||
}
|
||||
}
|
||||
Reference in new issue
Block a user