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 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_012iLMBNwBE2GnphAsu4cjaC
This commit is contained in:
Claude committed 2026-10-02 09:51:43 +00:00
1 parent 3b3d7b7f6b
commit 353143b953
5 files changed
+906

No files matched your search

@@ -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;
/// <summary>A deliberate exposure change written to the metadata from frame <paramref name="Index"/> on; when
/// <paramref name="Received"/> is false the pixels ignore it (e.g. a setting the camera did not apply).</summary>
/// <param name="DeltaEv">Camera EV change (positive = less light; the pixels darken by this many stops).</param>
public sealed record SyntheticExposureStep(int Index, double DeltaEv, ExposureChange Change = ExposureChange.Shutter, bool Received = true);
/// <summary>Seconds added to the capture clock from frame <paramref name="Index"/> on (pauses, clock jumps).</summary>
public sealed record SyntheticTimeShift(int Index, double Seconds);
/// <summary>Recipe of a synthetic sequence; every field has a neutral default.</summary>
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;
/// <summary>Camera wall-clock time of the first frame.</summary>
public DateTime Start { get; init; } = new(2024, 6, 21, 19, 0, 0);
public int? UtcOffsetMinutes { get; init; } = 120;
public double IntervalSeconds { get; init; } = 10;
/// <summary>Uniform ± jitter of each capture time, in seconds.</summary>
public double IntervalJitterSeconds { get; init; }
public IReadOnlyList<SyntheticTimeShift> TimeShifts { get; init; } = [];
/// <summary>Scene brightness (EV) at the first and last frame; linear ramp in between.</summary>
public double StartEv { get; init; }
public double EndEv { get; init; }
/// <summary>Global flicker amplitude in EV: uniform in ±amplitude, or a sinusoid when a period is set.</summary>
public double FlickerEv { get; init; }
/// <summary>Period of sinusoidal flicker in frames; 0 = random flicker.</summary>
public double FlickerPeriodFrames { get; init; }
/// <summary>Extra independent uniform flicker of the sky region, in ±EV.</summary>
public double SkyFlickerEv { get; init; }
/// <summary>Extra independent uniform flicker of the land region, in ±EV.</summary>
public double LandFlickerEv { get; init; }
public IReadOnlyList<SyntheticExposureStep> ExposureSteps { get; init; } = [];
/// <summary>Horizon row at the centre column as a fraction of the height (sky above).</summary>
public double HorizonFraction { get; init; } = 0.45;
/// <summary>Horizon slope in rows per column.</summary>
public double HorizonTilt { get; init; }
/// <summary>Amplitude in rows of one sine period of horizon undulation across the width.</summary>
public double HorizonWave { get; init; }
/// <summary>Linear luminance of the sky (at the horizon) and of the average land pixel at 0 EV.</summary>
public double SkyLevel { get; init; } = 0.25;
public double LandLevel { get; init; } = 0.05;
/// <summary>Night sky: dark background with point stars instead of a bright gradient.</summary>
public bool StarField { get; init; }
public int StarCount { get; init; } = 40;
/// <summary>Correlated colour temperature of the light at the first and last frame (linear in mireds).</summary>
public double StartKelvin { get; init; } = 5500;
public double EndKelvin { get; init; } = 5500;
/// <summary>Uniform ± per-frame jitter of log2(R/G) and log2(B/G).</summary>
public double WhiteBalanceJitter { get; init; }
/// <summary>Additive Gaussian sensor noise (linear units) on every channel.</summary>
public double NoiseSigma { get; init; }
public IReadOnlyList<int> BlackFrames { get; init; } = [];
public IReadOnlyList<int> WhiteFrames { get; init; } = [];
/// <summary>Frames that repeat the previous frame exactly (pixels, capture time and settings).</summary>
public IReadOnlyList<int> 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; }
}
/// <summary>
/// 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: <c>base(x, y) · 2^(scene + exposure + flicker + regionFlicker) · rgb(kelvin)</c> with rgb at luminance 1,
/// so log-luminance shifts equal the truth series exactly.
/// </summary>
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<int>(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<Frame> Frames { get; }
public IReadOnlyList<FrameMetadata> Metadata { get; }
/// <summary>True scene brightness per frame (EV): the ramp.</summary>
public double[] SceneEv { get; }
/// <summary>Global flicker per frame (EV).</summary>
public double[] FlickerEv { get; }
public double[] SkyFlickerEv { get; }
public double[] LandFlickerEv { get; }
/// <summary>Luminance offset of the received exposure steps (EV).</summary>
public double[] ExposureOffsetEv { get; }
public double[] Kelvin { get; }
/// <summary>Per-frame white-balance jitter of log2(R/G) and log2(B/G).</summary>
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]);
/// <summary>Light-analysis input of every frame (with camera, lens and GPS).</summary>
public IReadOnlyList<LightFrame> LightFrames() => Metadata.Select((m, i) => LightFrame.From(m, i)).ToList();
/// <summary>Horizon position (rows from the top edge) at column centre <paramref name="x"/>.</summary>
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);
}
/// <summary>Renders frame <paramref name="index"/> (linear RGB); identical calls give identical pixels.</summary>
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);
}
/// <summary>Linear Rec.709 colour of the frame's light at luminance 1, with the white-balance jitter applied.</summary>
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);
/// <summary>Uniform [0, 1) from a SplitMix64 hash of the inputs (stable across processes, unlike HashCode).</summary>
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<byte> 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);
}
}
@@ -0,0 +1,59 @@
using Titano.Core.Analysis;
using Titano.Core.Diagnostics.Synthetic;
using Titano.Core.Imaging;
namespace Titano.Core.Tests.Analysis;
/// <summary>Shared measurement helpers for the analysis tests.</summary>
internal static class AnalysisFixtures
{
/// <summary>Trimmed-mean log2 luminance of every frame, optionally after applying a per-frame correction.</summary>
public static double[] MeasureSeries(SyntheticSequence sequence, Func<int, ImageBuffer, ImageBuffer>? 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;
}
/// <summary>RMS of the frame-to-frame change of (series − truth): flicker relative to the true curve, free of
/// any constant offset.</summary>
public static double FrameToFrameResidualRms(IReadOnlyList<double> series, IReadOnlyList<double> 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));
}
/// <summary>Largest |series − truth − c| where c is the mean offset (the measurement constant).</summary>
public static double MaxDeviation(IReadOnlyList<double> series, IReadOnlyList<double> 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;
}
/// <summary>Land pixels at least <paramref name="margin"/> rows below the true horizon (weight 1), else 0.</summary>
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;
}
}
@@ -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)
{
/// <summary>
/// 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.
/// </summary>
[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<ArgumentException>(() => 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);
}
}
@@ -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<LightFrame>());
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);
}
}
@@ -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<ArgumentOutOfRangeException>(() => sequence.Render(1));
}
}