using Titano.Core.Mathematics; using Titano.Core.Model; namespace Titano.Core.Analysis; /// /// Metadata-only sequence analysis run at import/scan (BRIEF ยง10.1): cadence, gaps and sessions, timestamp /// sanity, exposure series and steps, camera/lens identity, size and orientation consistency, and day phases /// from GPS. Linear in the number of frames apart from two medians; deterministic. /// public static class LightAnalyzer { private const double SameTimeSeconds = 0.001; private const double Hour = 3600; public static LightAnalysisReport Analyze(IReadOnlyList frames, LightAnalysisOptions? options = null) { ArgumentNullException.ThrowIfNull(frames); var light = new LightFrame[frames.Count]; for (var i = 0; i < light.Length; i++) light[i] = LightFrame.From(frames[i]); return Analyze(light, options); } public static LightAnalysisReport Analyze(IReadOnlyList frames, LightAnalysisOptions? options = null) { ArgumentNullException.ThrowIfNull(frames); options ??= LightAnalysisOptions.Default; if (!(options.GapFactor > 1)) throw new ArgumentOutOfRangeException(nameof(options), "GapFactor must exceed 1."); var findings = new List(); var timing = AnalyzeTiming(frames, options, findings); var exposure = AnalyzeExposure(frames, options, findings); var identity = AnalyzeIdentity(frames, findings); var (dominantSize, sizeOutliers, orientation, orientationOutliers) = AnalyzeGeometry(frames, findings); var phases = AnalyzeDayPhases(frames, timing.Adjusted, findings); return new LightAnalysisReport { FrameCount = frames.Count, TimedFrameCount = timing.TimedCount, MedianIntervalSeconds = timing.Median, JitterSeconds = timing.Jitter, FirstCapture = timing.First, LastCapture = timing.Last, CaptureSpan = timing.Span, AdjustedTimes = timing.Adjusted, Intervals = timing.Intervals, Gaps = timing.Intervals.Where(i => i.Kind is IntervalKind.Gap or IntervalKind.SessionBreak).ToList(), TimestampIssues = timing.Intervals.Where(i => i.Kind is IntervalKind.Duplicate or IntervalKind.NonMonotonic or IntervalKind.ClockJump).ToList(), Sessions = timing.Sessions, ExposureValues = exposure.Values, ExposureSteps = exposure.Steps, TypicalStepDistance = exposure.TypicalDistance, IdentityChanges = identity, DominantSize = dominantSize, ResolutionOutliers = sizeOutliers, DominantOrientation = orientation, OrientationOutliers = orientationOutliers, DayPhases = phases, Findings = findings, }; } private sealed record Timing( int TimedCount, double? Median, double? Jitter, DateTime? First, DateTime? Last, TimeSpan Span, DateTime?[] Adjusted, List Intervals, List Sessions); private static Timing AnalyzeTiming(IReadOnlyList frames, LightAnalysisOptions options, List findings) { var n = frames.Count; var sessionGap = options.SessionGapMinutes * 60; var raw = new List<(int Index, double Seconds)>(); int? previous = null; var timedCount = 0; for (var i = 0; i < n; i++) { if (frames[i].CapturedAt is not { } t) continue; timedCount++; if (previous is { } p) raw.Add((i, (t - frames[p].CapturedAt!.Value).TotalSeconds)); previous = i; } if (timedCount < 2 && n >= 2) findings.Add(new Finding(FindingKeys.NoTimestamps, FindingSeverity.Warning, [timedCount, n], [])); var cadence = raw.Where(d => d.Seconds > SameTimeSeconds && d.Seconds < sessionGap).Select(d => d.Seconds).ToArray(); if (cadence.Length == 0) cadence = raw.Where(d => d.Seconds > SameTimeSeconds).Select(d => d.Seconds).ToArray(); double? median = cadence.Length > 0 ? Statistics.Median(cadence) : null; double? jitter = null; if (median is { } m) { var regular = raw.Where(d => d.Seconds > SameTimeSeconds && d.Seconds <= options.GapFactor * m).Select(d => d.Seconds).ToArray(); jitter = regular.Length > 0 ? Statistics.MedianAbsoluteDeviation(regular) : 0; } var tolerance = median is { } med ? Math.Max(2, Math.Max(3 * Statistics.MadToSigma * (jitter ?? 0), 0.05 * med)) : 0; var intervals = new List(raw.Count); foreach (var (index, seconds) in raw) intervals.Add(new FrameInterval(index, seconds, Classify(seconds, median, tolerance, sessionGap, options.GapFactor))); // Clock-corrected timeline: jumps count as one cadence step, backward steps as none. var adjusted = new DateTime?[n]; var first = -1; var last = -1; for (var i = 0; i < n; i++) { if (frames[i].CapturedAt is null) continue; if (first < 0) first = i; last = i; } if (first >= 0) adjusted[first] = frames[first].CapturedAt; var previousTimed = first; foreach (var interval in intervals) { var advance = interval.Kind switch { IntervalKind.ClockJump => median ?? 0, IntervalKind.Duplicate or IntervalKind.NonMonotonic => 0, _ => interval.Seconds, }; adjusted[interval.Index] = adjusted[previousTimed]!.Value.AddSeconds(advance); previousTimed = interval.Index; } var span = first >= 0 ? adjusted[last]!.Value - adjusted[first]!.Value : TimeSpan.Zero; var sessions = BuildSessions(frames, intervals, options.MinimumSessionFrames); ReportTiming(intervals, sessions, median, jitter, options, findings); return new Timing(timedCount, median, jitter, first >= 0 ? frames[first].CapturedAt : null, last >= 0 ? frames[last].CapturedAt : null, span, adjusted, intervals, sessions); } private static IntervalKind Classify(double seconds, double? median, double tolerance, double sessionGap, double gapFactor) { if (Math.Abs(seconds) < SameTimeSeconds) return IntervalKind.Duplicate; if (median is not { } m) return seconds < 0 ? IntervalKind.NonMonotonic : IntervalKind.Regular; // A daylight-saving change shifts the clock by exactly one hour while the cadence continues. Longer // whole-hour pauses are left alone: scheduled intervalometer breaks look the same. var hours = Math.Round((seconds - m) / Hour); var hourAligned = Math.Abs(hours) == 1 && m < Hour / 2 && Math.Abs(seconds - m - hours * Hour) <= tolerance; if (seconds < 0) return hourAligned || -seconds > gapFactor * m ? IntervalKind.ClockJump : IntervalKind.NonMonotonic; if (hourAligned) return IntervalKind.ClockJump; if (seconds >= sessionGap) return IntervalKind.SessionBreak; return seconds > gapFactor * m ? IntervalKind.Gap : IntervalKind.Regular; } private static List BuildSessions(IReadOnlyList frames, List intervals, int minimumFrames) { var n = frames.Count; var ranges = new List<(int Start, int End)>(); if (n == 0) return []; var start = 0; foreach (var interval in intervals) { if (interval.Kind != IntervalKind.SessionBreak) continue; ranges.Add((start, interval.Index - 1)); start = interval.Index; } ranges.Add((start, n - 1)); for (var i = 0; i < ranges.Count && ranges.Count > 1;) { if (ranges[i].End - ranges[i].Start + 1 >= minimumFrames) { i++; continue; } if (i > 0) { ranges[i - 1] = (ranges[i - 1].Start, ranges[i].End); ranges.RemoveAt(i); } else { ranges[1] = (ranges[0].Start, ranges[1].End); ranges.RemoveAt(0); } } var sessions = new List(ranges.Count); foreach (var (s, e) in ranges) { DateTime? first = null, last = null; for (var i = s; i <= e; i++) { if (frames[i].CapturedAt is not { } t) continue; first ??= t; last = t; } sessions.Add(new CaptureSession(s, e, first, last)); } return sessions; } private static void ReportTiming(List intervals, List sessions, double? median, double? jitter, LightAnalysisOptions options, List findings) { var gaps = intervals.Where(i => i.Kind is IntervalKind.Gap or IntervalKind.SessionBreak).ToList(); if (gaps.Count > 0) findings.Add(new Finding(FindingKeys.Gaps, FindingSeverity.Warning, [gaps.Count, gaps.Max(g => g.Seconds)], Indices(gaps))); if (sessions.Count > 1) findings.Add(new Finding(FindingKeys.Sessions, FindingSeverity.Info, [sessions.Count], Cap(sessions.Select(s => s.StartIndex)))); if (median is { } m && jitter is { } j && j > options.IrregularIntervalFraction * m) findings.Add(new Finding(FindingKeys.IrregularInterval, FindingSeverity.Info, [j, m], [])); AddIssue(intervals, IntervalKind.Duplicate, FindingKeys.DuplicateTimestamps, findings); AddIssue(intervals, IntervalKind.NonMonotonic, FindingKeys.NonMonotonicTimestamps, findings); var jumps = intervals.Where(i => i.Kind == IntervalKind.ClockJump).ToList(); if (jumps.Count > 0) { var largest = jumps.MaxBy(i => Math.Abs(i.Seconds - (median ?? 0))); findings.Add(new Finding(FindingKeys.ClockJumps, FindingSeverity.Warning, [jumps.Count, largest.Seconds - (median ?? 0)], Indices(jumps))); } } private static void AddIssue(List intervals, IntervalKind kind, string key, List findings) { var issues = intervals.Where(i => i.Kind == kind).ToList(); if (issues.Count > 0) findings.Add(new Finding(key, FindingSeverity.Warning, [issues.Count], Indices(issues))); } private sealed record Exposure(double?[] Values, List Steps, double? TypicalDistance); private static Exposure AnalyzeExposure(IReadOnlyList frames, LightAnalysisOptions options, List findings) { var n = frames.Count; var values = new double?[n]; var steps = new List(); var missing = new List(); var logTolerance = Math.Log(1 + options.ExposureTolerance); var previous = -1; for (var i = 0; i < n; i++) { var f = frames[i]; values[i] = f.ExposureValue; if (values[i] is null) { missing.Add(i); continue; } if (previous >= 0) { var p = frames[previous]; var changes = ExposureChange.None; if (Math.Abs(Math.Log(f.ExposureTime!.Value / p.ExposureTime!.Value)) > logTolerance) changes |= ExposureChange.Shutter; if (Math.Abs(Math.Log(f.FNumber!.Value / p.FNumber!.Value)) > logTolerance) changes |= ExposureChange.Aperture; if ((f.Iso ?? 100) != (p.Iso ?? 100)) changes |= ExposureChange.Iso; if (changes != ExposureChange.None) steps.Add(new ExposureStep(i, changes, values[previous]!.Value, values[i]!.Value)); } previous = i; } double? typical = null; if (steps.Count >= 2) { var distances = new double[steps.Count - 1]; for (var i = 1; i < steps.Count; i++) distances[i - 1] = steps[i].Index - steps[i - 1].Index; typical = Statistics.Median(distances); } if (steps.Count > 0) { var total = steps.Sum(s => s.DeltaEv); findings.Add(new Finding(FindingKeys.ExposureSteps, FindingSeverity.Info, [steps.Count, typical ?? 0, total], Cap(steps.Select(s => s.Index)))); } if (missing.Count > 0 && n > 0) findings.Add(new Finding(FindingKeys.MissingExposure, FindingSeverity.Info, [missing.Count], Cap(missing))); return new Exposure(values, steps, typical); } private static List AnalyzeIdentity(IReadOnlyList frames, List findings) { var changes = new List(); string? camera = null, lens = null; for (var i = 0; i < frames.Count; i++) { var f = frames[i]; var body = Join(f.CameraMake, f.CameraModel, f.CameraSerial); if (body is not null) { if (camera is not null && !string.Equals(camera, body, StringComparison.Ordinal)) changes.Add(new IdentityChange(i, IdentityKind.Camera, camera, body)); camera = body; } var l = string.IsNullOrWhiteSpace(f.Lens) ? null : f.Lens.Trim(); if (l is not null) { if (lens is not null && !string.Equals(lens, l, StringComparison.Ordinal)) changes.Add(new IdentityChange(i, IdentityKind.Lens, lens, l)); lens = l; } } var bodyChanges = changes.Where(c => c.Kind == IdentityKind.Camera).Select(c => c.Index).ToList(); if (bodyChanges.Count > 0) findings.Add(new Finding(FindingKeys.CameraChanged, FindingSeverity.Warning, [bodyChanges.Count], Cap(bodyChanges))); var lensChanges = changes.Where(c => c.Kind == IdentityKind.Lens).Select(c => c.Index).ToList(); if (lensChanges.Count > 0) findings.Add(new Finding(FindingKeys.LensChanged, FindingSeverity.Warning, [lensChanges.Count], Cap(lensChanges))); return changes; } private static string? Join(params string?[] parts) { var present = parts.Where(p => !string.IsNullOrWhiteSpace(p)).Select(p => p!.Trim()).ToArray(); return present.Length == 0 ? null : string.Join(' ', present); } private static ((int, int)? Size, List SizeOutliers, int Orientation, List OrientationOutliers) AnalyzeGeometry(IReadOnlyList frames, List findings) { var sizes = new Dictionary<(int, int), int>(); var orientations = new Dictionary(); foreach (var f in frames) { if (f.Width > 0 && f.Height > 0) sizes[f.OrientedSize] = sizes.GetValueOrDefault(f.OrientedSize) + 1; orientations[f.Orientation] = orientations.GetValueOrDefault(f.Orientation) + 1; } // Dictionaries preserve first-insertion order here (no removals), so ties go to the first value seen. (int, int)? dominant = sizes.Count > 0 ? sizes.MaxBy(kv => kv.Value).Key : null; var orientation = orientations.Count > 0 ? orientations.MaxBy(kv => kv.Value).Key : 1; var sizeOutliers = new List(); var orientationOutliers = new List(); for (var i = 0; i < frames.Count; i++) { var f = frames[i]; if (dominant is { } d && f.Width > 0 && f.Height > 0 && f.OrientedSize != d) sizeOutliers.Add(i); if (f.Orientation != orientation) orientationOutliers.Add(i); } if (sizeOutliers.Count > 0 && dominant is { } ds) findings.Add(new Finding(FindingKeys.MixedResolution, FindingSeverity.Warning, [sizeOutliers.Count, ds.Item1, ds.Item2], Cap(sizeOutliers))); if (orientationOutliers.Count > 0) findings.Add(new Finding(FindingKeys.MixedOrientation, FindingSeverity.Warning, [orientationOutliers.Count], Cap(orientationOutliers))); return (dominant, sizeOutliers, orientation, orientationOutliers); } private static DayPhase?[] AnalyzeDayPhases(IReadOnlyList frames, DateTime?[] adjusted, List findings) { var n = frames.Count; var phases = new DayPhase?[n]; (double Lat, double Lon)? fallback = null; int? sequenceOffset = null; foreach (var f in frames) { fallback ??= Location(f); sequenceOffset ??= Offset(f); } if (fallback is not { } site) return phases; if (sequenceOffset is null) { // No recorded offset: assume the nominal zone of the longitude. sequenceOffset = (int)Math.Round(site.Lon / 15) * 60; findings.Add(new Finding(FindingKeys.TimeZoneEstimated, FindingSeverity.Info, [sequenceOffset.Value], [])); } int day = 0, twilight = 0, night = 0; for (var i = 0; i < n; i++) { if (adjusted[i] is not { } local) continue; var (lat, lon) = Location(frames[i]) ?? site; var utc = DateTime.SpecifyKind(local.AddMinutes(-(Offset(frames[i]) ?? sequenceOffset.Value)), DateTimeKind.Utc); var phase = SolarPosition.Phase(utc, lat, lon); phases[i] = phase; switch (phase) { case DayPhase.Day or DayPhase.GoldenHour: day++; break; case DayPhase.Night or DayPhase.AstronomicalTwilight: night++; break; default: twilight++; break; } } if (day > 0 && night > 0) findings.Add(new Finding(FindingKeys.DayNightTransition, FindingSeverity.Info, [day, twilight, night], [])); return phases; } private static (double, double)? Location(LightFrame f) => f.Latitude is { } lat && f.Longitude is { } lon && lat is >= -90 and <= 90 && lon is >= -180 and <= 180 && (lat != 0 || lon != 0) ? (lat, lon) : null; /// Recorded UTC offset, else the camera-clock minus GPS-time difference rounded to 15 minutes. private static int? Offset(LightFrame f) { if (f.UtcOffsetMinutes is { } recorded) return recorded; if (f.CapturedAt is not { } local || f.GpsUtc is not { } gps) return null; var minutes = (local - gps).TotalMinutes; return Math.Abs(minutes) <= 14 * 60 ? (int)Math.Round(minutes / 15) * 15 : null; } private static List Indices(List intervals) => Cap(intervals.Select(i => i.Index)); private static List Cap(IEnumerable indices) => indices.Take(Finding.MaxFrames).ToList(); }