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