From 353143b953f438588f58d5e328d3e2c09a620338 Mon Sep 17 00:00:00 2001 From: Claude Date: Fri, 2 Oct 2026 09:51:43 +0000 Subject: [PATCH] feat(diagnostics): add deterministic synthetic sequence generator Known-answer fixtures: brightness ramp, seeded global/sky/land flicker, metadata and pixel exposure steps, horizon split, colour temperature drift and white-balance jitter, star field, black/white/duplicate frames, gaps and clock shifts. Covers frame statistics (CCT against exact blackbody chromaticities) and the light analyzer with it. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_012iLMBNwBE2GnphAsu4cjaC --- .../Synthetic/SyntheticSequence.cs | 374 ++++++++++++++++++ .../Analysis/AnalysisFixtures.cs | 59 +++ .../Analysis/FrameStatisticsTests.cs | 197 +++++++++ .../Analysis/LightAnalyzerTests.cs | 196 +++++++++ .../Analysis/SyntheticSequenceTests.cs | 80 ++++ 5 files changed, 906 insertions(+) create mode 100644 src/Titano.Core/Diagnostics/Synthetic/SyntheticSequence.cs create mode 100644 tests/Titano.Core.Tests/Analysis/AnalysisFixtures.cs create mode 100644 tests/Titano.Core.Tests/Analysis/FrameStatisticsTests.cs create mode 100644 tests/Titano.Core.Tests/Analysis/LightAnalyzerTests.cs create mode 100644 tests/Titano.Core.Tests/Analysis/SyntheticSequenceTests.cs 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)); + } +}