feat(analysis): add holy-grail exposure step redistribution

Metadata steps are verified against the detrended measured jump; only
received steps are removed, the step-free series deflickered and the
steps restored as smoothstep transitions that lengthen until no frame
step exceeds 0.3 EV.

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 731ab2c48b
commit f6adbf7a31
2 files changed
+309

No files matched your search

+221
View File
@@ -0,0 +1,221 @@
using Titano.Core.Mathematics;
namespace Titano.Core.Analysis;
/// <summary>Parameters of <see cref="HolyGrailEngine"/>.</summary>
public sealed record HolyGrailOptions
{
public static HolyGrailOptions Default { get; } = new();
/// <summary>Transition length in frames; null = half the typical distance between received steps.</summary>
public int? TransitionFrames { get; init; }
/// <summary>Transition length when fewer than two steps were received and none is configured.</summary>
public int SingleStepTransitionFrames { get; init; } = 12;
/// <summary>Largest allowed frame-to-frame change of the target curve, in EV.</summary>
public double MaxStepEv { get; init; } = 0.3;
/// <summary>Metadata EV changes smaller than this are not steps.</summary>
public double MinimumStepEv { get; init; } = 0.05;
/// <summary>A step is received when the measured jump has the expected sign and at least this fraction of its size.</summary>
public double MinimumReceivedFraction { get; init; } = 0.5;
/// <summary>Frames measured on each side of a step.</summary>
public int MeasureFrames { get; init; } = 6;
public DeflickerOptions Deflicker { get; init; } = DeflickerOptions.Default;
}
/// <summary>One metadata exposure step and how it was redistributed.</summary>
/// <param name="Index">First frame shot with the new settings.</param>
/// <param name="ExpectedEv">Luminance change implied by the metadata (−ΔEV).</param>
/// <param name="MeasuredEv">Detrended luminance jump measured across the step (NaN when not measurable).</param>
/// <param name="Received">Whether the pixels actually changed; ignored steps get no transition.</param>
/// <param name="Start">Frame position where the smooth transition starts (fractional).</param>
/// <param name="Length">Transition length in frames (0 when not received).</param>
public sealed record ExposureTransition(int Index, double ExpectedEv, double MeasuredEv, bool Received, double Start, double Length);
/// <param name="Target">Target log2 luminance per frame.</param>
/// <param name="CorrectionEv">Target − measured.</param>
/// <param name="StepOffsets">Cumulative received steps (the abrupt exposure offsets in the pixels).</param>
/// <param name="SmoothedOffsets">The same steps spread over their transitions.</param>
/// <param name="MaxFrameStepEv">Largest |Target[i] − Target[i−1]|.</param>
public sealed record HolyGrailResult(
double[] Target,
double[] CorrectionEv,
double[] StepOffsets,
double[] SmoothedOffsets,
IReadOnlyList<ExposureTransition> Transitions,
DeflickerResult Deflicker,
double MaxFrameStepEv);
/// <summary>
/// Holy-grail exposure-step redistribution (BRIEF §10.3, §11.2). Metadata EV steps are checked against the measured
/// luminance (detrended medians on both sides), steps the pixels did not receive are ignored, and each received step
/// is removed from the series, the step-free series deflickered, and the step added back as a smoothstep transition
/// centred on it. Transitions lengthen until no frame-to-frame change of the target exceeds
/// <see cref="HolyGrailOptions.MaxStepEv"/>; ramps are kept inside the sequence so the total change is preserved.
/// </summary>
public static class HolyGrailEngine
{
/// <param name="logLuminance">Measured log2 luminance per frame (NaN = unusable).</param>
/// <param name="exposureEv">Metadata EV (ISO 100) per frame; null when unknown.</param>
public static HolyGrailResult Compute(ReadOnlySpan<double> logLuminance, ReadOnlySpan<double?> exposureEv, HolyGrailOptions? options = null)
{
options ??= HolyGrailOptions.Default;
var n = logLuminance.Length;
if (exposureEv.Length != n) throw new ArgumentException("One exposure value per frame is required.", nameof(exposureEv));
if (!(options.MaxStepEv > 0)) throw new ArgumentOutOfRangeException(nameof(options), "MaxStepEv must be positive.");
var luminance = logLuminance.ToArray();
var transitions = DetectSteps(luminance, exposureEv, options);
var offsets = new double[n];
foreach (var t in transitions)
{
if (!t.Received) continue;
for (var i = t.Index; i < n; i++) offsets[i] += t.ExpectedEv;
}
var flat = new double[n];
for (var i = 0; i < n; i++) flat[i] = luminance[i] - offsets[i];
var deflicker = DeflickerEngine.Compute(flat, options.Deflicker);
var received = transitions.Where(t => t.Received).ToList();
var lengths = InitialLengths(received, deflicker.Target, n, options);
var smoothed = new double[n];
var target = new double[n];
var maxStep = 0.0;
for (var attempt = 0; attempt < 40; attempt++)
{
Ramps(received, lengths, n, smoothed);
for (var i = 0; i < n; i++) target[i] = deflicker.Target[i] + smoothed[i];
maxStep = MaxStep(target);
if (maxStep <= options.MaxStepEv || lengths.All(l => l >= n - 1)) break;
for (var k = 0; k < lengths.Length; k++) lengths[k] = Math.Min(n - 1, Math.Max(lengths[k] + 1, lengths[k] * 1.25));
}
var correction = new double[n];
for (var i = 0; i < n; i++) correction[i] = double.IsFinite(luminance[i]) ? target[i] - luminance[i] : 0;
var report = new List<ExposureTransition>(transitions.Count);
var r = 0;
foreach (var t in transitions)
{
if (!t.Received)
{
report.Add(t);
continue;
}
report.Add(t with { Start = RampStart(t.Index, lengths[r], n), Length = lengths[r] });
r++;
}
return new HolyGrailResult(target, correction, offsets, smoothed, report, deflicker, maxStep);
}
private static List<ExposureTransition> DetectSteps(double[] luminance, ReadOnlySpan<double?> exposureEv, HolyGrailOptions options)
{
var candidates = new List<(int Index, double Expected)>();
double? last = null;
for (var i = 0; i < exposureEv.Length; i++)
{
if (exposureEv[i] is not { } ev || !double.IsFinite(ev)) continue;
if (last is { } p && Math.Abs(ev - p) >= options.MinimumStepEv) candidates.Add((i, -(ev - p)));
last = ev;
}
var result = new List<ExposureTransition>(candidates.Count);
for (var c = 0; c < candidates.Count; c++)
{
var (index, expected) = candidates[c];
var from = Math.Max(c > 0 ? candidates[c - 1].Index : 0, index - options.MeasureFrames);
var to = Math.Min(c + 1 < candidates.Count ? candidates[c + 1].Index : luminance.Length, index + options.MeasureFrames);
var measured = MeasureJump(luminance, from, index, to);
var received = double.IsNaN(measured)
|| (Math.Sign(measured) == Math.Sign(expected) && Math.Abs(measured) >= options.MinimumReceivedFraction * Math.Abs(expected));
result.Add(new ExposureTransition(index, expected, measured, received, 0, 0));
}
return result;
}
/// <summary>
/// Jump between frames [from, index) and [index, to): the scene trend (median first difference on both sides,
/// excluding the step itself) is removed, then the medians of the two sides are compared. NaN when a side has no
/// valid frame.
/// </summary>
private static double MeasureJump(double[] luminance, int from, int index, int to)
{
var differences = new List<double>();
for (var j = from + 1; j < to; j++)
{
if (j == index) continue;
var d = luminance[j] - luminance[j - 1];
if (double.IsFinite(d)) differences.Add(d);
}
var slope = differences.Count > 0 ? Statistics.Median(differences.ToArray()) : 0;
var left = new List<double>();
var right = new List<double>();
for (var j = from; j < to; j++)
{
if (!double.IsFinite(luminance[j])) continue;
var detrended = luminance[j] - slope * (j - (index - 0.5));
(j < index ? left : right).Add(detrended);
}
if (left.Count == 0 || right.Count == 0) return double.NaN;
return Statistics.Median(right.ToArray()) - Statistics.Median(left.ToArray());
}
/// <summary>Half the typical spacing of received steps (or the configured length), lengthened per step so a lone
/// smoothstep (peak slope 1.5·|s|/L) fits in the budget left by the scene's own frame-to-frame change.</summary>
private static double[] InitialLengths(List<ExposureTransition> received, double[] sceneTarget, int n, HolyGrailOptions options)
{
double baseLength;
if (options.TransitionFrames is { } configured) baseLength = configured;
else if (received.Count >= 2)
{
var spacing = new double[received.Count - 1];
for (var i = 1; i < received.Count; i++) spacing[i - 1] = received[i].Index - received[i - 1].Index;
baseLength = Math.Round(Statistics.Median(spacing) / 2);
}
else baseLength = options.SingleStepTransitionFrames;
baseLength = Math.Max(2, baseLength);
var budget = options.MaxStepEv - MaxStep(sceneTarget);
var lengths = new double[received.Count];
for (var k = 0; k < lengths.Length; k++)
{
var needed = budget > 0 ? Math.Ceiling(1.5 * Math.Abs(received[k].ExpectedEv) / budget) : n - 1;
lengths[k] = Math.Min(Math.Max(1, n - 1), Math.Max(baseLength, needed));
}
return lengths;
}
private static void Ramps(List<ExposureTransition> received, double[] lengths, int n, double[] smoothed)
{
Array.Clear(smoothed);
for (var k = 0; k < received.Count; k++)
{
var length = lengths[k];
var start = RampStart(received[k].Index, length, n);
var amount = received[k].ExpectedEv;
for (var i = 0; i < n; i++)
{
var t = Math.Clamp((i - start) / length, 0, 1);
smoothed[i] += amount * t * t * (3 - 2 * t);
}
}
}
/// <summary>Ramp centred on the boundary between frames index − 1 and index, shifted to lie inside [0, n − 1].</summary>
private static double RampStart(int index, double length, int n) => Math.Clamp(index - 0.5 - length / 2, 0, Math.Max(0, n - 1 - length));
private static double MaxStep(double[] series)
{
var max = 0.0;
for (var i = 1; i < series.Length; i++)
{
var d = Math.Abs(series[i] - series[i - 1]);
if (double.IsFinite(d)) max = Math.Max(max, d);
}
return max;
}
}
@@ -0,0 +1,88 @@
using System.Globalization;
using Titano.Core.Analysis;
using Titano.Core.Diagnostics.Synthetic;
using Titano.Testing;
namespace Titano.Core.Tests.Analysis;
public sealed class HolyGrailEngineTests(TestContext context)
{
/// <summary>
/// Sunset: the scene darkens 8 EV while the camera opens up 2/3 EV every 20 frames, plus one metadata change
/// the pixels never received. BRIEF §20.4: no target step above 0.3 EV; the total change is preserved.
/// </summary>
[Test]
public void SunsetStepsAreRedistributedWithinTheGate()
{
var steps = Enumerable.Range(1, 11).Select(k => new SyntheticExposureStep(k * 20, -2.0 / 3, k % 3 == 0 ? ExposureChange.Iso : ExposureChange.Shutter)).ToList();
steps.Add(new SyntheticExposureStep(130, -1.0 / 3, ExposureChange.Aperture, Received: false));
var sequence = SyntheticSequence.Create(new SyntheticSequenceOptions
{
FrameCount = 240,
Seed = 9,
StartEv = 2,
EndEv = -6,
FlickerEv = 0.03,
ExposureSteps = steps,
});
var measured = AnalysisFixtures.MeasureSeries(sequence);
var ev = sequence.Frames.Select(f => f.ExposureValue).ToArray();
var result = HolyGrailEngine.Compute(measured, ev);
var rawMaxStep = Enumerable.Range(1, measured.Length - 1).Max(i => Math.Abs(measured[i] - measured[i - 1]));
var maxStep = Enumerable.Range(1, measured.Length - 1).Max(i => Math.Abs(result.Target[i] - result.Target[i - 1]));
var truth = sequence.SceneEv.Select((s, i) => s + sequence.ExposureOffsetEv[i]).ToArray();
var totalTruth = truth[^1] - truth[0];
var totalTarget = result.Target[^1] - result.Target[0];
context.Log(string.Create(CultureInfo.InvariantCulture,
$"raw max step {rawMaxStep:F3} EV, target max step {maxStep:F3} EV, total change target {totalTarget:F3} vs truth {totalTruth:F3} EV, transition {result.Transitions[0].Length} frames"));
Assert.Equal(12, result.Transitions.Count);
var ignored = Assert.NotNull(result.Transitions.SingleOrDefault(t => !t.Received));
Assert.Equal(130, ignored.Index);
Assert.True(result.Transitions.Where(t => t.Index != 130).All(t => t.Received));
Assert.Greater(rawMaxStep, 0.5);
Assert.LessOrEqual(maxStep, 0.3);
Assert.Approximately(maxStep, result.MaxFrameStepEv, 1e-12);
Assert.Approximately(totalTruth, totalTarget, 0.05);
// Default transition: half the 20-frame step spacing.
Assert.Equal(10.0, result.Transitions[0].Length);
}
[Test]
public void LargeStepGetsALongerTransition()
{
var n = 100;
var measured = Enumerable.Range(0, n).Select(i => i >= 50 ? 1.5 : 0.0).ToArray();
var ev = Enumerable.Range(0, n).Select(i => (double?)(i >= 50 ? 10.5 : 12.0)).ToArray();
var result = HolyGrailEngine.Compute(measured, ev, new HolyGrailOptions { TransitionFrames = 4 });
Assert.LessOrEqual(result.MaxFrameStepEv, 0.3);
Assert.GreaterOrEqual(result.Transitions[0].Length, 7.5);
Assert.Approximately(1.5, result.Target[^1] - result.Target[0], 1e-9);
Assert.Approximately(1.5, result.Transitions[0].MeasuredEv, 1e-9);
}
[Test]
public void StepsNearTheEndsStayInsideTheSequence()
{
var n = 30;
var measured = Enumerable.Range(0, n).Select(i => i >= 2 ? 1.0 : 0.0).ToArray();
var ev = Enumerable.Range(0, n).Select(i => (double?)(i >= 2 ? 11.0 : 12.0)).ToArray();
var result = HolyGrailEngine.Compute(measured, ev, new HolyGrailOptions { TransitionFrames = 8 });
Assert.Equal(0.0, result.Transitions[0].Start);
Assert.Approximately(0, result.SmoothedOffsets[0], 1e-12);
Assert.Approximately(1, result.SmoothedOffsets[^1], 1e-12);
Assert.LessOrEqual(result.MaxFrameStepEv, 0.3);
}
[Test]
public void NoMetadataStepsMeansPlainDeflicker()
{
var measured = Enumerable.Range(0, 60).Select(i => 0.01 * i + (i % 2 == 0 ? 0.05 : -0.05)).ToArray();
var ev = new double?[60];
var result = HolyGrailEngine.Compute(measured, ev);
var plain = DeflickerEngine.Compute(measured);
Assert.Empty(result.Transitions);
Assert.SequenceEqual(plain.Target, result.Target);
}
}