diff --git a/src/Titano.Core/Diagnostics/Synthetic/SyntheticSequence.cs b/src/Titano.Core/Diagnostics/Synthetic/SyntheticSequence.cs
new file mode 100644
index 00000000..53a02c98
--- /dev/null
+++ b/src/Titano.Core/Diagnostics/Synthetic/SyntheticSequence.cs
@@ -0,0 +1,374 @@
+using Titano.Core.Analysis;
+using Titano.Core.Imaging;
+using Titano.Core.Metadata;
+using Titano.Core.Model;
+
+namespace Titano.Core.Diagnostics.Synthetic;
+
+/// A deliberate exposure change written to the metadata from frame on; when
+/// is false the pixels ignore it (e.g. a setting the camera did not apply).
+/// Camera EV change (positive = less light; the pixels darken by this many stops).
+public sealed record SyntheticExposureStep(int Index, double DeltaEv, ExposureChange Change = ExposureChange.Shutter, bool Received = true);
+
+/// Seconds added to the capture clock from frame on (pauses, clock jumps).
+public sealed record SyntheticTimeShift(int Index, double Seconds);
+
+/// Recipe of a synthetic sequence; every field has a neutral default.
+public sealed record SyntheticSequenceOptions
+{
+ public int Width { get; init; } = 96;
+ public int Height { get; init; } = 64;
+ public int FrameCount { get; init; } = 120;
+ public int Seed { get; init; } = 1;
+
+ /// Camera wall-clock time of the first frame.
+ public DateTime Start { get; init; } = new(2024, 6, 21, 19, 0, 0);
+
+ public int? UtcOffsetMinutes { get; init; } = 120;
+ public double IntervalSeconds { get; init; } = 10;
+
+ /// Uniform ± jitter of each capture time, in seconds.
+ public double IntervalJitterSeconds { get; init; }
+
+ public IReadOnlyList TimeShifts { get; init; } = [];
+
+ /// Scene brightness (EV) at the first and last frame; linear ramp in between.
+ public double StartEv { get; init; }
+
+ public double EndEv { get; init; }
+
+ /// Global flicker amplitude in EV: uniform in ±amplitude, or a sinusoid when a period is set.
+ public double FlickerEv { get; init; }
+
+ /// Period of sinusoidal flicker in frames; 0 = random flicker.
+ public double FlickerPeriodFrames { get; init; }
+
+ /// Extra independent uniform flicker of the sky region, in ±EV.
+ public double SkyFlickerEv { get; init; }
+
+ /// Extra independent uniform flicker of the land region, in ±EV.
+ public double LandFlickerEv { get; init; }
+
+ public IReadOnlyList ExposureSteps { get; init; } = [];
+
+ /// Horizon row at the centre column as a fraction of the height (sky above).
+ public double HorizonFraction { get; init; } = 0.45;
+
+ /// Horizon slope in rows per column.
+ public double HorizonTilt { get; init; }
+
+ /// Amplitude in rows of one sine period of horizon undulation across the width.
+ public double HorizonWave { get; init; }
+
+ /// Linear luminance of the sky (at the horizon) and of the average land pixel at 0 EV.
+ public double SkyLevel { get; init; } = 0.25;
+
+ public double LandLevel { get; init; } = 0.05;
+
+ /// Night sky: dark background with point stars instead of a bright gradient.
+ public bool StarField { get; init; }
+
+ public int StarCount { get; init; } = 40;
+
+ /// Correlated colour temperature of the light at the first and last frame (linear in mireds).
+ public double StartKelvin { get; init; } = 5500;
+
+ public double EndKelvin { get; init; } = 5500;
+
+ /// Uniform ± per-frame jitter of log2(R/G) and log2(B/G).
+ public double WhiteBalanceJitter { get; init; }
+
+ /// Additive Gaussian sensor noise (linear units) on every channel.
+ public double NoiseSigma { get; init; }
+
+ public IReadOnlyList BlackFrames { get; init; } = [];
+ public IReadOnlyList WhiteFrames { get; init; } = [];
+
+ /// Frames that repeat the previous frame exactly (pixels, capture time and settings).
+ public IReadOnlyList DuplicateFrames { get; init; } = [];
+
+ public double BaseExposureTime { get; init; } = 1.0 / 100;
+ public double BaseFNumber { get; init; } = 8;
+ public int BaseIso { get; init; } = 100;
+ public string CameraMake { get; init; } = "Titano";
+ public string CameraModel { get; init; } = "Synthetic";
+ public string Lens { get; init; } = "Synthetic 24mm";
+ public double? Latitude { get; init; }
+ public double? Longitude { get; init; }
+}
+
+///
+/// Deterministic synthetic time-lapse with known answers (the analysis self-test fixture): a scene-brightness
+/// ramp, seeded flicker (global and per region), exposure steps in metadata and pixels, a sky/land split along a
+/// horizon, colour-temperature drift, an optional star field, and black/white/duplicate frames. Pixels are linear
+/// light: base(x, y) · 2^(scene + exposure + flicker + regionFlicker) · rgb(kelvin) with rgb at luminance 1,
+/// so log-luminance shifts equal the truth series exactly.
+///
+public sealed class SyntheticSequence
+{
+ private readonly int[] _source;
+
+ private SyntheticSequence(SyntheticSequenceOptions options)
+ {
+ Options = options;
+ var n = options.FrameCount;
+ var random = new Random(options.Seed);
+ _source = new int[n];
+ SceneEv = new double[n];
+ FlickerEv = new double[n];
+ SkyFlickerEv = new double[n];
+ LandFlickerEv = new double[n];
+ ExposureOffsetEv = new double[n];
+ Kelvin = new double[n];
+ RedJitter = new double[n];
+ BlueJitter = new double[n];
+ var phase = random.NextDouble() * 2 * Math.PI;
+ for (var i = 0; i < n; i++)
+ {
+ var t = n > 1 ? (double)i / (n - 1) : 0;
+ SceneEv[i] = options.StartEv + (options.EndEv - options.StartEv) * t;
+ FlickerEv[i] = options.FlickerPeriodFrames > 0
+ ? options.FlickerEv * Math.Sin(2 * Math.PI * i / options.FlickerPeriodFrames + phase)
+ : options.FlickerEv * (2 * random.NextDouble() - 1);
+ SkyFlickerEv[i] = options.SkyFlickerEv * (2 * random.NextDouble() - 1);
+ LandFlickerEv[i] = options.LandFlickerEv * (2 * random.NextDouble() - 1);
+ Kelvin[i] = 1e6 / (1e6 / options.StartKelvin + (1e6 / options.EndKelvin - 1e6 / options.StartKelvin) * t);
+ RedJitter[i] = options.WhiteBalanceJitter * (2 * random.NextDouble() - 1);
+ BlueJitter[i] = options.WhiteBalanceJitter * (2 * random.NextDouble() - 1);
+ }
+
+ var frames = new Frame[n];
+ var metadata = new FrameMetadata[n];
+ var sequenceId = DeterministicGuid(options.Seed, -1);
+ double exposureTime = options.BaseExposureTime, fNumber = options.BaseFNumber, pixelOffset = 0;
+ var iso = options.BaseIso;
+ var timeShift = 0.0;
+ var duplicates = new HashSet(options.DuplicateFrames);
+ for (var i = 0; i < n; i++)
+ {
+ foreach (var shift in options.TimeShifts)
+ {
+ if (shift.Index == i) timeShift += shift.Seconds;
+ }
+ foreach (var step in options.ExposureSteps)
+ {
+ if (step.Index != i) continue;
+ var before = Ev(exposureTime, fNumber, iso);
+ switch (step.Change)
+ {
+ case ExposureChange.Aperture: fNumber *= Math.Pow(2, step.DeltaEv / 2); break;
+ case ExposureChange.Iso: iso = (int)Math.Round(iso * Math.Pow(2, -step.DeltaEv)); break;
+ default: exposureTime *= Math.Pow(2, -step.DeltaEv); break;
+ }
+ if (step.Received) pixelOffset -= Ev(exposureTime, fNumber, iso) - before;
+ }
+ ExposureOffsetEv[i] = pixelOffset;
+ var jitter = options.IntervalJitterSeconds * (2 * random.NextDouble() - 1);
+ var captured = options.Start.AddSeconds(i * options.IntervalSeconds + jitter + timeShift);
+ _source[i] = i;
+ if (duplicates.Contains(i) && i > 0)
+ {
+ _source[i] = _source[i - 1];
+ captured = metadata[i - 1].CapturedAt!.Value;
+ CopyTruth(i, i - 1);
+ }
+ var exposure = duplicates.Contains(i) && i > 0 ? metadata[i - 1] : null;
+ metadata[i] = new FrameMetadata
+ {
+ Format = ImageFileFormat.Tiff,
+ Make = options.CameraMake,
+ Model = options.CameraModel,
+ LensModel = options.Lens,
+ CapturedAt = captured,
+ UtcOffsetMinutes = options.UtcOffsetMinutes,
+ TimestampSource = TimestampSource.ExifOriginal,
+ ExposureTime = exposure?.ExposureTime ?? exposureTime,
+ FNumber = exposure?.FNumber ?? fNumber,
+ Iso = exposure?.Iso ?? iso,
+ Width = options.Width,
+ Height = options.Height,
+ Gps = options.Latitude is { } lat && options.Longitude is { } lon ? new GpsPosition(lat, lon, null, null) : null,
+ };
+ var name = $"IMG_{i + 1:D4}.tif";
+ frames[i] = new Frame
+ {
+ Id = DeterministicGuid(options.Seed, i),
+ SequenceId = sequenceId,
+ Index = i,
+ RelativePath = "synthetic/" + name,
+ FileName = name,
+ CapturedAt = captured,
+ UtcOffsetMinutes = options.UtcOffsetMinutes,
+ TimestampSource = TimestampSource.ExifOriginal,
+ ExposureTime = metadata[i].ExposureTime,
+ FNumber = metadata[i].FNumber,
+ Iso = metadata[i].Iso,
+ Width = options.Width,
+ Height = options.Height,
+ Format = ImageFileFormat.Tiff,
+ };
+ }
+ Frames = frames;
+ Metadata = metadata;
+ }
+
+ public SyntheticSequenceOptions Options { get; }
+ public IReadOnlyList Frames { get; }
+ public IReadOnlyList Metadata { get; }
+
+ /// True scene brightness per frame (EV): the ramp.
+ public double[] SceneEv { get; }
+
+ /// Global flicker per frame (EV).
+ public double[] FlickerEv { get; }
+
+ public double[] SkyFlickerEv { get; }
+ public double[] LandFlickerEv { get; }
+
+ /// Luminance offset of the received exposure steps (EV).
+ public double[] ExposureOffsetEv { get; }
+
+ public double[] Kelvin { get; }
+
+ /// Per-frame white-balance jitter of log2(R/G) and log2(B/G).
+ public double[] RedJitter { get; }
+
+ public double[] BlueJitter { get; }
+
+ public int Count => Options.FrameCount;
+
+ public bool IsBlack(int index) => Options.BlackFrames.Contains(_source[index]);
+
+ public bool IsWhite(int index) => Options.WhiteFrames.Contains(_source[index]);
+
+ /// Light-analysis input of every frame (with camera, lens and GPS).
+ public IReadOnlyList LightFrames() => Metadata.Select((m, i) => LightFrame.From(m, i)).ToList();
+
+ /// Horizon position (rows from the top edge) at column centre .
+ public double HorizonRow(double x)
+ {
+ var o = Options;
+ var centre = o.Width / 2.0;
+ return o.HorizonFraction * o.Height + o.HorizonTilt * (x - centre) + o.HorizonWave * Math.Sin(2 * Math.PI * x / o.Width);
+ }
+
+ public bool IsSky(int x, int y) => y + 0.5 < HorizonRow(x + 0.5);
+
+ public static SyntheticSequence Create(SyntheticSequenceOptions options)
+ {
+ ArgumentNullException.ThrowIfNull(options);
+ ArgumentOutOfRangeException.ThrowIfLessThan(options.Width, 4);
+ ArgumentOutOfRangeException.ThrowIfLessThan(options.Height, 4);
+ ArgumentOutOfRangeException.ThrowIfNegativeOrZero(options.FrameCount);
+ return new SyntheticSequence(options);
+ }
+
+ /// Renders frame (linear RGB); identical calls give identical pixels.
+ public ImageBuffer Render(int index)
+ {
+ ArgumentOutOfRangeException.ThrowIfNegative(index);
+ ArgumentOutOfRangeException.ThrowIfGreaterThanOrEqual(index, Count);
+ var o = Options;
+ var source = _source[index];
+ var image = new ImageBuffer(o.Width, o.Height, 3);
+ if (IsWhite(index))
+ {
+ image.Data.Fill(1f);
+ return image;
+ }
+ if (IsBlack(index)) return image;
+
+ var colour = ColourOf(source);
+ var common = SceneEv[source] + ExposureOffsetEv[source] + FlickerEv[source];
+ var skyGain = Math.Pow(2, common + SkyFlickerEv[source]);
+ var landGain = Math.Pow(2, common + LandFlickerEv[source]);
+ var noise = o.NoiseSigma > 0 ? new Random(unchecked(o.Seed * 7919 + source * 104729)) : null;
+ var r = image.Plane(0);
+ var g = image.Plane(1);
+ var b = image.Plane(2);
+ for (var y = 0; y < o.Height; y++)
+ {
+ for (var x = 0; x < o.Width; x++)
+ {
+ var horizon = HorizonRow(x + 0.5);
+ double value;
+ if (y + 0.5 < horizon)
+ {
+ value = skyGain * (o.StarField
+ ? StarOrBackground(x, y)
+ : o.SkyLevel * (0.7 + 0.3 * Math.Clamp((y + 0.5) / Math.Max(1, horizon), 0, 1)));
+ }
+ else
+ {
+ value = landGain * o.LandLevel * (o.StarField ? 1.0 / 32 : 1) * (0.5 + Hash(x, y, o.Seed));
+ }
+ var i = y * o.Width + x;
+ r[i] = (float)(value * colour.Red + Noise(noise));
+ g[i] = (float)(value * colour.Green + Noise(noise));
+ b[i] = (float)(value * colour.Blue + Noise(noise));
+ }
+ }
+ return image;
+ }
+
+ private double StarOrBackground(int x, int y)
+ {
+ var o = Options;
+ var star = Hash(x, y, o.Seed + 1);
+ var density = (double)o.StarCount / (o.Width * o.Height * o.HorizonFraction);
+ return star < density ? 0.25 + 0.75 * Hash(y, x, o.Seed + 2) : 1.0 / 2048;
+ }
+
+ private double Noise(Random? random)
+ {
+ if (random is null) return 0;
+ // Box–Muller transform of two uniform deviates.
+ var u = 1 - random.NextDouble();
+ var v = random.NextDouble();
+ return Options.NoiseSigma * Math.Sqrt(-2 * Math.Log(u)) * Math.Cos(2 * Math.PI * v);
+ }
+
+ /// Linear Rec.709 colour of the frame's light at luminance 1, with the white-balance jitter applied.
+ private ChannelGains ColourOf(int index)
+ {
+ var rgb = ColorTemperature.PlanckianRgb(Kelvin[index]);
+ var red = rgb.X * Math.Pow(2, RedJitter[index]);
+ var blue = rgb.Z * Math.Pow(2, BlueJitter[index]);
+ var luminance = ColorSpace.LumaR * red + ColorSpace.LumaG * rgb.Y + ColorSpace.LumaB * blue;
+ return new ChannelGains(red / luminance, rgb.Y / luminance, blue / luminance);
+ }
+
+ private void CopyTruth(int to, int from)
+ {
+ SceneEv[to] = SceneEv[from];
+ FlickerEv[to] = FlickerEv[from];
+ SkyFlickerEv[to] = SkyFlickerEv[from];
+ LandFlickerEv[to] = LandFlickerEv[from];
+ ExposureOffsetEv[to] = ExposureOffsetEv[from];
+ Kelvin[to] = Kelvin[from];
+ RedJitter[to] = RedJitter[from];
+ BlueJitter[to] = BlueJitter[from];
+ }
+
+ private static double Ev(double exposureTime, double fNumber, int iso) => Math.Log2(fNumber * fNumber / exposureTime) - Math.Log2(iso / 100.0);
+
+ /// Uniform [0, 1) from a SplitMix64 hash of the inputs (stable across processes, unlike HashCode).
+ private static double Hash(int x, int y, int seed)
+ {
+ var z = unchecked((ulong)(uint)x * 0x9E3779B97F4A7C15UL ^ (ulong)(uint)y * 0xC2B2AE3D27D4EB4FUL ^ (ulong)(uint)seed * 0x165667B19E3779F9UL);
+ z = unchecked((z ^ (z >> 30)) * 0xBF58476D1CE4E5B9UL);
+ z = unchecked((z ^ (z >> 27)) * 0x94D049BB133111EBUL);
+ z ^= z >> 31;
+ return (z >> 11) * (1.0 / (1UL << 53));
+ }
+
+ private static Guid DeterministicGuid(int seed, int index)
+ {
+ Span bytes = stackalloc byte[16];
+ BitConverter.TryWriteBytes(bytes, (long)seed);
+ BitConverter.TryWriteBytes(bytes[8..], (long)index);
+ bytes[7] = (byte)((bytes[7] & 0x0F) | 0x40);
+ bytes[8] = (byte)((bytes[8] & 0x3F) | 0x80);
+ return new Guid(bytes);
+ }
+}
diff --git a/tests/Titano.Core.Tests/Analysis/AnalysisFixtures.cs b/tests/Titano.Core.Tests/Analysis/AnalysisFixtures.cs
new file mode 100644
index 00000000..35d6bf2f
--- /dev/null
+++ b/tests/Titano.Core.Tests/Analysis/AnalysisFixtures.cs
@@ -0,0 +1,59 @@
+using Titano.Core.Analysis;
+using Titano.Core.Diagnostics.Synthetic;
+using Titano.Core.Imaging;
+
+namespace Titano.Core.Tests.Analysis;
+
+/// Shared measurement helpers for the analysis tests.
+internal static class AnalysisFixtures
+{
+ /// Trimmed-mean log2 luminance of every frame, optionally after applying a per-frame correction.
+ public static double[] MeasureSeries(SyntheticSequence sequence, Func? transform = null, float[]? mask = null)
+ {
+ var result = new double[sequence.Count];
+ Parallel.For(0, sequence.Count, new ParallelOptions { MaxDegreeOfParallelism = 2 }, i =>
+ {
+ using var image = sequence.Render(i);
+ var measured = transform is null ? image : transform(i, image);
+ result[i] = FrameStatistics.MeasureLogLuminance(measured, mask);
+ });
+ return result;
+ }
+
+ /// RMS of the frame-to-frame change of (series − truth): flicker relative to the true curve, free of
+ /// any constant offset.
+ public static double FrameToFrameResidualRms(IReadOnlyList series, IReadOnlyList truth)
+ {
+ double sum = 0;
+ for (var i = 1; i < series.Count; i++)
+ {
+ var d = series[i] - series[i - 1] - (truth[i] - truth[i - 1]);
+ sum += d * d;
+ }
+ return Math.Sqrt(sum / (series.Count - 1));
+ }
+
+ /// Largest |series − truth − c| where c is the mean offset (the measurement constant).
+ public static double MaxDeviation(IReadOnlyList series, IReadOnlyList truth)
+ {
+ var offset = 0.0;
+ for (var i = 0; i < series.Count; i++) offset += series[i] - truth[i];
+ offset /= series.Count;
+ var max = 0.0;
+ for (var i = 0; i < series.Count; i++) max = Math.Max(max, Math.Abs(series[i] - truth[i] - offset));
+ return max;
+ }
+
+ /// Land pixels at least rows below the true horizon (weight 1), else 0.
+ public static float[] TrueLandMask(SyntheticSequence sequence, double margin = 2)
+ {
+ var o = sequence.Options;
+ var mask = new float[o.Width * o.Height];
+ for (var y = 0; y < o.Height; y++)
+ {
+ for (var x = 0; x < o.Width; x++)
+ mask[y * o.Width + x] = y + 0.5 > sequence.HorizonRow(x + 0.5) + margin ? 1 : 0;
+ }
+ return mask;
+ }
+}
diff --git a/tests/Titano.Core.Tests/Analysis/FrameStatisticsTests.cs b/tests/Titano.Core.Tests/Analysis/FrameStatisticsTests.cs
new file mode 100644
index 00000000..c01652c3
--- /dev/null
+++ b/tests/Titano.Core.Tests/Analysis/FrameStatisticsTests.cs
@@ -0,0 +1,197 @@
+using System.Globalization;
+using Titano.Core.Analysis;
+using Titano.Core.Diagnostics.Synthetic;
+using Titano.Core.Imaging;
+using Titano.Core.Mathematics;
+using Titano.Testing;
+
+namespace Titano.Core.Tests.Analysis;
+
+public sealed class FrameStatisticsTests(TestContext context)
+{
+ ///
+ /// Gate: CCT within 100 K for Planckian colours from 2500 K to 10000 K, measured from images. The chromaticities
+ /// are exact blackbody values (Planck's law integrated against the CIE 1931 2° observer at 1 nm), independent of
+ /// the Krystek locus used by the estimator.
+ ///
+ [Theory]
+ [Case(2500, 0.476998, 0.413676)]
+ [Case(3000, 0.436934, 0.404075)]
+ [Case(3500, 0.405307, 0.390717)]
+ [Case(4000, 0.380442, 0.376749)]
+ [Case(5000, 0.345103, 0.351610)]
+ [Case(6000, 0.322085, 0.331755)]
+ [Case(6500, 0.313528, 0.323630)]
+ [Case(7500, 0.300336, 0.310268)]
+ [Case(8500, 0.290762, 0.299903)]
+ [Case(10000, 0.280634, 0.288289)]
+ public void ColourTemperatureOfPlanckianLightIsWithinOneHundredKelvin(int kelvin, double x, double y)
+ {
+ var rgb = Matrix3.XyzToRec709 * new Chromaticity(x, y).ToXyz(0.2);
+ using var image = new ImageBuffer(16, 16, 3);
+ image.Plane(0).Fill((float)rgb.X);
+ image.Plane(1).Fill((float)rgb.Y);
+ image.Plane(2).Fill((float)rgb.Z);
+ var estimate = Assert.NotNull(FrameStatistics.Measure(image).ColorTemperature);
+ context.Log(string.Create(CultureInfo.InvariantCulture,
+ $"{kelvin} K: estimate {estimate.Kelvin:F1} K (error {estimate.Kelvin - kelvin:F1}), raw McCamy {estimate.McCamyKelvin:F1} K, Duv {estimate.Duv:E2}"));
+ Assert.Approximately(kelvin, estimate.Kelvin, 100);
+ Assert.Less(Math.Abs(estimate.Duv), 2e-4);
+ }
+
+ [Test]
+ public void OffLocusColoursHaveNoTemperature()
+ {
+ Assert.Null(ColorTemperature.Estimate(0.1, 0.5, 0.1));
+ Assert.Null(ColorTemperature.Estimate(0.5, 0.1, 0.5));
+ Assert.Null(ColorTemperature.Estimate(0, 0, 0));
+ // 0.01 along the locus normal (towards green) keeps the CCT and stays within the ±0.02 validity band;
+ // 0.03 falls outside it.
+ var (u, v) = ColorTemperature.PlanckianUv(5000);
+ var (u1, v1) = ColorTemperature.PlanckianUv(4990);
+ var (u2, v2) = ColorTemperature.PlanckianUv(5010);
+ double nu = v1 - v2, nv = u2 - u1;
+ if (nv < 0) (nu, nv) = (-nu, -nv);
+ var length = Math.Sqrt(nu * nu + nv * nv);
+ Vector3D Tinted(double duv) => Matrix3.XyzToRec709 * Chromaticity.FromUv1960(u + duv * nu / length, v + duv * nv / length).ToXyz();
+ var green = Tinted(0.01);
+ var estimate = Assert.NotNull(ColorTemperature.Estimate(green.X, green.Y, green.Z));
+ Assert.Approximately(0.01, estimate.Duv, 1e-5);
+ Assert.Approximately(5000, estimate.Kelvin, 1);
+ var magenta = Tinted(-0.015);
+ Assert.Approximately(-0.015, Assert.NotNull(ColorTemperature.Estimate(magenta.X, magenta.Y, magenta.Z)).Duv, 1e-5);
+ var far = Tinted(0.03);
+ Assert.Null(ColorTemperature.Estimate(far.X, far.Y, far.Z));
+ }
+
+ [Test]
+ public void TrimmedLogMeanHistogramAndClipping()
+ {
+ // 1000 pixels: 900 at 2^-3, 50 crushed at zero, 50 clipped at 1.
+ using var image = new ImageBuffer(100, 10, 3);
+ for (var i = 0; i < 1000; i++)
+ {
+ var v = i < 50 ? 0f : i < 100 ? 1f : 0.125f;
+ for (var c = 0; c < 3; c++) image.Plane(c)[i] = v;
+ }
+ var stats = FrameStatistics.Measure(image);
+ Assert.Approximately(0.05, stats.ClipLowFraction, 1e-12);
+ Assert.Approximately(0.05, stats.ClipHighFraction, 1e-12);
+ Assert.Approximately(1, stats.Histogram.Sum(), 1e-12);
+ Assert.Approximately(0.9, stats.Histogram[(int)((-3 - FrameStatistics.HistogramMinEv) * 16)], 1e-12);
+ // Trimming 2 % per tail removes 20 of the 50 crushed and 20 of the 50 clipped pixels: (30·−14 + 900·−3 + 30·0) / 960.
+ Assert.Approximately((30 * -14.0 + 900 * -3.0) / 960, stats.MeanLogLuminance, 1e-9);
+ Assert.Approximately(0.05 + 0.9 * 0.125, stats.MeanGreen, 1e-6);
+ }
+
+ [Test]
+ public void LogMeanFollowsExposureExactly()
+ {
+ var sequence = SyntheticSequence.Create(new SyntheticSequenceOptions { FrameCount = 1 });
+ using var a = sequence.Render(0);
+ using var b = a.Clone();
+ ExposureProcessor.Apply(b, -1.37);
+ Assert.Approximately(-1.37, FrameStatistics.MeasureLogLuminance(b) - FrameStatistics.MeasureLogLuminance(a), 2e-3);
+ }
+
+ [Test]
+ public void MaskSelectsTheRegion()
+ {
+ using var image = new ImageBuffer(20, 20, 3);
+ var mask = new float[400];
+ for (var y = 0; y < 20; y++)
+ {
+ for (var x = 0; x < 20; x++)
+ {
+ var top = y < 10;
+ for (var c = 0; c < 3; c++) image[c, x, y] = top ? 0.5f : 0.0625f;
+ mask[y * 20 + x] = top ? 0 : 1;
+ }
+ }
+ var stats = FrameStatistics.Measure(image, mask);
+ Assert.Approximately(-4, stats.MeanLogLuminance, 1e-6);
+ Assert.Approximately(200, stats.Weight, 1e-9);
+ Assert.Approximately(-1, FrameStatistics.MeasureLogLuminance(image, mask.Select(m => 1 - m).ToArray()), 1e-6);
+ Assert.Throws(() => FrameStatistics.Measure(image, new float[3]));
+ }
+
+ [Test]
+ public void SharpnessDropsWhenBlurred()
+ {
+ var sequence = SyntheticSequence.Create(new SyntheticSequenceOptions { FrameCount = 1, Width = 64, Height = 48 });
+ using var sharp = sequence.Render(0);
+ using var blurred = sharp.Clone();
+ for (var c = 0; c < 3; c++)
+ {
+ var plane = blurred.Plane(c);
+ var source = plane.ToArray();
+ for (var y = 1; y < 47; y++)
+ {
+ for (var x = 1; x < 63; x++)
+ {
+ var sum = 0f;
+ for (var dy = -1; dy <= 1; dy++)
+ {
+ for (var dx = -1; dx <= 1; dx++) sum += source[(y + dy) * 64 + x + dx];
+ }
+ plane[y * 64 + x] = sum / 9;
+ }
+ }
+ }
+ Assert.Greater(FrameStatistics.Measure(sharp).Sharpness, 3 * FrameStatistics.Measure(blurred).Sharpness);
+ }
+
+ [Test]
+ public void ImmerkaerNoiseMatchesTheTrueSigma()
+ {
+ // Encoded-domain flat field 0.5 plus Gaussian noise of σ = 0.02 (the estimator works on sRGB-encoded luminance).
+ var random = new Random(17);
+ using var image = new ImageBuffer(128, 128, 1);
+ var plane = image.Plane(0);
+ for (var i = 0; i < plane.Length; i++)
+ {
+ var gaussian = Math.Sqrt(-2 * Math.Log(1 - random.NextDouble())) * Math.Cos(2 * Math.PI * random.NextDouble());
+ plane[i] = (float)ColorSpace.SrgbToLinear(0.5 + 0.02 * gaussian);
+ }
+ var stats = FrameStatistics.Measure(image);
+ Assert.Approximately(0.02, stats.Noise, 0.001);
+ Assert.Null(stats.ColorTemperature);
+ }
+
+ [Test]
+ public void DetectsBlackWhiteAndDuplicateFrames()
+ {
+ var sequence = SyntheticSequence.Create(new SyntheticSequenceOptions
+ {
+ FrameCount = 8,
+ FlickerEv = 0.1,
+ BlackFrames = [2],
+ WhiteFrames = [4],
+ DuplicateFrames = [6],
+ });
+ var stats = Enumerable.Range(0, 8).Select(i =>
+ {
+ using var image = sequence.Render(i);
+ return FrameStatistics.Measure(image);
+ }).ToArray();
+ Assert.SequenceEqual([2], Enumerable.Range(0, 8).Where(i => stats[i].IsBlack()));
+ Assert.SequenceEqual([4], Enumerable.Range(0, 8).Where(i => stats[i].IsWhite()));
+ Assert.SequenceEqual([6], Enumerable.Range(1, 7).Where(i => FrameStatistics.AreLikelyDuplicates(stats[i - 1], stats[i])));
+ }
+
+ [Test]
+ public void DownscaleAveragesBlocks()
+ {
+ using var image = new ImageBuffer(101, 60, 3);
+ for (var c = 0; c < 3; c++)
+ {
+ var plane = image.Plane(c);
+ for (var i = 0; i < plane.Length; i++) plane[i] = (i % 101) % 2 == 0 ? 0.2f : 0.4f;
+ }
+ using var small = AnalysisImage.Downscale(image, 32);
+ Assert.Equal((25, 15), (small.Width, small.Height));
+ Assert.True(small.Data.ToArray().All(v => Math.Abs(v - 0.3f) < 1e-6f));
+ using var same = AnalysisImage.Downscale(image, 200);
+ Assert.Equal(101, same.Width);
+ }
+}
diff --git a/tests/Titano.Core.Tests/Analysis/LightAnalyzerTests.cs b/tests/Titano.Core.Tests/Analysis/LightAnalyzerTests.cs
new file mode 100644
index 00000000..5873ce17
--- /dev/null
+++ b/tests/Titano.Core.Tests/Analysis/LightAnalyzerTests.cs
@@ -0,0 +1,196 @@
+using System.Diagnostics;
+using System.Globalization;
+using Titano.Core.Analysis;
+using Titano.Core.Diagnostics.Synthetic;
+using Titano.Core.Mathematics;
+using Titano.Testing;
+
+namespace Titano.Core.Tests.Analysis;
+
+public sealed class LightAnalyzerTests(TestContext context)
+{
+ private static SyntheticSequence Timeline() => SyntheticSequence.Create(new SyntheticSequenceOptions
+ {
+ FrameCount = 200,
+ IntervalSeconds = 10,
+ TimeShifts =
+ [
+ new(40, 60), // 70 s interval: gap
+ new(100, 5400), // 90 min: session break
+ new(150, -3600), // daylight saving ends: clock jump
+ new(195, 7200), // 2 h break leaving a 5-frame tail session
+ ],
+ DuplicateFrames = [60],
+ ExposureSteps =
+ [
+ new(50, 1.0 / 3, ExposureChange.Shutter),
+ new(120, -1, ExposureChange.Iso),
+ new(170, 0.5, ExposureChange.Aperture),
+ ],
+ });
+
+ [Test]
+ public void FindsSessionsGapsClockJumpsAndDuplicatesExactly()
+ {
+ var report = LightAnalyzer.Analyze(Timeline().LightFrames());
+
+ Assert.Equal(200, report.TimedFrameCount);
+ Assert.Equal(10.0, report.MedianIntervalSeconds);
+ Assert.Equal(0.0, report.JitterSeconds);
+ Assert.SequenceEqual([40, 100, 195], report.Gaps.Select(g => g.Index));
+ Assert.SequenceEqual([IntervalKind.Gap, IntervalKind.SessionBreak, IntervalKind.SessionBreak], report.Gaps.Select(g => g.Kind));
+ Assert.Approximately(70, report.Gaps[0].Seconds, 1e-9);
+
+ // The 5-frame tail merges into the previous session.
+ Assert.Equal(2, report.Sessions.Count);
+ Assert.Equal((0, 99), (report.Sessions[0].StartIndex, report.Sessions[0].EndIndex));
+ Assert.Equal((100, 199), (report.Sessions[1].StartIndex, report.Sessions[1].EndIndex));
+
+ Assert.SequenceEqual([(60, IntervalKind.Duplicate), (150, IntervalKind.ClockJump)], report.TimestampIssues.Select(t => (t.Index, t.Kind)));
+ Assert.Approximately(11050 + 3600, report.CaptureSpan.TotalSeconds, 1e-6);
+ Assert.Equal(report.AdjustedTimes[149]!.Value.AddSeconds(10), report.AdjustedTimes[150]!.Value);
+
+ var keys = report.Findings.Select(f => f.Key).ToList();
+ foreach (var key in new[] { FindingKeys.Gaps, FindingKeys.Sessions, FindingKeys.DuplicateTimestamps, FindingKeys.ClockJumps, FindingKeys.ExposureSteps })
+ Assert.Contains(key, keys);
+ foreach (var key in new[] { FindingKeys.NonMonotonicTimestamps, FindingKeys.CameraChanged, FindingKeys.MixedResolution, FindingKeys.IrregularInterval, FindingKeys.NoTimestamps })
+ Assert.DoesNotContain(key, keys);
+ var gaps = report.Findings.Single(f => f.Key == FindingKeys.Gaps);
+ Assert.Equal(FindingSeverity.Warning, gaps.Severity);
+ Assert.Equal(3, (int)gaps.Arguments[0]);
+ Assert.Approximately(7210, (double)gaps.Arguments[1], 1e-9);
+ }
+
+ [Test]
+ public void FindsExposureStepsWithTheirAmplitude()
+ {
+ var report = LightAnalyzer.Analyze(Timeline().LightFrames());
+ Assert.SequenceEqual([50, 120, 170], report.ExposureSteps.Select(s => s.Index));
+ Assert.SequenceEqual([ExposureChange.Shutter, ExposureChange.Iso, ExposureChange.Aperture], report.ExposureSteps.Select(s => s.Changes));
+ Assert.Approximately(1.0 / 3, report.ExposureSteps[0].DeltaEv, 1e-9);
+ Assert.Approximately(-1, report.ExposureSteps[1].DeltaEv, 1e-9);
+ Assert.Approximately(0.5, report.ExposureSteps[2].DeltaEv, 1e-9);
+ Assert.Equal(60.0, report.TypicalStepDistance);
+ Assert.Approximately(Math.Log2(64 / 0.01), report.ExposureValues[0]!.Value, 1e-9);
+ }
+
+ [Test]
+ public void SmallBackwardStepIsNonMonotonic()
+ {
+ var frames = Timeline().LightFrames().Take(30).ToList();
+ frames[10] = frames[10] with { CapturedAt = frames[10].CapturedAt!.Value.AddSeconds(-15) };
+ var report = LightAnalyzer.Analyze(frames);
+ Assert.SequenceEqual([(10, IntervalKind.NonMonotonic)], report.TimestampIssues.Select(t => (t.Index, t.Kind)));
+ Assert.Contains(FindingKeys.NonMonotonicTimestamps, report.Findings.Select(f => f.Key));
+ }
+
+ [Test]
+ public void ForwardHourJumpOnCadenceIsAClockChange()
+ {
+ var frames = Timeline().LightFrames().Take(40).Select((f, i) => i >= 20 ? f with { CapturedAt = f.CapturedAt!.Value.AddHours(1) } : f).ToList();
+ var report = LightAnalyzer.Analyze(frames);
+ Assert.SequenceEqual([(20, IntervalKind.ClockJump)], report.TimestampIssues.Select(t => (t.Index, t.Kind)));
+ Assert.Count(1, report.Sessions);
+ Assert.Approximately(390, report.CaptureSpan.TotalSeconds, 1e-6);
+ }
+
+ [Test]
+ public void ReportsIdentityResolutionAndOrientationChanges()
+ {
+ var frames = Timeline().LightFrames().Take(100).ToList();
+ frames[30] = frames[30] with { CameraModel = "Other" };
+ for (var i = 80; i < 100; i++) frames[i] = frames[i] with { Lens = "Zoom 70-200" };
+ frames[10] = frames[10] with { Width = 50 };
+ frames[11] = frames[11] with { Orientation = 6 };
+ frames[12] = frames[12] with { Lens = null, CameraMake = null, CameraModel = null };
+
+ var report = LightAnalyzer.Analyze(frames);
+ Assert.SequenceEqual([(30, IdentityKind.Camera), (31, IdentityKind.Camera), (80, IdentityKind.Lens)], report.IdentityChanges.Select(c => (c.Index, c.Kind)));
+ Assert.Equal("Titano Synthetic", report.IdentityChanges[1].After);
+ Assert.Equal((96, 64), report.DominantSize);
+ Assert.SequenceEqual([10, 11], report.ResolutionOutliers);
+ Assert.SequenceEqual([11], report.OrientationOutliers);
+ var keys = report.Findings.Select(f => f.Key).ToList();
+ foreach (var key in new[] { FindingKeys.CameraChanged, FindingKeys.LensChanged, FindingKeys.MixedResolution, FindingKeys.MixedOrientation })
+ Assert.Contains(key, keys);
+ }
+
+ [Test]
+ public void LabelsDayPhasesFromGps()
+ {
+ const double lat = 45.07, lon = 7.69;
+ var sequence = SyntheticSequence.Create(new SyntheticSequenceOptions
+ {
+ FrameCount = 240,
+ IntervalSeconds = 60,
+ Start = new DateTime(2024, 6, 21, 19, 0, 0),
+ UtcOffsetMinutes = 120,
+ Latitude = lat,
+ Longitude = lon,
+ });
+ var report = LightAnalyzer.Analyze(sequence.LightFrames());
+ var phases = report.DayPhases.Select(p => (int)Assert.NotNull(p)).ToList();
+ Assert.Monotonic(phases.Select(p => (double)p), decreasing: true);
+ Assert.Equal((int)DayPhase.Day, phases[0]);
+ Assert.LessOrEqual(phases[^1], (int)DayPhase.NauticalTwilight);
+
+ var sunset = SolarPosition.Events(new DateOnly(2024, 6, 21), lat, lon).Sunset!.Value.AddHours(2);
+ var firstTwilight = phases.FindIndex(p => p == (int)DayPhase.CivilTwilight);
+ var frameTime = new DateTime(2024, 6, 21, 19, 0, 0).AddMinutes(firstTwilight);
+ Assert.InRange((frameTime - sunset).TotalSeconds, 0, 60);
+ Assert.Contains(FindingKeys.DayNightTransition, report.Findings.Select(f => f.Key));
+ Assert.DoesNotContain(FindingKeys.TimeZoneEstimated, report.Findings.Select(f => f.Key));
+
+ // A GPS time stamp gives the same offset; without either the zone is estimated from the longitude.
+ var viaGps = LightAnalyzer.Analyze(sequence.LightFrames().Select(f => f with { UtcOffsetMinutes = null, GpsUtc = f.CapturedAt!.Value.AddHours(-2) }).ToList());
+ Assert.SequenceEqual(report.DayPhases, viaGps.DayPhases);
+ var estimated = LightAnalyzer.Analyze(sequence.LightFrames().Select(f => f with { UtcOffsetMinutes = null }).ToList());
+ var finding = estimated.Findings.Single(f => f.Key == FindingKeys.TimeZoneEstimated);
+ Assert.Equal(60, (int)finding.Arguments[0]);
+
+ var noGps = LightAnalyzer.Analyze(sequence.LightFrames().Select(f => f with { Latitude = null, Longitude = null }).ToList());
+ Assert.True(noGps.DayPhases.All(p => p is null));
+ }
+
+ [Test]
+ public void TenThousandFramesTakeWellUnderASecond()
+ {
+ var start = new DateTime(2024, 3, 1, 5, 0, 0);
+ var frames = Enumerable.Range(0, 10_000).Select(i => new LightFrame
+ {
+ Index = i,
+ CapturedAt = start.AddSeconds(i * 5 + (i >= 5000 ? 3600 : 0)),
+ UtcOffsetMinutes = 60,
+ ExposureTime = i < 4000 ? 1.0 / 500 : 1.0 / 250,
+ FNumber = 5.6,
+ Iso = 100,
+ Width = 6000,
+ Height = 4000,
+ CameraMake = "Maker",
+ CameraModel = "Body",
+ Lens = "Lens",
+ Latitude = 46.5,
+ Longitude = 11.3,
+ }).ToList();
+ LightAnalyzer.Analyze(frames.Take(100).ToList());
+ var watch = Stopwatch.StartNew();
+ var report = LightAnalyzer.Analyze(frames);
+ watch.Stop();
+ context.Log(string.Create(CultureInfo.InvariantCulture, $"10,000 frames analysed in {watch.Elapsed.TotalMilliseconds:F1} ms"));
+ Assert.Equal(10_000, report.DayPhases.Length);
+ Assert.Count(1, report.ExposureSteps);
+ Assert.Less(watch.Elapsed.TotalSeconds, 2);
+ }
+
+ [Test]
+ public void HandlesEmptyAndUntimedInput()
+ {
+ var empty = LightAnalyzer.Analyze(Array.Empty());
+ Assert.Equal(0, empty.FrameCount);
+ Assert.Empty(empty.Sessions);
+ var untimed = LightAnalyzer.Analyze(new[] { new LightFrame(), new LightFrame { Index = 1 } });
+ Assert.Contains(FindingKeys.NoTimestamps, untimed.Findings.Select(f => f.Key));
+ Assert.Null(untimed.MedianIntervalSeconds);
+ Assert.Count(1, untimed.Sessions);
+ }
+}
diff --git a/tests/Titano.Core.Tests/Analysis/SyntheticSequenceTests.cs b/tests/Titano.Core.Tests/Analysis/SyntheticSequenceTests.cs
new file mode 100644
index 00000000..8ed0539f
--- /dev/null
+++ b/tests/Titano.Core.Tests/Analysis/SyntheticSequenceTests.cs
@@ -0,0 +1,80 @@
+using Titano.Core.Analysis;
+using Titano.Core.Diagnostics.Synthetic;
+using Titano.Testing;
+
+namespace Titano.Core.Tests.Analysis;
+
+public sealed class SyntheticSequenceTests
+{
+ private static readonly SyntheticSequenceOptions Recipe = new()
+ {
+ FrameCount = 30,
+ Seed = 42,
+ StartEv = -1,
+ EndEv = 1,
+ FlickerEv = 0.1,
+ SkyFlickerEv = 0.05,
+ ExposureSteps = [new(10, -1), new(20, 0.5, ExposureChange.Aperture, Received: false)],
+ StartKelvin = 3000,
+ EndKelvin = 7000,
+ NoiseSigma = 0.001,
+ DuplicateFrames = [15],
+ Latitude = 45,
+ Longitude = 9,
+ };
+
+ [Test]
+ public void IsDeterministic()
+ {
+ var a = SyntheticSequence.Create(Recipe);
+ var b = SyntheticSequence.Create(Recipe);
+ Assert.SequenceEqual(a.FlickerEv, b.FlickerEv);
+ Assert.SequenceEqual(a.Frames.Select(f => f.Id), b.Frames.Select(f => f.Id));
+ foreach (var i in new[] { 0, 7, 29 })
+ {
+ using var x = a.Render(i);
+ using var y = b.Render(i);
+ using var again = a.Render(i);
+ Assert.True(x.Data.SequenceEqual(y.Data) && x.Data.SequenceEqual(again.Data), $"frame {i}");
+ }
+ var other = SyntheticSequence.Create(Recipe with { Seed = 43 });
+ Assert.False(other.FlickerEv.SequenceEqual(a.FlickerEv));
+ }
+
+ [Test]
+ public void MetadataMatchesTheRecipe()
+ {
+ var sequence = SyntheticSequence.Create(Recipe);
+ var ev = sequence.Frames.Select(f => f.ExposureValue!.Value).ToArray();
+ Assert.Approximately(-1, ev[10] - ev[9], 1e-9);
+ Assert.Approximately(0.5, ev[20] - ev[19], 1e-9);
+ Assert.Approximately(1, sequence.ExposureOffsetEv[10], 1e-9);
+ Assert.Approximately(1, sequence.ExposureOffsetEv[29], 1e-9);
+ Assert.Equal(sequence.Frames[14].CapturedAt, sequence.Frames[15].CapturedAt);
+ Assert.Equal(TimeSpan.FromSeconds(10), sequence.Frames[2].CapturedAt!.Value - sequence.Frames[1].CapturedAt!.Value);
+ Assert.Equal(45.0, sequence.Metadata[0].Gps!.Latitude);
+ Assert.Equal("Synthetic", sequence.LightFrames()[3].CameraModel);
+ }
+
+ [Test]
+ public void PixelsCarryTheTruthSeries()
+ {
+ var sequence = SyntheticSequence.Create(Recipe with { SkyFlickerEv = 0, NoiseSigma = 0, StartKelvin = 5000, EndKelvin = 5000 });
+ var measured = AnalysisFixtures.MeasureSeries(sequence);
+ var truth = sequence.SceneEv.Select((s, i) => s + sequence.ExposureOffsetEv[i] + sequence.FlickerEv[i]).ToArray();
+ Assert.Less(AnalysisFixtures.MaxDeviation(measured, truth), 2e-3);
+ Assert.Equal(measured[14], measured[15]);
+ }
+
+ [Test]
+ public void StarFieldIsDarkWithPointSources()
+ {
+ var sequence = SyntheticSequence.Create(new SyntheticSequenceOptions { FrameCount = 1, StarField = true, StarCount = 60, Width = 128, Height = 96 });
+ using var image = sequence.Render(0);
+ var stats = FrameStatistics.Measure(image);
+ Assert.Less(stats.MeanLogLuminance, -8);
+ var bright = image.Plane(1).ToArray().Count(v => v > 0.2f);
+ Assert.InRange(bright, 30, 100);
+ Assert.Throws(() => sequence.Render(1));
+ }
+}