diff --git a/src/Titano.Core/Analysis/HolyGrailEngine.cs b/src/Titano.Core/Analysis/HolyGrailEngine.cs new file mode 100644 index 00000000..38c4e5ca --- /dev/null +++ b/src/Titano.Core/Analysis/HolyGrailEngine.cs @@ -0,0 +1,221 @@ +using Titano.Core.Mathematics; + +namespace Titano.Core.Analysis; + +/// Parameters of . +public sealed record HolyGrailOptions +{ + public static HolyGrailOptions Default { get; } = new(); + + /// Transition length in frames; null = half the typical distance between received steps. + public int? TransitionFrames { get; init; } + + /// Transition length when fewer than two steps were received and none is configured. + public int SingleStepTransitionFrames { get; init; } = 12; + + /// Largest allowed frame-to-frame change of the target curve, in EV. + public double MaxStepEv { get; init; } = 0.3; + + /// Metadata EV changes smaller than this are not steps. + public double MinimumStepEv { get; init; } = 0.05; + + /// A step is received when the measured jump has the expected sign and at least this fraction of its size. + public double MinimumReceivedFraction { get; init; } = 0.5; + + /// Frames measured on each side of a step. + public int MeasureFrames { get; init; } = 6; + + public DeflickerOptions Deflicker { get; init; } = DeflickerOptions.Default; +} + +/// One metadata exposure step and how it was redistributed. +/// First frame shot with the new settings. +/// Luminance change implied by the metadata (−ΔEV). +/// Detrended luminance jump measured across the step (NaN when not measurable). +/// Whether the pixels actually changed; ignored steps get no transition. +/// Frame position where the smooth transition starts (fractional). +/// Transition length in frames (0 when not received). +public sealed record ExposureTransition(int Index, double ExpectedEv, double MeasuredEv, bool Received, double Start, double Length); + +/// Target log2 luminance per frame. +/// Target − measured. +/// Cumulative received steps (the abrupt exposure offsets in the pixels). +/// The same steps spread over their transitions. +/// Largest |Target[i] − Target[i−1]|. +public sealed record HolyGrailResult( + double[] Target, + double[] CorrectionEv, + double[] StepOffsets, + double[] SmoothedOffsets, + IReadOnlyList Transitions, + DeflickerResult Deflicker, + double MaxFrameStepEv); + +/// +/// 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 +/// ; ramps are kept inside the sequence so the total change is preserved. +/// +public static class HolyGrailEngine +{ + /// Measured log2 luminance per frame (NaN = unusable). + /// Metadata EV (ISO 100) per frame; null when unknown. + public static HolyGrailResult Compute(ReadOnlySpan logLuminance, ReadOnlySpan 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(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 DetectSteps(double[] luminance, ReadOnlySpan 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(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; + } + + /// + /// 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. + /// + private static double MeasureJump(double[] luminance, int from, int index, int to) + { + var differences = new List(); + 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(); + var right = new List(); + 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()); + } + + /// 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. + private static double[] InitialLengths(List 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 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); + } + } + } + + /// Ramp centred on the boundary between frames index − 1 and index, shifted to lie inside [0, n − 1]. + 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; + } +} diff --git a/tests/Titano.Core.Tests/Analysis/HolyGrailEngineTests.cs b/tests/Titano.Core.Tests/Analysis/HolyGrailEngineTests.cs new file mode 100644 index 00000000..3becabf6 --- /dev/null +++ b/tests/Titano.Core.Tests/Analysis/HolyGrailEngineTests.cs @@ -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) +{ + /// + /// 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. + /// + [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); + } +}