From d8d25f187741da096d440979c0380c9a50c17843 Mon Sep 17 00:00:00 2001 From: Claude Date: Fri, 2 Oct 2026 10:52:08 +0000 Subject: [PATCH] feat(advisor): add recommendations, apply, optimise and sequence presets Rules for timing, frame rate, motion blur, deflicker, regions, holy-grail transitions, white balance, stabilisation, aspect, output size and export preset, each with a localisable reason and confidence; Apply fills Auto values without touching manual ones; Optimise takes per-section module decisions and reports changes; content-driven presets round-trip as JSON. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_012iLMBNwBE2GnphAsu4cjaC --- src/Titano.Core/Advisor/Advisor.cs | 91 ++++ src/Titano.Core/Advisor/AdvisorKeys.cs | 97 ++++ src/Titano.Core/Advisor/AdvisorRules.cs | 507 ++++++++++++++++++ src/Titano.Core/Advisor/AdvisorTypes.cs | 177 ++++++ src/Titano.Core/Advisor/ParameterBindings.cs | 137 +++++ src/Titano.Core/Advisor/SequencePresets.cs | 217 ++++++++ .../Advisor/AdvisorLocalizationTests.cs | 132 +++++ .../Titano.Core.Tests/Advisor/AdvisorTests.cs | 349 ++++++++++++ 8 files changed, 1707 insertions(+) create mode 100644 src/Titano.Core/Advisor/Advisor.cs create mode 100644 src/Titano.Core/Advisor/AdvisorKeys.cs create mode 100644 src/Titano.Core/Advisor/AdvisorRules.cs create mode 100644 src/Titano.Core/Advisor/AdvisorTypes.cs create mode 100644 src/Titano.Core/Advisor/ParameterBindings.cs create mode 100644 src/Titano.Core/Advisor/SequencePresets.cs create mode 100644 tests/Titano.Core.Tests/Advisor/AdvisorLocalizationTests.cs create mode 100644 tests/Titano.Core.Tests/Advisor/AdvisorTests.cs diff --git a/src/Titano.Core/Advisor/Advisor.cs b/src/Titano.Core/Advisor/Advisor.cs new file mode 100644 index 00000000..40eca224 --- /dev/null +++ b/src/Titano.Core/Advisor/Advisor.cs @@ -0,0 +1,91 @@ +using System.Globalization; +using Titano.Core.Analysis; +using Titano.Core.Analysis.Deep; +using Titano.Core.Localization; +using Titano.Core.Project; + +namespace Titano.Core.Advisor; + +/// +/// The analysis advisor (BRIEF §10.3, §10.4): turns the light and deep analyses into explained recommendations +/// (), stores them as Auto values without touching manual ones (), and takes +/// the heavier per-section decisions on request (). Deterministic; every reason is a resource +/// key plus arguments. +/// +public static class Advisor +{ + /// + /// Recommendations for every parameter the rules cover (see ), in section order, plus + /// every finding of both analyses. Without a deep report, pixel-based parameters get missing-data recommendations. + /// + public static AdvisorResult Recommend(LightAnalysisReport light, DeepAnalysisReport? deep, SequenceContext context) + { + ArgumentNullException.ThrowIfNull(light); + ArgumentNullException.ThrowIfNull(context); + var findings = new List(light.Findings); + if (deep is not null) findings.AddRange(deep.Findings.Select(f => f.ToFinding())); + return new AdvisorResult(new AdvisorRules(light, deep, context).Run(), findings); + } + + /// + /// Fills , and of every + /// advised parameter. Manual values stay in force; missing data changes no value (its reason is stored only where no + /// advice exists yet). Plain, non-Auto settings are left to . + /// + public static ProjectSettings Apply(ProjectSettings settings, AdvisorResult result) + { + ArgumentNullException.ThrowIfNull(settings); + ArgumentNullException.ThrowIfNull(result); + foreach (var recommendation in result.Recommendations) + { + if (ParameterBindings.Find(recommendation.Parameter)?.Advise is { } advise) settings = advise(settings, recommendation); + } + return settings; + } + + /// + /// "Optimise section" (BRIEF §10.4): applies the section's advice, returns module switches (deflicker, regions, holy + /// grail, white balance, motion blur, stabilisation, timing mode, export preset) to Auto where the advice differs + /// from the value in force, and takes the plain decisions (fit-to duration, hero frame when unset, exclusions added + /// to the user's, crop placement when centred, output size cap). Missing data changes nothing. + /// Returns every effective value that changed, with its reason. + /// + public static OptimiseResult Optimise(AdvisorSection section, ProjectSettings settings, AdvisorResult result) + { + ArgumentNullException.ThrowIfNull(settings); + ArgumentNullException.ThrowIfNull(result); + var optimised = settings; + var changes = new List(); + foreach (var binding in ParameterBindings.All) + { + if (binding.Section != section || result.Find(binding.Parameter) is not { } recommendation) continue; + if (binding.Advise is { } advise) optimised = advise(optimised, recommendation); + if (recommendation.Value is null) continue; + if (binding.IsModuleSwitch && !ParameterBindings.SameValue(binding.Effective(optimised), recommendation.Value)) optimised = binding.ResetToAuto!(optimised); + if (binding.Set is { } set) optimised = set(optimised, recommendation); + var before = binding.Effective(settings); + var after = binding.Effective(optimised); + if (!ParameterBindings.SameValue(before, after)) + changes.Add(new SettingChange(binding.Parameter, before, after, recommendation.ReasonKey, recommendation.ReasonArgs)); + } + return new OptimiseResult(optimised, changes); + } + + /// Localised text of a recommendation in the current UI culture. + public static string Explain(Recommendation recommendation) + { + ArgumentNullException.ThrowIfNull(recommendation); + return Loc.L(recommendation.ReasonKey, [.. recommendation.ReasonArgs]); + } + + /// + /// Localised text of a stored reason (/): numeric + /// arguments, stored culture-neutral, are parsed back so they format with the current culture. + /// + public static string Explain(string reasonKey, IReadOnlyList? reasonArgs) + { + ArgumentNullException.ThrowIfNull(reasonKey); + var args = (reasonArgs ?? []).Select(a => double.TryParse(a, NumberStyles.Float, CultureInfo.InvariantCulture, out var number) ? (object)number : a).ToArray(); + return Loc.L(reasonKey, args); + } +} diff --git a/src/Titano.Core/Advisor/AdvisorKeys.cs b/src/Titano.Core/Advisor/AdvisorKeys.cs new file mode 100644 index 00000000..26688e9a --- /dev/null +++ b/src/Titano.Core/Advisor/AdvisorKeys.cs @@ -0,0 +1,97 @@ +namespace Titano.Core.Advisor; + +/// +/// Resource keys (area Advisor) of the advisor's reasons, missing-data notes and sequence presets. Each key is +/// written through LocKey(…) so Titano.Tools i18n check verifies it exists in every required culture; +/// the resx comment of each key says what its placeholders hold. +/// +public static class AdvisorKeys +{ + /// Every missing-data key starts with this; such a reason never carries a value. + public const string MissingPrefix = "Advisor.Missing."; + + public static string MissingTimestamps { get; } = LocKey("Advisor.Missing.Timestamps"); + public static string MissingExposure { get; } = LocKey("Advisor.Missing.Exposure"); + public static string MissingDeep { get; } = LocKey("Advisor.Missing.Deep"); + public static string MissingMotion { get; } = LocKey("Advisor.Missing.Motion"); + public static string MissingShake { get; } = LocKey("Advisor.Missing.Shake"); + public static string MissingSourceSize { get; } = LocKey("Advisor.Missing.SourceSize"); + + public static string TimingSessions { get; } = LocKey("Advisor.Reason.Timing.Sessions"); + public static string TimingIrregular { get; } = LocKey("Advisor.Reason.Timing.Irregular"); + public static string TimingSparseGapsSmooth { get; } = LocKey("Advisor.Reason.Timing.SparseGapsSmooth"); + public static string TimingSparseGaps { get; } = LocKey("Advisor.Reason.Timing.SparseGaps"); + public static string TimingManyGaps { get; } = LocKey("Advisor.Reason.Timing.ManyGaps"); + public static string TimingRegular { get; } = LocKey("Advisor.Reason.Timing.Regular"); + + public static string FrameRateFit { get; } = LocKey("Advisor.Reason.FrameRate.Fit"); + public static string FrameRateShort { get; } = LocKey("Advisor.Reason.FrameRate.Short"); + public static string FrameRateLong { get; } = LocKey("Advisor.Reason.FrameRate.Long"); + public static string FrameRateSessions { get; } = LocKey("Advisor.Reason.FrameRate.Sessions"); + public static string FrameRateFastMotion { get; } = LocKey("Advisor.Reason.FrameRate.FastMotion"); + public static string FrameRateCinematic { get; } = LocKey("Advisor.Reason.FrameRate.Cinematic"); + public static string FrameRateDefault { get; } = LocKey("Advisor.Reason.FrameRate.Default"); + public static string FitToSeconds { get; } = LocKey("Advisor.Reason.FitToSeconds"); + + public static string ShutterAngle { get; } = LocKey("Advisor.Reason.ShutterAngle"); + public static string MotionBlurOn { get; } = LocKey("Advisor.Reason.MotionBlur.On"); + public static string MotionBlurAlready { get; } = LocKey("Advisor.Reason.MotionBlur.Already"); + public static string MotionBlurLittle { get; } = LocKey("Advisor.Reason.MotionBlur.Little"); + public static string FlowBest { get; } = LocKey("Advisor.Reason.Flow.Best"); + public static string FlowBalanced { get; } = LocKey("Advisor.Reason.Flow.Balanced"); + public static string StabilizeOn { get; } = LocKey("Advisor.Reason.Stabilize.On"); + public static string StabilizeHighCrop { get; } = LocKey("Advisor.Reason.Stabilize.HighCrop"); + public static string StabilizeOff { get; } = LocKey("Advisor.Reason.Stabilize.Off"); + public static string StabilizeSmoothing { get; } = LocKey("Advisor.Reason.Stabilize.Smoothing"); + + public static string DeflickerOn { get; } = LocKey("Advisor.Reason.Deflicker.On"); + public static string DeflickerOff { get; } = LocKey("Advisor.Reason.Deflicker.Off"); + public static string WindowPeriod { get; } = LocKey("Advisor.Reason.Window.Period"); + public static string WindowCorrelation { get; } = LocKey("Advisor.Reason.Window.Correlation"); + public static string WindowMinimum { get; } = LocKey("Advisor.Reason.Window.Minimum"); + public static string WindowMaximum { get; } = LocKey("Advisor.Reason.Window.Maximum"); + public static string StrengthFull { get; } = LocKey("Advisor.Reason.Strength.Full"); + public static string StrengthPartial { get; } = LocKey("Advisor.Reason.Strength.Partial"); + public static string RegionsHorizon { get; } = LocKey("Advisor.Reason.Regions.Horizon"); + public static string RegionsLuminance { get; } = LocKey("Advisor.Reason.Regions.Luminance"); + public static string RegionsOff { get; } = LocKey("Advisor.Reason.Regions.Off"); + public static string HolyGrailReceived { get; } = LocKey("Advisor.Reason.HolyGrail.Received"); + public static string HolyGrailNotReceived { get; } = LocKey("Advisor.Reason.HolyGrail.NotReceived"); + public static string HolyGrailNone { get; } = LocKey("Advisor.Reason.HolyGrail.None"); + public static string HolyGrailMetadata { get; } = LocKey("Advisor.Reason.HolyGrail.Metadata"); + public static string TransitionSpacing { get; } = LocKey("Advisor.Reason.Transition.Spacing"); + public static string TransitionSingle { get; } = LocKey("Advisor.Reason.Transition.Single"); + public static string WhiteBalanceOn { get; } = LocKey("Advisor.Reason.WhiteBalance.On"); + public static string WhiteBalanceOff { get; } = LocKey("Advisor.Reason.WhiteBalance.Off"); + + public static string AspectLandscape { get; } = LocKey("Advisor.Reason.Aspect.Landscape"); + public static string AspectWide { get; } = LocKey("Advisor.Reason.Aspect.Wide"); + public static string AspectNative { get; } = LocKey("Advisor.Reason.Aspect.Native"); + public static string AspectPortrait { get; } = LocKey("Advisor.Reason.Aspect.Portrait"); + public static string FramingHorizon { get; } = LocKey("Advisor.Reason.Framing.Horizon"); + + public static string Hero { get; } = LocKey("Advisor.Reason.Hero"); + public static string Exclude { get; } = LocKey("Advisor.Reason.Exclude"); + + public static string ResolutionSource { get; } = LocKey("Advisor.Reason.Resolution.Source"); + public static string ResolutionPreview { get; } = LocKey("Advisor.Reason.Resolution.Preview"); + public static string ResolutionCodec { get; } = LocKey("Advisor.Reason.Resolution.Codec"); + public static string ExportNight { get; } = LocKey("Advisor.Reason.Export.Night"); + public static string ExportStandard { get; } = LocKey("Advisor.Reason.Export.Standard"); + public static string ExportVertical { get; } = LocKey("Advisor.Reason.Export.Vertical"); + + public static string PresetNightSky { get; } = LocKey("Advisor.Preset.NightSky"); + public static string PresetNightSkyStabilised { get; } = LocKey("Advisor.Preset.NightSkyStabilised"); + public static string PresetHolyGrail { get; } = LocKey("Advisor.Preset.HolyGrail"); + public static string PresetConstruction { get; } = LocKey("Advisor.Preset.Construction"); + public static string PresetSocialVertical { get; } = LocKey("Advisor.Preset.SocialVertical"); + public static string PresetStandard { get; } = LocKey("Advisor.Preset.Standard"); + public static string PresetReasonNightSky { get; } = LocKey("Advisor.PresetReason.NightSky"); + public static string PresetReasonHolyGrail { get; } = LocKey("Advisor.PresetReason.HolyGrail"); + public static string PresetReasonConstruction { get; } = LocKey("Advisor.PresetReason.Construction"); + public static string PresetReasonSocialVertical { get; } = LocKey("Advisor.PresetReason.SocialVertical"); + public static string PresetReasonStandard { get; } = LocKey("Advisor.PresetReason.Standard"); + + /// Identity function that marks a literal as a resource key for the i18n check. + private static string LocKey(string key) => key; +} diff --git a/src/Titano.Core/Advisor/AdvisorRules.cs b/src/Titano.Core/Advisor/AdvisorRules.cs new file mode 100644 index 00000000..4c3888ab --- /dev/null +++ b/src/Titano.Core/Advisor/AdvisorRules.cs @@ -0,0 +1,507 @@ +using System.Globalization; +using Titano.Core.Analysis; +using Titano.Core.Analysis.Deep; +using Titano.Core.Export; +using Titano.Core.Imaging.Geometry; +using Titano.Core.Project; +using Titano.Core.Video; + +namespace Titano.Core.Advisor; + +/// +/// The recommendation rules of BRIEF §10.3, one method per parameter group. Output size is decided first because +/// shake and motion are judged in output pixels: deep-analysis pixels (source resolution) are scaled by output long +/// edge / source long edge. Every rule states its thresholds; missing inputs yield a null value with a +/// reason. +/// +internal sealed class AdvisorRules +{ + /// Visible shake threshold in output pixels (BRIEF §10.3). + public const double ShakeThresholdPx = 0.3; + + /// Film-look target shutter angle in degrees. + public const double TargetShutterAngle = 180; + + /// Path smoothing σ in frames (as StabilizerOptions.SmoothingSigma). + public const double StabilizeSigma = 12; + + private const double RegionConfidence = 0.6; + private const double StrongFlickerEv = 0.08; + private const double CropCostLimit = 0.15; + + private static readonly (int Width, int Height)[] Landscape = [(3840, 2160), (2560, 1440), (1920, 1080), (1280, 720)]; + private static readonly (int Width, int Height)[] Portrait = [(1080, 1920), (720, 1280)]; + + private readonly LightAnalysisReport _light; + private readonly DeepAnalysisReport? _deep; + private readonly SequenceContext _context; + private readonly List _result = []; + private readonly int _frames; + private readonly (int Width, int Height) _source; + private (int Width, int Height) _output; + private TimingMode? _timing; + + public AdvisorRules(LightAnalysisReport light, DeepAnalysisReport? deep, SequenceContext context) + { + _light = light; + _deep = deep; + _context = context; + _frames = context.FrameCount > 0 ? context.FrameCount : light.FrameCount; + _source = context.SourceWidth > 0 && context.SourceHeight > 0 + ? (context.SourceWidth, context.SourceHeight) + : light.DominantSize ?? (deep is { SourceWidth: > 0, SourceHeight: > 0 } ? (deep.SourceWidth, deep.SourceHeight) : (0, 0)); + } + + public List Run() + { + Export(); + Frames(); + Timing(); + Exposure(); + Motion(); + Camera(); + return [.. _result.OrderBy(r => r.Section)]; + } + + /// Converts deep-analysis pixels (source resolution) to output pixels. + private double ToOutput(double sourcePixels) + { + var deepLong = _deep is { SourceWidth: > 0, SourceHeight: > 0 } d ? int.Max(d.SourceWidth, d.SourceHeight) : _deep?.AnalysisLongEdge ?? 0; + var outputLong = int.Max(_output.Width, _output.Height); + return deepLong > 0 && outputLong > 0 ? sourcePixels * outputLong / deepLong : sourcePixels; + } + + private void Add(AdvisorSection section, string parameter, object? value, double confidence, string reason, params object[] args) => + _result.Add(new Recommendation(section, parameter, value, value is null ? 0 : double.Round(confidence, 2), reason, args)); + + private void Missing(AdvisorSection section, string parameter, string reason, params object[] args) => Add(section, parameter, null, 0, reason, args); + + /// + /// Output size and preset: standard 16:9 sizes (9:16 for portrait sources; 4K UHD at most) are tried from the + /// largest that fits inside the source cropped to that aspect — or inside the embedded previews when frames decode + /// only as previews — downwards, and the first whose preset the encoders can produce wins. Preset per size: 10-bit + /// HEVC archive for star fields and night skies (dark gradients band in 8 bit), HEVC, then H.264 at 4K; the H.264 + /// preset of the size below 4K; vertical social for portrait sources. + /// + private void Export() + { + if (_source.Width <= 0 || _source.Height <= 0) + { + Missing(AdvisorSection.Export, AdvisorParameters.Resolution, AdvisorKeys.MissingSourceSize); + Missing(AdvisorSection.Export, AdvisorParameters.ExportPreset, AdvisorKeys.MissingSourceSize); + return; + } + var portrait = _source.Height > _source.Width; + var ratio = portrait ? 9.0 / 16 : 16.0 / 9; + var cap = Fit(_source.Width, _source.Height, ratio); + var reason = AdvisorKeys.ResolutionSource; + object[] args = [_source.Width, _source.Height]; + if (_context is { PreviewOnlyCount: > 0, PreviewWidth: > 0, PreviewHeight: > 0 }) + { + var preview = Fit(_context.PreviewWidth, _context.PreviewHeight, ratio); + if (preview.Width < cap.Width) + { + cap = preview; + reason = AdvisorKeys.ResolutionPreview; + args = [_context.PreviewOnlyCount, _context.PreviewWidth, _context.PreviewHeight]; + } + } + + var sizes = (portrait ? Portrait : Landscape).Where(s => s.Width <= cap.Width && s.Height <= cap.Height).ToList(); + if (sizes.Count == 0) sizes.Add((int.Max(2, cap.Width & ~1), int.Max(2, cap.Height & ~1))); + EncoderCapability? limiting = null; + foreach (var size in sizes) + { + foreach (var (preset, key) in Candidates(size, portrait)) + { + var codec = ExportPresets.Find(preset)!.Codec; + if (!Fits(codec, size, out var capability)) + { + limiting ??= capability; + continue; + } + _output = size; + if (limiting is not null) + { + reason = AdvisorKeys.ResolutionCodec; + args = [limiting.Name, limiting.MaxWidth, limiting.MaxHeight]; + } + Add(AdvisorSection.Export, AdvisorParameters.Resolution, ParameterBindings.Size(size.Width, size.Height), 0.9, reason, args); + if (key == AdvisorKeys.ExportStandard) Add(AdvisorSection.Export, AdvisorParameters.ExportPreset, preset, 0.7, key, size.Width, size.Height); + else Add(AdvisorSection.Export, AdvisorParameters.ExportPreset, preset, key == AdvisorKeys.ExportNight ? 0.8 : 0.7, key); + return; + } + } + // No listed encoder can produce any standard size: keep the source-derived size and leave the preset alone. + _output = sizes[0]; + Add(AdvisorSection.Export, AdvisorParameters.Resolution, ParameterBindings.Size(_output.Width, _output.Height), 0.5, reason, args); + } + + /// Presets for one output size in order of preference, with the reason each one carries. + private IEnumerable<(string Preset, string Reason)> Candidates((int Width, int Height) size, bool portrait) + { + if (portrait) + { + yield return ("vertical-1080x1920", AdvisorKeys.ExportVertical); + yield break; + } + if (size.Width >= 3840) + { + if (IsNightSky() && HasTenBitHevc()) yield return ("4k-hevc10-archive", AdvisorKeys.ExportNight); + yield return ("4k-hevc", AdvisorKeys.ExportStandard); + yield return ("4k-h264", AdvisorKeys.ExportStandard); + } + else if (size.Width >= 2560) yield return ("1440p-h264", AdvisorKeys.ExportStandard); + else if (size.Width >= 1920) yield return ("1080p-h264", AdvisorKeys.ExportStandard); + else yield return ("720p-preview", AdvisorKeys.ExportStandard); + } + + /// Whether an encoder for handles the size (either orientation); with no + /// capability list everything fits. is the codec's largest capability, if any. + private bool Fits(VideoCodec codec, (int Width, int Height) size, out EncoderCapability? largest) + { + largest = null; + if (_context.Codecs.Count == 0) return true; + var available = _context.Codecs.Where(c => c.Codec == codec).ToList(); + largest = available.MaxBy(c => (long)c.MaxWidth * c.MaxHeight); + return available.Any(c => c.MaxWidth <= 0 || c.MaxHeight <= 0 + || (size.Width <= c.MaxWidth && size.Height <= c.MaxHeight) + || (size.Height <= c.MaxWidth && size.Width <= c.MaxHeight)); + } + + /// Hero frame from the deep analysis; exclusion of undecodable, black, white and duplicate frames. + private void Frames() + { + if (_deep is null) + { + Missing(AdvisorSection.Frames, AdvisorParameters.Hero, AdvisorKeys.MissingDeep); + Missing(AdvisorSection.Frames, AdvisorParameters.Excluded, AdvisorKeys.MissingDeep); + return; + } + if (_deep.HeroIndex is { } hero) Add(AdvisorSection.Frames, AdvisorParameters.Hero, hero, 0.6, AdvisorKeys.Hero, hero + 1); + var excluded = _deep.Issues.Excludable(); + if (excluded.Length > 0) Add(AdvisorSection.Frames, AdvisorParameters.Excluded, excluded, 0.9, AdvisorKeys.Exclude, excluded.Length); + } + + /// + /// Timing mode, in order: several capture sessions (pauses ≥ the session gap) → Adaptive; jitter above 10 % of the + /// median interval → Adaptive; gaps that are sparse (≤ 2 % of intervals, each ≤ 10 × median) with smooth measured + /// motion (95th percentile ≤ 1 % of the long edge per frame) → Interpolated, or Constant when motion is unknown or + /// fast; denser gaps → Adaptive; otherwise Constant. Frame rate, in order: "fit to N s" target → the standard rate + /// nearest frames/N; under 240 frames → 24 (clip ≥ 10 s); over 10 min at 30 fps → 60; several sessions → 30; fast + /// motion (≥ 1 % of the long edge per frame) → 24; measured moderate motion (≥ 0.2 %) → 24; otherwise 30. + /// + private void Timing() + { + if (_light.MedianIntervalSeconds is not { } median) + { + Missing(AdvisorSection.Timing, AdvisorParameters.TimingMode, AdvisorKeys.MissingTimestamps, _light.TimedFrameCount, _light.FrameCount); + _timing = null; + } + else + { + ChooseTimingMode(median); + } + FrameRate(); + } + + private void ChooseTimingMode(double median) + { + var jitter = _light.JitterSeconds ?? 0; + var breaks = _light.Intervals.Where(i => i.Kind == IntervalKind.SessionBreak).ToList(); + var gaps = _light.Intervals.Where(i => i.Kind == IntervalKind.Gap).ToList(); + var section = AdvisorSection.Timing; + var parameter = AdvisorParameters.TimingMode; + if (_light.Sessions.Count >= 2 && breaks.Count > 0) + { + _timing = TimingMode.Adaptive; + Add(section, parameter, _timing, 0.85, AdvisorKeys.TimingSessions, _light.Sessions.Count, R(breaks.Max(b => b.Seconds) / 3600, 1)); + } + else if (jitter > 0.1 * median) + { + _timing = TimingMode.Adaptive; + Add(section, parameter, _timing, 0.7, AdvisorKeys.TimingIrregular, R(jitter, 2), R(median, 2)); + } + else if (gaps.Count > 0) + { + var sparse = gaps.Count <= double.Max(1, 0.02 * _light.Intervals.Count) && gaps.All(g => g.Seconds <= 10 * median); + var motion = MotionFraction(); + if (sparse && motion is <= 0.01) + { + _timing = TimingMode.Interpolated; + Add(section, parameter, _timing, 0.65, AdvisorKeys.TimingSparseGapsSmooth, gaps.Count, R(ToOutput(_deep!.Motion.P95Px!.Value), 1)); + } + else if (sparse) + { + _timing = TimingMode.Constant; + Add(section, parameter, _timing, 0.6, AdvisorKeys.TimingSparseGaps, gaps.Count); + } + else + { + _timing = TimingMode.Adaptive; + Add(section, parameter, _timing, 0.7, AdvisorKeys.TimingManyGaps, gaps.Count); + } + } + else + { + _timing = TimingMode.Constant; + Add(section, parameter, _timing, 0.9, AdvisorKeys.TimingRegular, R(median, 2), R(jitter, 2)); + } + } + + private void FrameRate() + { + var section = AdvisorSection.Timing; + var parameter = AdvisorParameters.FrameRate; + if (_frames <= 0) return; + double Seconds(int fps) => R((double)_frames / fps, 1); + var motion = MotionFraction(); + if (_context.TargetDurationSeconds is > 0 and var target) + { + var wanted = _frames / target; + var fps = new[] { 24, 25, 30, 60 }.MinBy(f => double.Abs(double.Log(f / wanted))); + Add(section, parameter, Rate(fps), 0.8, AdvisorKeys.FrameRateFit, _frames, R(target, 1), fps); + Add(section, AdvisorParameters.FitToSeconds, target, 0.8, AdvisorKeys.FitToSeconds, _frames, R(target, 1), fps); + } + else if (_frames < 240) Add(section, parameter, Rate(24), 0.7, AdvisorKeys.FrameRateShort, _frames, Seconds(24)); + else if (_frames > 30 * 600) Add(section, parameter, Rate(60), 0.6, AdvisorKeys.FrameRateLong, _frames, Seconds(60)); + else if (_light.Sessions.Count >= 2) Add(section, parameter, Rate(30), 0.7, AdvisorKeys.FrameRateSessions, Seconds(30)); + else if (motion >= 0.01) Add(section, parameter, Rate(24), 0.6, AdvisorKeys.FrameRateFastMotion, R(ToOutput(_deep!.Motion.P95Px!.Value), 1), Seconds(24)); + else if (motion >= 0.002) Add(section, parameter, Rate(24), 0.5, AdvisorKeys.FrameRateCinematic, R(ToOutput(_deep!.Motion.P95Px!.Value), 1), Seconds(24)); + else Add(section, parameter, Rate(30), 0.5, AdvisorKeys.FrameRateDefault, Seconds(30)); + } + + /// + /// Deflicker on when the step-free luminance deviates from its smooth curve by ≥ 0.02 EV RMS; window = the + /// spectrum's 4 × flicker period (or correlation length), odd, clamped to 15–151 (the reason says when it was + /// clamped); strength 1 for ≥ 0.08 EV, else 0.8. + /// Regions follow the mask method when its confidence is ≥ 0.6. Holy grail on when metadata exposure steps reached + /// the pixels (all metadata steps when pixels were not analysed); transition = half the median spacing of the + /// received steps (12 frames for a single step). White-balance smoothing on when the colour ratios jitter by + /// ≥ 0.01 log2 RMS around their smoothed course. + /// + private void Exposure() + { + HolyGrail(); + var section = AdvisorSection.Exposure; + if (_deep is null) + { + foreach (var p in new[] { AdvisorParameters.Deflicker, AdvisorParameters.DeflickerWindow, AdvisorParameters.DeflickerStrength, AdvisorParameters.Regions, AdvisorParameters.WhiteBalanceSmoothing }) + Missing(section, p, AdvisorKeys.MissingDeep); + return; + } + var flicker = _deep.Flicker; + var amplitude = R(flicker.AmplitudeEv, 3); + if (flicker.AmplitudeEv >= DeepSequenceAnalysis.VisibleFlickerEv) + Add(section, AdvisorParameters.Deflicker, true, double.Min(0.95, 0.5 + 10 * flicker.AmplitudeEv), AdvisorKeys.DeflickerOn, amplitude); + else Add(section, AdvisorParameters.Deflicker, false, 0.7, AdvisorKeys.DeflickerOff, amplitude); + var scale = flicker.PeriodFrames ?? flicker.CorrelationLength; + var window = flicker.RecommendedWindow; + if (4 * scale < FlickerSpectrumOptions.Default.MinimumWindow) Add(section, AdvisorParameters.DeflickerWindow, window, 0.6, AdvisorKeys.WindowMinimum, window); + else if (4 * scale > FlickerSpectrumOptions.Default.MaximumWindow) Add(section, AdvisorParameters.DeflickerWindow, window, 0.6, AdvisorKeys.WindowMaximum, R(scale, 1), window); + else if (flicker.PeriodFrames is not null) Add(section, AdvisorParameters.DeflickerWindow, window, 0.75, AdvisorKeys.WindowPeriod, R(scale, 1), window); + else Add(section, AdvisorParameters.DeflickerWindow, window, 0.6, AdvisorKeys.WindowCorrelation, R(scale, 1), window); + if (flicker.AmplitudeEv >= StrongFlickerEv) Add(section, AdvisorParameters.DeflickerStrength, 1.0, 0.6, AdvisorKeys.StrengthFull, amplitude); + else Add(section, AdvisorParameters.DeflickerStrength, 0.8, 0.6, AdvisorKeys.StrengthPartial, amplitude); + + if (_deep.Regions is not { } regions) Missing(section, AdvisorParameters.Regions, AdvisorKeys.MissingDeep); + else + { + var percent = R(100 * regions.Confidence, 0); + if (regions.Confidence < RegionConfidence) Add(section, AdvisorParameters.Regions, RegionMode.Off, 0.7, AdvisorKeys.RegionsOff, percent); + else if (regions.Method == RegionMethod.Horizon) Add(section, AdvisorParameters.Regions, RegionMode.Horizon, regions.Confidence, AdvisorKeys.RegionsHorizon, percent); + else Add(section, AdvisorParameters.Regions, RegionMode.Luminance, regions.Confidence, AdvisorKeys.RegionsLuminance, percent); + } + + var jitter = _deep.WhiteBalance.JitterLog2; + var jitterPercent = R(100 * (double.Exp2(jitter) - 1), 1); + if (jitter >= DeepSequenceAnalysis.VisibleWhiteBalanceJitter) Add(section, AdvisorParameters.WhiteBalanceSmoothing, true, 0.7, AdvisorKeys.WhiteBalanceOn, jitterPercent); + else Add(section, AdvisorParameters.WhiteBalanceSmoothing, false, 0.7, AdvisorKeys.WhiteBalanceOff, jitterPercent); + } + + private void HolyGrail() + { + var section = AdvisorSection.Exposure; + if (!_light.ExposureValues.Any(v => v is not null)) + { + Missing(section, AdvisorParameters.HolyGrail, AdvisorKeys.MissingExposure); + Missing(section, AdvisorParameters.TransitionLength, AdvisorKeys.MissingExposure); + return; + } + if (_deep is { Exposure: var exposure }) + { + if (exposure.MetadataSteps == 0) Add(section, AdvisorParameters.HolyGrail, false, 0.9, AdvisorKeys.HolyGrailNone); + else if (exposure.ReceivedSteps == 0) Add(section, AdvisorParameters.HolyGrail, false, 0.8, AdvisorKeys.HolyGrailNotReceived, exposure.MetadataSteps); + else + { + Add(section, AdvisorParameters.HolyGrail, true, 0.85, AdvisorKeys.HolyGrailReceived, exposure.ReceivedSteps); + Transition(exposure.TypicalSpacing, exposure.TransitionLength!.Value, 0.8); + } + return; + } + if (_light.ExposureSteps.Count == 0) + { + Add(section, AdvisorParameters.HolyGrail, false, 0.9, AdvisorKeys.HolyGrailNone); + return; + } + Add(section, AdvisorParameters.HolyGrail, true, 0.6, AdvisorKeys.HolyGrailMetadata, _light.ExposureSteps.Count); + var spacing = _light.TypicalStepDistance; + var length = spacing is { } s ? int.Max(2, (int)double.Round(s / 2)) : HolyGrailOptions.Default.SingleStepTransitionFrames; + Transition(spacing, length, 0.5); + } + + private void Transition(double? spacing, int length, double confidence) + { + if (spacing is { } s) Add(AdvisorSection.Exposure, AdvisorParameters.TransitionLength, length, confidence, AdvisorKeys.TransitionSpacing, R(s, 0), length); + else Add(AdvisorSection.Exposure, AdvisorParameters.TransitionLength, length, confidence, AdvisorKeys.TransitionSingle, length); + } + + /// + /// Target shutter angle 180° (film look); real angle = 360 × median exposure / median interval. Motion blur off when + /// the real angle already reaches the target or the moving content (95th-percentile flow, output pixels) moves + /// under 1 px per frame; otherwise on, adding √(180² − real²)/360 × motion px of trail. Flow quality Best for + /// interpolated timing (per-pixel vectors), else Balanced. Stabilisation on when the shake RMS exceeds 0.3 output + /// pixels (lower confidence when hiding it costs over 15 % of the frame); path smoothing σ = 12 frames. + /// + private void Motion() + { + var section = AdvisorSection.Motion; + var interval = _light.MedianIntervalSeconds; + var exposure = _context.MedianExposureSeconds; + if (interval is null) + { + Missing(section, AdvisorParameters.TargetShutterAngle, AdvisorKeys.MissingTimestamps, _light.TimedFrameCount, _light.FrameCount); + Missing(section, AdvisorParameters.MotionBlur, AdvisorKeys.MissingTimestamps, _light.TimedFrameCount, _light.FrameCount); + } + else if (exposure is null) + { + Missing(section, AdvisorParameters.TargetShutterAngle, AdvisorKeys.MissingExposure); + Missing(section, AdvisorParameters.MotionBlur, AdvisorKeys.MissingExposure); + } + else + { + var real = double.Min(360, 360 * exposure.Value / interval.Value); + Add(section, AdvisorParameters.TargetShutterAngle, TargetShutterAngle, 0.8, AdvisorKeys.ShutterAngle, R(real, 0), Significant(exposure.Value), R(interval.Value, 2)); + MotionBlur(real); + } + + var best = _timing == TimingMode.Interpolated; + Add(section, AdvisorParameters.FlowQuality, best ? FlowQualitySetting.Best : FlowQualitySetting.Balanced, 0.6, best ? AdvisorKeys.FlowBest : AdvisorKeys.FlowBalanced); + Stabilize(); + } + + private void MotionBlur(double real) + { + var section = AdvisorSection.Motion; + if (real >= TargetShutterAngle) + { + Add(section, AdvisorParameters.MotionBlur, false, 0.9, AdvisorKeys.MotionBlurAlready, R(real, 0), TargetShutterAngle); + return; + } + if (_deep is null) + { + Missing(section, AdvisorParameters.MotionBlur, AdvisorKeys.MissingDeep); + return; + } + if (_deep.Motion.P95Px is not { } p95) + { + Missing(section, AdvisorParameters.MotionBlur, AdvisorKeys.MissingMotion); + return; + } + var motion = ToOutput(p95); + if (motion < 1) + { + Add(section, AdvisorParameters.MotionBlur, false, 0.8, AdvisorKeys.MotionBlurLittle, R(motion, 1)); + return; + } + var trail = motion * double.Sqrt(TargetShutterAngle * TargetShutterAngle - real * real) / 360; + Add(section, AdvisorParameters.MotionBlur, true, 0.75, AdvisorKeys.MotionBlurOn, R(real, 0), R(motion, 1), TargetShutterAngle, R(trail, 1)); + } + + private void Stabilize() + { + var section = AdvisorSection.Motion; + if (_deep is null) + { + Missing(section, AdvisorParameters.Stabilize, AdvisorKeys.MissingDeep); + Missing(section, AdvisorParameters.StabilizeSmoothing, AdvisorKeys.MissingDeep); + return; + } + var shake = _deep.Shake; + if (shake.MeasuredFraction < 0.5) + { + Missing(section, AdvisorParameters.Stabilize, AdvisorKeys.MissingShake, R(100 * shake.MeasuredFraction, 0)); + return; + } + var rms = ToOutput(shake.RmsPx); + var crop = R(100 * shake.CropCost, 1); + if (rms <= ShakeThresholdPx) Add(section, AdvisorParameters.Stabilize, false, 0.8, AdvisorKeys.StabilizeOff, R(rms, 2)); + else if (shake.CropCost <= CropCostLimit) Add(section, AdvisorParameters.Stabilize, true, 0.8, AdvisorKeys.StabilizeOn, R(rms, 2), crop); + else Add(section, AdvisorParameters.Stabilize, true, 0.5, AdvisorKeys.StabilizeHighCrop, R(rms, 2), crop); + Add(section, AdvisorParameters.StabilizeSmoothing, StabilizeSigma, 0.6, AdvisorKeys.StabilizeSmoothing, StabilizeSigma); + } + + /// + /// Aspect 16:9 for landscape sources (the reason says how much height or width the crop keeps), 9:16 for portrait + /// ones. When a confident horizon exists and the crop gives up + /// height, the crop is placed so the horizon sits on the nearest third of the output frame (recommended only when the + /// placement moves at least a fifth of the slack away from centred). + /// + private void Camera() + { + var section = AdvisorSection.Camera; + if (_source.Width <= 0 || _source.Height <= 0) + { + Missing(section, AdvisorParameters.Aspect, AdvisorKeys.MissingSourceSize); + return; + } + if (_source.Height > _source.Width) + { + Add(section, AdvisorParameters.Aspect, "9:16", 0.7, AdvisorKeys.AspectPortrait); + return; + } + var ratio = (double)_source.Width / _source.Height / (16.0 / 9); + var kept = double.Min(1, ratio); + if (double.Abs(ratio - 1) < 0.01) Add(section, AdvisorParameters.Aspect, "16:9", 0.9, AdvisorKeys.AspectNative); + else if (ratio < 1) Add(section, AdvisorParameters.Aspect, "16:9", 0.7, AdvisorKeys.AspectLandscape, _source.Width, _source.Height, R(100 * ratio, 0)); + else Add(section, AdvisorParameters.Aspect, "16:9", 0.6, AdvisorKeys.AspectWide, _source.Width, _source.Height, R(100 / ratio, 0)); + + if (kept >= 0.99 || _deep?.Regions is not { Method: RegionMethod.Horizon, Confidence: >= RegionConfidence, Horizon: { Length: > 0 } horizon }) return; + var row = horizon.Average(); + var slack = 1 - kept; + var third = double.Abs(row - (slack / 2 + kept / 3)) <= double.Abs(row - (slack / 2 + 2 * kept / 3)) ? 1.0 / 3 : 2.0 / 3; + var top = double.Clamp(row - third * kept, 0, slack); + var offset = R(2 * top / slack - 1, 2); + if (double.Abs(offset) >= 0.2) Add(section, AdvisorParameters.OffsetY, offset, 0.5, AdvisorKeys.FramingHorizon, R(100 * row, 0)); + } + + /// Night content: a star field, or a sequence the deep analysis or GPS phases call night. + private bool IsNightSky() => _deep is { } d && (d.Sky.StarField || d.Sky.Light == DayNight.Night); + + /// Speed of moving content as a fraction of the frame's long edge per frame; null without motion data. + private double? MotionFraction() + { + if (_deep?.Motion.P95Px is not { } p95) return null; + var deepLong = _deep.SourceWidth > 0 ? int.Max(_deep.SourceWidth, _deep.SourceHeight) : _deep.AnalysisLongEdge; + return deepLong > 0 ? p95 / deepLong : null; + } + + private bool HasTenBitHevc() => _context.Codecs.Count == 0 || _context.Codecs.Any(c => c.Codec == VideoCodec.Hevc && c.SupportsTenBit); + + private static (int Width, int Height) Fit(int width, int height, double ratio) + { + var crop = AspectRatio.FitCrop(RectD.FromSize(width, height), ratio); + return ((int)double.Floor(crop.Width + 1e-9), (int)double.Floor(crop.Height + 1e-9)); + } + + private static string Rate(int fps) => fps.ToString(CultureInfo.InvariantCulture); + + private static double R(double value, int decimals) => double.Round(value, decimals, MidpointRounding.AwayFromZero); + + private static double Significant(double value) + { + if (!(value > 0)) return value; + var decimals = 2 - (int)double.Floor(double.Log10(value)); + return decimals is >= 0 and <= 15 ? R(value, decimals) : value; + } +} diff --git a/src/Titano.Core/Advisor/AdvisorTypes.cs b/src/Titano.Core/Advisor/AdvisorTypes.cs new file mode 100644 index 00000000..427dca10 --- /dev/null +++ b/src/Titano.Core/Advisor/AdvisorTypes.cs @@ -0,0 +1,177 @@ +using Titano.Core.Analysis; +using Titano.Core.Mathematics; +using Titano.Core.Model; +using Titano.Core.Project; +using Titano.Core.Video; + +namespace Titano.Core.Advisor; + +/// Sequence-editor section a recommendation belongs to (BRIEF §12.3). +public enum AdvisorSection +{ + Frames, + Timing, + Exposure, + Motion, + Camera, + + /// No automatic advice: a temporal median erases stars that move between frames, so stacking stays a user choice. + Stack, + + Export, +} + +/// +/// Stable ids of the parameters the advisor decides, named after their path. +/// Value types: see each constant. +/// +public static class AdvisorParameters +{ + /// frame index. + public const string Hero = "Frames.Hero"; + + /// [] frame indices to exclude. + public const string Excluded = "Frames.Excluded"; + + /// . + public const string TimingMode = "Timing.Mode"; + + /// frame rate ("24", "25", "30", "60"). + public const string FrameRate = "Timing.FrameRate"; + + /// seconds. + public const string FitToSeconds = "Timing.FitToSeconds"; + + /// . + public const string Deflicker = "Exposure.Deflicker"; + + /// frames (odd). + public const string DeflickerWindow = "Exposure.DeflickerWindow"; + + /// 0..1. + public const string DeflickerStrength = "Exposure.DeflickerStrength"; + + /// . + public const string Regions = "Exposure.Regions"; + + /// . + public const string HolyGrail = "Exposure.HolyGrail"; + + /// frames. + public const string TransitionLength = "Exposure.TransitionLength"; + + /// . + public const string WhiteBalanceSmoothing = "Exposure.WhiteBalanceSmoothing"; + + /// . + public const string MotionBlur = "Motion.MotionBlur"; + + /// degrees. + public const string TargetShutterAngle = "Motion.TargetShutterAngle"; + + /// . + public const string FlowQuality = "Motion.FlowQuality"; + + /// . + public const string Stabilize = "Motion.Stabilize"; + + /// σ in frames. + public const string StabilizeSmoothing = "Motion.StabilizeSmoothing"; + + /// aspect ("16:9", "9:16", …). + public const string Aspect = "Camera.Aspect"; + + /// crop placement −1..1 (0 = centred). + public const string OffsetY = "Camera.OffsetY"; + + /// built-in export preset id. + public const string ExportPreset = "Export.Preset"; + + /// output size "WxH" (the cap from source, previews and encoder). + public const string Resolution = "Export.Resolution"; +} + +/// +/// One advisor decision (BRIEF §10.3). is null when data is missing; the reason then says what is +/// missing and nothing is changed. are numbers (already rounded for display) or plain tokens, +/// formatted by the caller with its culture: Loc.L(ReasonKey, [.. ReasonArgs]). +/// +/// 0..1: how strongly the measurements support the value. +public sealed record Recommendation( + AdvisorSection Section, + string Parameter, + object? Value, + double Confidence, + string ReasonKey, + IReadOnlyList ReasonArgs) +{ + public bool IsMissingData => Value is null; +} + +/// Output of : recommendations in section order plus every finding. +public sealed record AdvisorResult(IReadOnlyList Recommendations, IReadOnlyList Findings) +{ + public Recommendation? Find(string parameter) => Recommendations.FirstOrDefault(r => r.Parameter == parameter); + + public IEnumerable In(AdvisorSection section) => Recommendations.Where(r => r.Section == section); +} + +/// What the advisor knows about the sequence besides the analyses. +public sealed record SequenceContext +{ + public int FrameCount { get; init; } + + /// Oriented full-resolution size (0 = take the light analysis' dominant size). + public int SourceWidth { get; init; } + + public int SourceHeight { get; init; } + + /// Frames that decode only through their embedded preview (BRIEF §8.2 tier 2). + public int PreviewOnlyCount { get; init; } + + /// Oriented size of those embedded previews (0 = unknown). + public int PreviewWidth { get; init; } + + public int PreviewHeight { get; init; } + + /// Median shutter time in seconds, for the real shutter angle. + public double? MedianExposureSeconds { get; init; } + + /// Encoders available on the rendering machine; empty = unknown (no codec is ruled out). + public IReadOnlyList Codecs { get; init; } = []; + + /// Wanted video length ("fit to N seconds"), when the user set one. + public double? TargetDurationSeconds { get; init; } + + /// Context from the archive's frame rows: count, dominant oriented size, preview-only count, median shutter time. + public static SequenceContext FromFrames(IReadOnlyList frames, IReadOnlyList? codecs = null) + { + ArgumentNullException.ThrowIfNull(frames); + var sizes = new Dictionary<(int, int), int>(); + var exposures = new List(); + var previewOnly = 0; + foreach (var f in frames) + { + var size = f.Orientation is >= 5 and <= 8 ? (f.Height, f.Width) : (f.Width, f.Height); + if (size.Item1 > 0 && size.Item2 > 0) sizes[size] = sizes.GetValueOrDefault(size) + 1; + if (f.ExposureTime is > 0 and var t) exposures.Add(t); + if ((f.Flags & FrameFlags.PreviewOnly) != 0) previewOnly++; + } + var (width, height) = sizes.Count > 0 ? sizes.MaxBy(kv => kv.Value).Key : (0, 0); + return new SequenceContext + { + FrameCount = frames.Count, + SourceWidth = width, + SourceHeight = height, + PreviewOnlyCount = previewOnly, + MedianExposureSeconds = exposures.Count > 0 ? Statistics.Median(exposures.ToArray()) : null, + Codecs = codecs ?? [], + }; + } +} + +/// A value changed: effective value before and after, and why. +public sealed record SettingChange(string Parameter, object? Before, object? After, string ReasonKey, IReadOnlyList ReasonArgs); + +/// Settings after and the report of what changed. +public sealed record OptimiseResult(ProjectSettings Settings, IReadOnlyList Changes); diff --git a/src/Titano.Core/Advisor/ParameterBindings.cs b/src/Titano.Core/Advisor/ParameterBindings.cs new file mode 100644 index 00000000..831a62e1 --- /dev/null +++ b/src/Titano.Core/Advisor/ParameterBindings.cs @@ -0,0 +1,137 @@ +using System.Collections; +using System.Globalization; +using Titano.Core.Export; +using Titano.Core.Project; + +namespace Titano.Core.Advisor; + +/// How one advisor parameter reads and writes . +internal sealed class ParameterBinding +{ + public required string Parameter { get; init; } + public required AdvisorSection Section { get; init; } + + /// A module on/off decision: returns it to Auto when the advice differs. + public bool IsModuleSwitch { get; init; } + + /// The value in force (manual, else advised), null when neither exists. + public required Func Effective { get; init; } + + /// Auto fields: stores the advice and its reason, never touching a manual value. + public Func? Advise { get; init; } + + /// Auto fields: drops the manual value so the advice applies. + public Func? ResetToAuto { get; init; } + + /// Plain fields: the heavier decision takes (each guards user choices). + public Func? Set { get; init; } +} + +/// The binding of every id, in section order. +internal static class ParameterBindings +{ + public static IReadOnlyList All { get; } = + [ + new() + { + Parameter = AdvisorParameters.Hero, Section = AdvisorSection.Frames, + Effective = s => s.HeroFrame, + Set = (s, r) => s.HeroFrame is null ? s with { HeroFrame = (int)r.Value! } : s, + }, + new() + { + Parameter = AdvisorParameters.Excluded, Section = AdvisorSection.Frames, + Effective = s => s.ExcludedFrames, + Set = (s, r) => s with { ExcludedFrames = [.. s.ExcludedFrames.Union((int[])r.Value!).Order()] }, + }, + AutoField(AdvisorParameters.TimingMode, AdvisorSection.Timing, true, s => s.Timing.Mode, (s, a) => s with { Timing = s.Timing with { Mode = a } }), + AutoField(AdvisorParameters.FrameRate, AdvisorSection.Timing, false, s => s.Timing.FrameRate, (s, a) => s with { Timing = s.Timing with { FrameRate = a } }), + new() + { + Parameter = AdvisorParameters.FitToSeconds, Section = AdvisorSection.Timing, + Effective = s => s.Timing.FitToSeconds, + Set = (s, r) => s with { Timing = s.Timing with { FitToSeconds = (double)r.Value! } }, + }, + AutoField(AdvisorParameters.Deflicker, AdvisorSection.Exposure, true, s => s.Exposure.Deflicker, (s, a) => s with { Exposure = s.Exposure with { Deflicker = a } }), + AutoField(AdvisorParameters.DeflickerWindow, AdvisorSection.Exposure, false, s => s.Exposure.DeflickerWindow, (s, a) => s with { Exposure = s.Exposure with { DeflickerWindow = a } }), + AutoField(AdvisorParameters.DeflickerStrength, AdvisorSection.Exposure, false, s => s.Exposure.DeflickerStrength, (s, a) => s with { Exposure = s.Exposure with { DeflickerStrength = a } }), + AutoField(AdvisorParameters.Regions, AdvisorSection.Exposure, true, s => s.Exposure.Regions, (s, a) => s with { Exposure = s.Exposure with { Regions = a } }), + AutoField(AdvisorParameters.HolyGrail, AdvisorSection.Exposure, true, s => s.Exposure.HolyGrail, (s, a) => s with { Exposure = s.Exposure with { HolyGrail = a } }), + AutoField(AdvisorParameters.TransitionLength, AdvisorSection.Exposure, false, s => s.Exposure.TransitionLength, (s, a) => s with { Exposure = s.Exposure with { TransitionLength = a } }), + AutoField(AdvisorParameters.WhiteBalanceSmoothing, AdvisorSection.Exposure, true, s => s.Exposure.WhiteBalanceSmoothing, (s, a) => s with { Exposure = s.Exposure with { WhiteBalanceSmoothing = a } }), + AutoField(AdvisorParameters.MotionBlur, AdvisorSection.Motion, true, s => s.Motion.MotionBlur, (s, a) => s with { Motion = s.Motion with { MotionBlur = a } }), + AutoField(AdvisorParameters.TargetShutterAngle, AdvisorSection.Motion, false, s => s.Motion.TargetShutterAngle, (s, a) => s with { Motion = s.Motion with { TargetShutterAngle = a } }), + AutoField(AdvisorParameters.FlowQuality, AdvisorSection.Motion, false, s => s.Motion.FlowQuality, (s, a) => s with { Motion = s.Motion with { FlowQuality = a } }), + AutoField(AdvisorParameters.Stabilize, AdvisorSection.Motion, true, s => s.Motion.Stabilize, (s, a) => s with { Motion = s.Motion with { Stabilize = a } }), + AutoField(AdvisorParameters.StabilizeSmoothing, AdvisorSection.Motion, false, s => s.Motion.StabilizeSmoothing, (s, a) => s with { Motion = s.Motion with { StabilizeSmoothing = a } }), + AutoField(AdvisorParameters.Aspect, AdvisorSection.Camera, false, s => s.Camera.Aspect, (s, a) => s with { Camera = s.Camera with { Aspect = a } }), + new() + { + Parameter = AdvisorParameters.OffsetY, Section = AdvisorSection.Camera, + Effective = s => s.Camera.OffsetY, + Set = (s, r) => s.Camera.OffsetY == 0 ? s with { Camera = s.Camera with { OffsetY = (double)r.Value! } } : s, + }, + AutoField(AdvisorParameters.ExportPreset, AdvisorSection.Export, true, s => s.Export.Preset, (s, a) => s with { Export = s.Export with { Preset = a } }), + new() + { + Parameter = AdvisorParameters.Resolution, Section = AdvisorSection.Export, + Effective = s => s.Export.Overrides is { Width: { } w, Height: { } h } ? Size(w, h) : null, + Set = CapResolution, + }, + ]; + + public static ParameterBinding? Find(string parameter) => All.FirstOrDefault(b => b.Parameter == parameter); + + /// Value equality that compares lists element by element. + public static bool SameValue(object? a, object? b) + { + if (a is IEnumerable x && b is IEnumerable y && a is not string && b is not string) return x.Cast().SequenceEqual(y.Cast()); + return Equals(a, b); + } + + /// Recommendation arguments as stored in (culture-neutral text). + public static string[] Strings(IReadOnlyList args) => [.. args.Select(a => Convert.ToString(a, CultureInfo.InvariantCulture) ?? string.Empty)]; + + public static string Size(int width, int height) => string.Create(CultureInfo.InvariantCulture, $"{width}x{height}"); + + public static bool HasAdvice(Auto auto) => typeof(T).IsValueType + ? auto.ReasonKey is not null && !auto.ReasonKey.StartsWith(AdvisorKeys.MissingPrefix, StringComparison.Ordinal) + : auto.AutoValue is not null; + + private static ParameterBinding AutoField(string parameter, AdvisorSection section, bool module, Func> get, Func, ProjectSettings> set) => new() + { + Parameter = parameter, + Section = section, + IsModuleSwitch = module, + Effective = s => EffectiveOf(get(s)), + Advise = (s, r) => set(s, Advise(get(s), r)), + ResetToAuto = s => set(s, get(s).Reset()), + }; + + private static object? EffectiveOf(Auto auto) => !auto.IsAuto && auto.Manual is not null ? auto.Manual : HasAdvice(auto) ? auto.AutoValue : null; + + /// + /// Stores a value with its reason. Missing data changes no value: the missing-data reason is stored only when the + /// parameter has no advice yet, so the Auto tooltip can say why it is empty. + /// + private static Auto Advise(Auto auto, Recommendation recommendation) + { + var args = Strings(recommendation.ReasonArgs); + if (recommendation.Value is null) + return HasAdvice(auto) ? auto : auto with { ReasonKey = recommendation.ReasonKey, ReasonArgs = args }; + if (recommendation.Value is not T value) + throw new InvalidOperationException($"{recommendation.Parameter} expects {typeof(T).Name}, got {recommendation.Value.GetType().Name}."); + return auto.WithAdvice(value, recommendation.ReasonKey, args); + } + + /// Overrides the output size when the preset in force is larger than the recommended cap. + private static ProjectSettings CapResolution(ProjectSettings settings, Recommendation recommendation) + { + var parts = ((string)recommendation.Value!).Split('x'); + var width = int.Parse(parts[0], CultureInfo.InvariantCulture); + var height = int.Parse(parts[1], CultureInfo.InvariantCulture); + var id = EffectiveOf(settings.Export.Preset) as string; + if (id is null || ExportPresets.Find(id) is not { Width: > 0 } preset || (preset.Width <= width && preset.Height <= height)) return settings; + return settings with { Export = settings.Export with { Overrides = settings.Export.Overrides with { Width = width, Height = height } } }; + } +} diff --git a/src/Titano.Core/Advisor/SequencePresets.cs b/src/Titano.Core/Advisor/SequencePresets.cs new file mode 100644 index 00000000..87e55389 --- /dev/null +++ b/src/Titano.Core/Advisor/SequencePresets.cs @@ -0,0 +1,217 @@ +using System.Globalization; +using System.Text.Json; +using System.Text.Json.Serialization; +using Titano.Core.Analysis; +using Titano.Core.Analysis.Deep; +using Titano.Core.Export; +using Titano.Core.Localization; +using Titano.Core.Project; +using Titano.Core.Video; + +namespace Titano.Core.Advisor; + +/// +/// A one-click bundle (BRIEF §10.3): full project settings plus an export preset, named by a resource key and +/// arguments (culture-neutral numbers or tokens) or, for user presets, by the user's own . +/// +public sealed record SequencePreset +{ + /// "night-sky", "holy-grail", "construction", "social-vertical", "standard", or a user id. + public required string Id { get; init; } + + public required string NameKey { get; init; } + public IReadOnlyList NameArgs { get; init; } = []; + + /// The user's name for a saved preset; overrides . + public string? Name { get; init; } + + public string? ReasonKey { get; init; } + public IReadOnlyList ReasonArgs { get; init; } = []; + public required ProjectSettings Settings { get; init; } + public required string ExportPresetId { get; init; } + + /// 0..1: how well the measured content matches the preset. + public double Confidence { get; init; } + + public bool IsUser { get; init; } + + public string DisplayName() => Name ?? Advisor.Explain(NameKey, NameArgs); + + /// A copy saved under the user's name. + public SequencePreset AsUserPreset(string name) + { + ArgumentException.ThrowIfNullOrWhiteSpace(name); + return this with { Id = Guid.CreateVersion7().ToString("N"), Name = name.Trim(), IsUser = true }; + } + + public string ToJson() => JsonSerializer.Serialize(this, AdvisorJson.Default.SequencePreset); + + public static SequencePreset FromJson(string json) => + JsonSerializer.Deserialize(json, AdvisorJson.Default.SequencePreset) ?? throw new InvalidDataException("Preset JSON is empty."); +} + +/// +/// Generates the sequence presets that fit the measured content, best match first: Night sky (star field or night, +/// 4K 10-bit HEVC 24 fps, deflicker, stabilise when shaky), Holy grail sunset (received exposure steps across a +/// day/night change, 4K HEVC 30 fps, transitions), Construction cam (several sessions over at least a day, 1080p +/// H.264 30 fps, adaptive timing), Standard when none of these match, and Social vertical (1080×1920) always last. +/// A preset's export choice gives way to the advised one when the source, previews or encoders cannot reach it. +/// Content values stay Auto with the advisor's reasons; the preset's own choices are stored as manual values. +/// +public static class SequencePresets +{ + public static IReadOnlyList Generate(LightAnalysisReport light, DeepAnalysisReport? deep, SequenceContext context) + { + ArgumentNullException.ThrowIfNull(light); + ArgumentNullException.ThrowIfNull(context); + var advice = Advisor.Recommend(light, deep, context); + var advised = Advisor.Apply(new ProjectSettings(), advice); + var exportId = advice.Find(AdvisorParameters.ExportPreset)?.Value as string ?? "1080p-h264"; + var presets = new List(); + + if (deep is { } d && (d.Sky.StarField || d.Sky.Light == DayNight.Night)) + { + var id = Pick(exportId, "4k-hevc10-archive", context); + var window = advised.Exposure.DeflickerWindow.AutoValue; + var shaky = advice.Find(AdvisorParameters.Stabilize)?.Value is true; + var settings = Manual(advised, id, "24") with { Exposure = advised.Exposure with { Deflicker = advised.Exposure.Deflicker.WithManual(true) } }; + if (shaky) settings = settings with { Motion = settings.Motion with { Stabilize = settings.Motion.Stabilize.WithManual(true) } }; + var stars = d.Sky.StarField ? 100.0 * d.Sky.StarFrames / int.Max(1, d.FrameCount) : 0; + presets.Add(new SequencePreset + { + Id = "night-sky", + NameKey = shaky ? AdvisorKeys.PresetNightSkyStabilised : AdvisorKeys.PresetNightSky, + NameArgs = [Label(id), CodecLabel(id), "24", Text(window)], + ReasonKey = AdvisorKeys.PresetReasonNightSky, + ReasonArgs = [Text(double.Round(stars))], + Settings = settings, + ExportPresetId = id, + Confidence = d.Sky.StarField ? 0.9 : 0.7, + }); + } + + var received = deep?.Exposure.ReceivedSteps ?? (light.ExposureValues.Any(v => v is not null) ? light.ExposureSteps.Count : 0); + var lightChange = deep is not null + ? deep.Sky.Light is DayNight.DayToNight or DayNight.NightToDay || deep.Exposure.SceneRangeEv >= 3 + : light.Findings.Any(f => f.Key == FindingKeys.DayNightTransition); + if (received > 0 && lightChange) + { + var id = Pick(exportId, "4k-hevc", context); + var transitions = advised.Exposure.TransitionLength.AutoValue; + var range = deep?.Exposure.SceneRangeEv ?? 0; + var settings = Manual(advised, id, "30") with + { + Exposure = advised.Exposure with + { + HolyGrail = advised.Exposure.HolyGrail.WithManual(true), + Deflicker = advised.Exposure.Deflicker.WithManual(true), + }, + }; + presets.Add(new SequencePreset + { + Id = "holy-grail", + NameKey = AdvisorKeys.PresetHolyGrail, + NameArgs = [Label(id), CodecLabel(id), "30", Text(transitions)], + ReasonKey = AdvisorKeys.PresetReasonHolyGrail, + ReasonArgs = [Text(received), Text(double.Round(range, 1))], + Settings = settings, + ExportPresetId = id, + Confidence = 0.85, + }); + } + + if (light.Sessions.Count >= 2 && light.CaptureSpan >= TimeSpan.FromDays(1)) + { + var id = Pick(exportId, "1080p-h264", context); + var settings = Manual(advised, id, "30"); + settings = settings with { Timing = settings.Timing with { Mode = settings.Timing.Mode.WithManual(TimingMode.Adaptive) } }; + presets.Add(new SequencePreset + { + Id = "construction", + NameKey = AdvisorKeys.PresetConstruction, + NameArgs = [Label(id), CodecLabel(id), "30"], + ReasonKey = AdvisorKeys.PresetReasonConstruction, + ReasonArgs = [Text(light.Sessions.Count), Text(double.Round(light.CaptureSpan.TotalDays, 1))], + Settings = settings, + ExportPresetId = id, + Confidence = 0.8, + }); + } + + if (presets.Count == 0) + { + var fps = advised.Timing.FrameRate.AutoValue ?? ExportPresets.Find(exportId)?.FrameRate.ToString() ?? "30"; + presets.Add(new SequencePreset + { + Id = "standard", + NameKey = AdvisorKeys.PresetStandard, + NameArgs = [Label(exportId), CodecLabel(exportId), fps], + ReasonKey = AdvisorKeys.PresetReasonStandard, + Settings = Manual(advised, exportId, null), + ExportPresetId = exportId, + Confidence = 0.6, + }); + } + + const string vertical = "vertical-1080x1920"; + var social = Manual(advised, vertical, "30") with { Camera = advised.Camera with { Aspect = advised.Camera.Aspect.WithManual("9:16"), OffsetY = 0 } }; + presets.Add(new SequencePreset + { + Id = "social-vertical", + NameKey = AdvisorKeys.PresetSocialVertical, + NameArgs = ["1080", "1920"], + ReasonKey = AdvisorKeys.PresetReasonSocialVertical, + Settings = social, + ExportPresetId = vertical, + Confidence = 0.4, + }); + return [.. presets.OrderByDescending(p => p.Confidence)]; + } + + /// The preset's own export choice when the advised size reaches 4K, else the advised (capped) preset. + private static string Pick(string advised, string wanted, SequenceContext context) + { + var cap = ExportPresets.Find(advised); + var target = ExportPresets.Find(wanted)!; + var codecOk = context.Codecs.Count == 0 || context.Codecs.Any(c => c.Codec == target.Codec && (target.BitDepth <= 8 || c.SupportsTenBit)); + return cap is not null && cap.Width >= target.Width && cap.Height >= target.Height && codecOk ? wanted : advised; + } + + /// Export preset and (optionally) frame rate as the preset's manual choices. + private static ProjectSettings Manual(ProjectSettings settings, string exportId, string? frameRate) + { + settings = settings with { Export = settings.Export with { Preset = settings.Export.Preset.WithManual(exportId) } }; + return frameRate is null ? settings : settings with { Timing = settings.Timing with { FrameRate = settings.Timing.FrameRate.WithManual(frameRate) } }; + } + + /// Resolution label of an export preset ("4K", "1440p", "1080p", …). + private static string Label(string exportId) => ExportPresets.Find(exportId) switch + { + { Width: >= 3840 } => "4K", + { Width: > 0 } p => string.Create(CultureInfo.InvariantCulture, $"{int.Min(p.Width, p.Height)}p"), + _ => exportId, + }; + + /// Codec label of an export preset ("HEVC Main10", "HEVC", "H.264", "AV1"): technical names, not translated. + private static string CodecLabel(string exportId) => ExportPresets.Find(exportId) switch + { + { Codec: VideoCodec.Hevc, BitDepth: >= 10 } => "HEVC Main10", + { Codec: VideoCodec.Hevc } => "HEVC", + { Codec: VideoCodec.Av1 } => "AV1", + { Codec: VideoCodec.H264 } => "H.264", + { } p => p.Codec.ToString(), + _ => exportId, + }; + + private static string Text(T value) => Convert.ToString(value, CultureInfo.InvariantCulture) ?? string.Empty; +} + +/// Source-generated JSON for saved sequence presets. +[JsonSourceGenerationOptions( + WriteIndented = true, + PropertyNamingPolicy = JsonKnownNamingPolicy.CamelCase, + DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingNull, + UseStringEnumConverter = true, + PropertyNameCaseInsensitive = true)] +[JsonSerializable(typeof(SequencePreset))] +internal sealed partial class AdvisorJson : JsonSerializerContext; diff --git a/tests/Titano.Core.Tests/Advisor/AdvisorLocalizationTests.cs b/tests/Titano.Core.Tests/Advisor/AdvisorLocalizationTests.cs new file mode 100644 index 00000000..bd5b610f --- /dev/null +++ b/tests/Titano.Core.Tests/Advisor/AdvisorLocalizationTests.cs @@ -0,0 +1,132 @@ +using System.Collections; +using System.Globalization; +using System.Reflection; +using System.Resources; +using System.Text.RegularExpressions; +using Titano.Core.Advisor; +using Titano.Core.Analysis; +using Titano.Core.Analysis.Deep; +using Titano.Core.Diagnostics.Synthetic; +using Titano.Core.Localization; +using Titano.Core.Project; +using Titano.Core.Tests.Analysis.Deep; +using Titano.Testing; + +namespace Titano.Core.Tests.Advisor; + +using AdvisorApi = Titano.Core.Advisor.Advisor; + +public sealed partial class AdvisorLocalizationTests(TestContext context) +{ + private static readonly CultureInfo English = CultureInfo.GetCultureInfo("en"); + private static readonly CultureInfo Italian = CultureInfo.GetCultureInfo("it"); + + [Test] + public void EveryAdvisorKeyHasEnglishAndItalianTextWithTheSamePlaceholders() + { + var manager = new ResourceManager("Titano.Core.i18n.Advisor", typeof(Loc).Assembly); + var english = Entries(manager.GetResourceSet(CultureInfo.InvariantCulture, createIfNotExists: true, tryParents: false)!); + var italian = Entries(manager.GetResourceSet(Italian, createIfNotExists: true, tryParents: false)!); + var keys = Keys(typeof(AdvisorKeys)).Concat(Keys(typeof(FindingKeys))).Concat(Keys(typeof(DeepFindingKeys))).ToList(); + Assert.Greater(keys.Count, 90); + foreach (var key in keys) + { + Assert.True(english.TryGetValue(key, out var en), $"English text missing for {key}"); + Assert.True(italian.TryGetValue(key, out var it), $"Italian text missing for {key}"); + Assert.SequenceEqual(Placeholders(en!), Placeholders(it!), key); + Assert.LessOrEqual(en!.Length, 200); + } + Assert.Equal(english.Count, keys.Count); + } + + [Test] + public async Task EveryReasonAndFindingOfTheGoldenScenesFormatsInBothLanguages() + { + var scenes = new List<(SyntheticFrameSource Source, DeepAnalysisReport? Deep)> + { + (new SyntheticFrameSource(DeepScenes.NightSky()), await DeepReports.Night), + (new SyntheticFrameSource(DeepScenes.NightSky(jitter: 2), 2), await DeepReports.NightJitter), + (new SyntheticFrameSource(DeepScenes.HolyGrail()), await DeepReports.HolyGrail), + (new SyntheticFrameSource(DeepScenes.HolyGrail()) { StripExposure = true }, null), + }; + var rendered = 0; + foreach (var (source, deep) in scenes) + { + var frames = Enumerable.Range(0, source.Count).Select(source.Metadata).ToList(); + var light = LightAnalyzer.Analyze(frames); + var sequence = new SequenceContext { FrameCount = frames.Count, SourceWidth = 6000, SourceHeight = 4000, MedianExposureSeconds = 1.0 / 250 }; + var result = AdvisorApi.Recommend(light, deep, sequence); + foreach (var r in result.Recommendations) rendered += Render(r.ReasonKey, [.. r.ReasonArgs]); + foreach (var f in result.Findings) rendered += Render(f.Key, f.Arguments); + foreach (var p in SequencePresets.Generate(light, deep, sequence)) + { + rendered += Render(p.NameKey, [.. p.NameArgs]); + rendered += Render(p.ReasonKey!, [.. p.ReasonArgs]); + } + // Stored reasons (culture-neutral strings) render with the current culture's numbers. + var applied = AdvisorApi.Apply(new ProjectSettings(), result); + Assert.DoesNotContain('⟦', AdvisorApi.Explain(applied.Exposure.HolyGrail.ReasonKey!, applied.Exposure.HolyGrail.ReasonArgs)); + } + context.Log($"{rendered} texts rendered"); + Assert.Greater(rendered, 80); + } + + [Test] + public void StoredNumericArgumentsAreLocalisedWhenExplained() + { + var text = Format(Loc.Get(AdvisorKeys.DeflickerOn, Italian)!, Italian, 0.125); + Assert.Contains("0,125", text); + Assert.Contains("0.125", Format(Loc.Get(AdvisorKeys.DeflickerOn, English)!, English, 0.125)); + } + + [Test] + public async Task PresetsRoundTripAsJsonAndSaveAsUserPresets() + { + var source = new SyntheticFrameSource(DeepScenes.NightSky(jitter: 2), 2); + var frames = Enumerable.Range(0, source.Count).Select(source.Metadata).ToList(); + var presets = SequencePresets.Generate(LightAnalyzer.Analyze(frames), await DeepReports.NightJitter, new SequenceContext { SourceWidth = 6000, SourceHeight = 4000 }); + foreach (var preset in presets) + { + var json = preset.ToJson(); + Assert.Equal(json, SequencePreset.FromJson(json).ToJson()); + } + var user = presets[0].AsUserPreset(" My night "); + Assert.True(user.IsUser); + Assert.Equal("My night", user.Name); + Assert.NotEqual(presets[0].Id, user.Id); + var restored = SequencePreset.FromJson(user.ToJson()); + Assert.Equal("My night", restored.DisplayName()); + Assert.Equal(presets[0].Settings.ToJson(), restored.Settings.ToJson()); + Assert.Equal(presets[0].ExportPresetId, restored.ExportPresetId); + } + + private static int Render(string key, object?[] args) + { + foreach (var culture in new[] { English, Italian }) + { + var format = Loc.Get(key, culture); + Assert.NotNull(format); + var text = Format(format!, culture, args); + Assert.False(text.Contains('{'), $"{key} left a placeholder: {text}"); + } + return 1; + } + + private static string Format(string format, CultureInfo culture, params object?[] args) => string.Format(culture, format, args); + + private static Dictionary Entries(ResourceSet set) + { + var entries = new Dictionary(StringComparer.Ordinal); + foreach (DictionaryEntry entry in set) entries[(string)entry.Key] = (string)entry.Value!; + return entries; + } + + private static IEnumerable Keys(Type type) => + type.GetFields(BindingFlags.Public | BindingFlags.Static).Where(f => f.IsLiteral && f.FieldType == typeof(string) && f.Name != nameof(AdvisorKeys.MissingPrefix)).Select(f => (string)f.GetRawConstantValue()!) + .Concat(type.GetProperties(BindingFlags.Public | BindingFlags.Static).Where(p => p.PropertyType == typeof(string)).Select(p => (string)p.GetValue(null)!)); + + private static IEnumerable Placeholders(string text) => PlaceholderRegex().Matches(text).Select(m => m.Groups[1].Value).Order(); + + [GeneratedRegex(@"\{(\d+)(?:[,:][^}]*)?\}")] + private static partial Regex PlaceholderRegex(); +} diff --git a/tests/Titano.Core.Tests/Advisor/AdvisorTests.cs b/tests/Titano.Core.Tests/Advisor/AdvisorTests.cs new file mode 100644 index 00000000..e0f23c1f --- /dev/null +++ b/tests/Titano.Core.Tests/Advisor/AdvisorTests.cs @@ -0,0 +1,349 @@ +using Titano.Core.Advisor; +using Titano.Core.Analysis; +using Titano.Core.Analysis.Deep; +using Titano.Core.Diagnostics.Synthetic; +using Titano.Core.Mathematics; +using Titano.Core.Project; +using Titano.Core.Tests.Analysis.Deep; +using Titano.Core.Video; +using Titano.Testing; + +namespace Titano.Core.Tests.Advisor; + +// The class shares its name with the namespace, which an enclosing Titano.Core.* namespace would resolve first. +using AdvisorApi = Titano.Core.Advisor.Advisor; + +public sealed class AdvisorTests(TestContext context) +{ + [Test] + public async Task NightSkyGetsTheNightPresetDeflickerAndNoStabilisation() + { + var (light, sequence) = Inputs(new SyntheticFrameSource(DeepScenes.NightSky())); + var deep = await DeepReports.Night; + var result = AdvisorApi.Recommend(light, deep, sequence); + Log(result); + + Assert.Equal(true, Value(result, AdvisorParameters.Deflicker)); + Assert.Equal(15, Value(result, AdvisorParameters.DeflickerWindow)); + Assert.Equal(false, Value(result, AdvisorParameters.Stabilize)); + Assert.Equal(AdvisorKeys.StabilizeOff, result.Find(AdvisorParameters.Stabilize)!.ReasonKey); + Assert.Equal("3840x2160", Value(result, AdvisorParameters.Resolution)); + Assert.Equal("4k-hevc10-archive", Value(result, AdvisorParameters.ExportPreset)); + // 15 s exposures every 20 s are a 270° shutter: already beyond the 180° target. + Assert.Equal(false, Value(result, AdvisorParameters.MotionBlur)); + Assert.Equal(AdvisorKeys.MotionBlurAlready, result.Find(AdvisorParameters.MotionBlur)!.ReasonKey); + Assert.Equal(TimingMode.Constant, Value(result, AdvisorParameters.TimingMode)); + Assert.Equal("24", Value(result, AdvisorParameters.FrameRate)); + Assert.Equal(AdvisorKeys.WindowMinimum, result.Find(AdvisorParameters.DeflickerWindow)!.ReasonKey); + + var presets = SequencePresets.Generate(light, deep, sequence); + var night = presets[0]; + Assert.Equal("night-sky", night.Id); + Assert.Equal(AdvisorKeys.PresetNightSky, night.NameKey); + Assert.SequenceEqual(["4K", "HEVC Main10", "24", "15"], night.NameArgs); + Assert.Equal("4k-hevc10-archive", night.ExportPresetId); + Assert.Equal("24", night.Settings.Timing.FrameRate.Resolve("30")); + Assert.True(night.Settings.Exposure.Deflicker.Resolve(false)); + Assert.False(night.Settings.Motion.Stabilize.Resolve(true)); + Assert.Equal("social-vertical", presets[^1].Id); + Assert.DoesNotContain("holy-grail", presets.Select(p => p.Id)); + } + + [Test] + public async Task InjectedJitterTurnsStabilisationOn() + { + var (light, sequence) = Inputs(new SyntheticFrameSource(DeepScenes.NightSky(jitter: 2), 2)); + var deep = await DeepReports.NightJitter; + var result = AdvisorApi.Recommend(light, deep, sequence); + var stabilize = result.Find(AdvisorParameters.Stabilize)!; + Assert.Equal(true, stabilize.Value); + Assert.Equal(AdvisorKeys.StabilizeOn, stabilize.ReasonKey); + // 2 px RMS on a 160-px source is 48 px at 3840 px. + Assert.InRange((double)stabilize.ReasonArgs[0], 40, 60); + Assert.Equal(12.0, Value(result, AdvisorParameters.StabilizeSmoothing)); + + var night = SequencePresets.Generate(light, deep, sequence)[0]; + Assert.Equal(AdvisorKeys.PresetNightSkyStabilised, night.NameKey); + Assert.False(night.Settings.Motion.Stabilize.IsAuto); + Assert.True(night.Settings.Motion.Stabilize.Manual); + } + + [Test] + public async Task HolyGrailSunsetGetsTransitionsOfHalfTheStepSpacing() + { + var (light, sequence) = Inputs(new SyntheticFrameSource(DeepScenes.HolyGrail())); + var deep = await DeepReports.HolyGrail; + var result = AdvisorApi.Recommend(light, deep, sequence); + Log(result); + var holyGrail = result.Find(AdvisorParameters.HolyGrail)!; + Assert.Equal(true, holyGrail.Value); + Assert.Equal(AdvisorKeys.HolyGrailReceived, holyGrail.ReasonKey); + Assert.SequenceEqual([5], holyGrail.ReasonArgs.Cast()); + var transition = result.Find(AdvisorParameters.TransitionLength)!; + Assert.Equal(20, transition.Value); + Assert.Equal(AdvisorKeys.TransitionSpacing, transition.ReasonKey); + Assert.SequenceEqual([40.0, 20.0], transition.ReasonArgs.Select(Convert.ToDouble)); + Assert.Equal(false, Value(result, AdvisorParameters.MotionBlur)); + Assert.Equal(AdvisorKeys.MotionBlurLittle, result.Find(AdvisorParameters.MotionBlur)!.ReasonKey); + + var presets = SequencePresets.Generate(light, deep, sequence); + var grail = presets[0]; + Assert.Equal("holy-grail", grail.Id); + Assert.SequenceEqual(["4K", "HEVC", "30", "20"], grail.NameArgs); + Assert.Equal("4k-hevc", grail.ExportPresetId); + Assert.True(grail.Settings.Exposure.HolyGrail.Resolve(false)); + Assert.Equal(20, grail.Settings.Exposure.TransitionLength.Resolve(0)); + + // Without pixels the metadata steps are trusted, with the same spacing rule and less confidence. + var metadataOnly = AdvisorApi.Recommend(light, null, sequence); + Assert.Equal(AdvisorKeys.HolyGrailMetadata, metadataOnly.Find(AdvisorParameters.HolyGrail)!.ReasonKey); + Assert.Equal(20, Value(metadataOnly, AdvisorParameters.TransitionLength)); + Assert.Less(metadataOnly.Find(AdvisorParameters.HolyGrail)!.Confidence, holyGrail.Confidence); + } + + [Test] + public void IrregularCadenceWithNightlyPausesIsAdaptive() + { + const double night = 14 * 3600; + var source = new SyntheticFrameSource(SyntheticSequence.Create(new SyntheticSequenceOptions + { + Width = 96, Height = 64, FrameCount = 300, IntervalSeconds = 600, IntervalJitterSeconds = 20, + TimeShifts = [new(60, night), new(120, night), new(180, night), new(240, night)], + })); + var (light, sequence) = Inputs(source); + var result = AdvisorApi.Recommend(light, null, sequence); + Log(result); + var mode = result.Find(AdvisorParameters.TimingMode)!; + Assert.Equal(TimingMode.Adaptive, mode.Value); + Assert.Equal(AdvisorKeys.TimingSessions, mode.ReasonKey); + Assert.Equal(5, mode.ReasonArgs[0]); + Assert.Approximately(14.2, (double)mode.ReasonArgs[1], 0.051); + Assert.Equal("30", Value(result, AdvisorParameters.FrameRate)); + // Pixel-based parameters wait for the deep analysis. + foreach (var parameter in new[] { AdvisorParameters.Deflicker, AdvisorParameters.Stabilize, AdvisorParameters.Regions, AdvisorParameters.Hero }) + { + var missing = result.Find(parameter)!; + Assert.True(missing.IsMissingData); + Assert.Equal(AdvisorKeys.MissingDeep, missing.ReasonKey); + } + + var presets = SequencePresets.Generate(light, null, sequence); + Assert.SequenceEqual(["construction", "social-vertical"], presets.Select(p => p.Id)); + Assert.Equal(TimingMode.Adaptive, presets[0].Settings.Timing.Mode.Resolve(TimingMode.Constant)); + Assert.Equal("1080p-h264", presets[0].ExportPresetId); + } + + [Test] + public async Task SparseGapsWithStillContentAreInterpolated() + { + var gapped = SyntheticSequence.Create(DeepScenes.HolyGrail().Options with { TimeShifts = [new(100, 40)] }); + var (light, sequence) = Inputs(new SyntheticFrameSource(gapped)); + var result = AdvisorApi.Recommend(light, await DeepReports.HolyGrail, sequence); + Assert.Equal(TimingMode.Interpolated, Value(result, AdvisorParameters.TimingMode)); + Assert.Equal(FlowQualitySetting.Best, Value(result, AdvisorParameters.FlowQuality)); + Assert.Equal(TimingMode.Constant, Value(AdvisorApi.Recommend(light, null, sequence), AdvisorParameters.TimingMode)); + } + + [Test] + public async Task PeriodicFlickerWindowIsFourPeriods() + { + var source = new SyntheticFrameSource(SyntheticSequence.Create(new SyntheticSequenceOptions + { + Width = 96, Height = 64, FrameCount = 240, FlickerEv = 0.15, FlickerPeriodFrames = 8, + })); + var deep = await DeepAnalyzer.AnalyzeAsync(source, DeepScenes.Options); + var (light, sequence) = Inputs(source); + var window = AdvisorApi.Recommend(light, deep, sequence).Find(AdvisorParameters.DeflickerWindow)!; + Assert.Equal(33, window.Value); + Assert.Equal(AdvisorKeys.WindowPeriod, window.ReasonKey); + Assert.Equal(8.0, window.ReasonArgs[0]); + } + + [Test] + public void MissingExposureMetadataIsReportedAndChangesNothing() + { + var (light, sequence) = Inputs(new SyntheticFrameSource(DeepScenes.HolyGrail()) { StripExposure = true }); + Assert.True(light.ExposureValues.All(v => v is null)); + var result = AdvisorApi.Recommend(light, null, sequence); + foreach (var parameter in new[] { AdvisorParameters.HolyGrail, AdvisorParameters.TransitionLength, AdvisorParameters.TargetShutterAngle, AdvisorParameters.MotionBlur }) + { + var missing = result.Find(parameter)!; + Assert.Null(missing.Value); + Assert.Equal(0.0, missing.Confidence); + Assert.Equal(AdvisorKeys.MissingExposure, missing.ReasonKey); + } + + var advised = new ProjectSettings + { + Exposure = new ExposureSettings + { + HolyGrail = new Auto().WithAdvice(true, AdvisorKeys.HolyGrailReceived, "5"), + TransitionLength = new Auto().WithAdvice(20, AdvisorKeys.TransitionSpacing, "40", "20"), + }, + }; + var applied = AdvisorApi.Apply(advised, result); + Assert.Same(advised.Exposure.HolyGrail, applied.Exposure.HolyGrail); + Assert.Same(advised.Exposure.TransitionLength, applied.Exposure.TransitionLength); + Assert.Empty(AdvisorApi.Optimise(AdvisorSection.Exposure, advised, result).Changes.Where(c => c.Parameter is AdvisorParameters.HolyGrail or AdvisorParameters.TransitionLength)); + + // A fresh project keeps its values and learns why there is no advice. + var fresh = AdvisorApi.Apply(new ProjectSettings(), result); + Assert.False(fresh.Exposure.HolyGrail.AutoValue); + Assert.Equal(AdvisorKeys.MissingExposure, fresh.Exposure.HolyGrail.ReasonKey); + Assert.Equal(0, fresh.Exposure.TransitionLength.AutoValue); + Assert.Equal(0.0, fresh.Motion.TargetShutterAngle.AutoValue); + Assert.Equal(AdvisorKeys.MissingExposure, fresh.Motion.TargetShutterAngle.ReasonKey); + } + + [Test] + public async Task ApplyNeverOverwritesManualValues() + { + var (light, sequence) = Inputs(new SyntheticFrameSource(DeepScenes.NightSky())); + var result = AdvisorApi.Recommend(light, await DeepReports.Night, sequence); + var manual = new ProjectSettings + { + Timing = new TimingSettings { FrameRate = new Auto().WithManual("50") }, + Exposure = new ExposureSettings + { + Deflicker = new Auto().WithManual(false), + DeflickerWindow = new Auto().WithManual(99), + }, + HeroFrame = 7, + ExcludedFrames = [3], + }; + var applied = AdvisorApi.Apply(manual, result); + Assert.False(applied.Exposure.Deflicker.IsAuto); + Assert.False(applied.Exposure.Deflicker.Resolve(true)); + Assert.True(applied.Exposure.Deflicker.AutoValue); + Assert.Equal(99, applied.Exposure.DeflickerWindow.Resolve(0)); + Assert.Equal(15, applied.Exposure.DeflickerWindow.AutoValue); + Assert.Equal("50", applied.Timing.FrameRate.Resolve("30")); + Assert.Equal("24", applied.Timing.FrameRate.AutoValue); + Assert.Equal(7, applied.HeroFrame); + Assert.SequenceEqual([3], applied.ExcludedFrames); + // Auto values carry the reason with culture-neutral arguments. + Assert.Equal(AdvisorKeys.WindowMinimum, applied.Exposure.DeflickerWindow.ReasonKey); + Assert.SequenceEqual(["15"], applied.Exposure.DeflickerWindow.ReasonArgs!); + Assert.True(applied.Motion.Stabilize.ReasonKey == AdvisorKeys.StabilizeOff && !applied.Motion.Stabilize.AutoValue); + Assert.Equal(applied.ToJson(), ProjectSettings.FromJson(applied.ToJson()).ToJson()); + } + + [Test] + public async Task OptimiseTakesModuleDecisionsAndReportsChanges() + { + var (light, sequence) = Inputs(new SyntheticFrameSource(DeepScenes.NightSky(jitter: 2), 2)); + var result = AdvisorApi.Recommend(light, await DeepReports.NightJitter, sequence); + var settings = new ProjectSettings + { + Motion = new MotionSettings { Stabilize = new Auto().WithManual(false), StabilizeSmoothing = new Auto().WithManual(30) }, + ExcludedFrames = [3], + }; + + var motion = AdvisorApi.Optimise(AdvisorSection.Motion, settings, result); + Assert.True(motion.Settings.Motion.Stabilize.IsAuto); + Assert.True(motion.Settings.Motion.Stabilize.Resolve(false)); + Assert.Equal(30.0, motion.Settings.Motion.StabilizeSmoothing.Resolve(12)); + var change = motion.Changes.Single(c => c.Parameter == AdvisorParameters.Stabilize); + Assert.Equal(false, change.Before); + Assert.Equal(true, change.After); + Assert.Equal(AdvisorKeys.StabilizeOn, change.ReasonKey); + Assert.DoesNotContain(AdvisorParameters.StabilizeSmoothing, motion.Changes.Select(c => c.Parameter)); + Assert.Null(motion.Settings.HeroFrame); + + var frames = AdvisorApi.Optimise(AdvisorSection.Frames, settings, result); + Assert.Equal(result.Find(AdvisorParameters.Hero)!.Value, frames.Settings.HeroFrame); + Assert.SequenceEqual([AdvisorParameters.Hero], frames.Changes.Select(c => c.Parameter)); + Assert.SequenceEqual([3], frames.Settings.ExcludedFrames); + + var exposure = AdvisorApi.Optimise(AdvisorSection.Exposure, settings, result); + var deflicker = exposure.Changes.Single(c => c.Parameter == AdvisorParameters.Deflicker); + Assert.Null(deflicker.Before); + Assert.Equal(true, deflicker.After); + Assert.Equal(settings.Motion, exposure.Settings.Motion); + + // Optimising again changes nothing. + Assert.Empty(AdvisorApi.Optimise(AdvisorSection.Motion, motion.Settings, result).Changes); + } + + [Test] + public async Task OptimiseExcludesFlaggedFramesAndCapsTheOutput() + { + var source = new SyntheticFrameSource(SyntheticSequence.Create(new SyntheticSequenceOptions + { + Width = 96, Height = 64, FrameCount = 40, FlickerEv = 0.05, BlackFrames = [5], DuplicateFrames = [9], + })); + var deep = await DeepAnalyzer.AnalyzeAsync(source, DeepScenes.Options); + var (light, sequence) = Inputs(source); + var result = AdvisorApi.Recommend(light, deep, sequence with { PreviewOnlyCount = 12, PreviewWidth = 1620, PreviewHeight = 1080 }); + + var frames = AdvisorApi.Optimise(AdvisorSection.Frames, new ProjectSettings { ExcludedFrames = [2] }, result); + Assert.SequenceEqual([2, 5, 9], frames.Settings.ExcludedFrames); + Assert.Equal(AdvisorKeys.Exclude, frames.Changes.Single(c => c.Parameter == AdvisorParameters.Excluded).ReasonKey); + + var resolution = result.Find(AdvisorParameters.Resolution)!; + Assert.Equal("1280x720", resolution.Value); + Assert.Equal(AdvisorKeys.ResolutionPreview, resolution.ReasonKey); + var big = new ProjectSettings { Export = new ExportSettings { Preset = new Auto().WithManual("4k-hevc") } }; + var export = AdvisorApi.Optimise(AdvisorSection.Export, big, result); + Assert.Equal("720p-preview", export.Settings.Export.Preset.Resolve("4k-hevc")); + Assert.Null(export.Settings.Export.Overrides.Width); + } + + [Test] + public void OutputSizeFollowsSourceShapeAndEncoders() + { + var (light, sequence) = Inputs(new SyntheticFrameSource(DeepScenes.HolyGrail())); + var h264Only = sequence with { Codecs = [new EncoderCapability(VideoCodec.H264, "Software H.264", false, 1920, 1088, false)] }; + var limited = AdvisorApi.Recommend(light, null, h264Only); + Assert.Equal("1920x1080", Value(limited, AdvisorParameters.Resolution)); + Assert.Equal(AdvisorKeys.ResolutionCodec, limited.Find(AdvisorParameters.Resolution)!.ReasonKey); + Assert.Equal("1080p-h264", Value(limited, AdvisorParameters.ExportPreset)); + + var portrait = AdvisorApi.Recommend(light, null, sequence with { SourceWidth = 4000, SourceHeight = 6000 }); + Assert.Equal("9:16", Value(portrait, AdvisorParameters.Aspect)); + Assert.Equal("1080x1920", Value(portrait, AdvisorParameters.Resolution)); + Assert.Equal("vertical-1080x1920", Value(portrait, AdvisorParameters.ExportPreset)); + + var landscape = AdvisorApi.Recommend(light, null, sequence); + Assert.Equal("16:9", Value(landscape, AdvisorParameters.Aspect)); + Assert.SequenceEqual([6000.0, 4000.0, 84.0], landscape.Find(AdvisorParameters.Aspect)!.ReasonArgs.Select(Convert.ToDouble)); + + var wide = AdvisorApi.Recommend(light, null, sequence with { SourceWidth = 6000, SourceHeight = 2500 }); + Assert.Equal(AdvisorKeys.AspectWide, wide.Find(AdvisorParameters.Aspect)!.ReasonKey); + Assert.Equal(74.0, wide.Find(AdvisorParameters.Aspect)!.ReasonArgs[2]); + Assert.Equal("3840x2160", Value(wide, AdvisorParameters.Resolution)); + } + + [Test] + public async Task RecommendationsAreDeterministic() + { + var (light, sequence) = Inputs(new SyntheticFrameSource(DeepScenes.NightSky())); + var deep = await DeepReports.Night; + var first = AdvisorApi.Recommend(light, deep, sequence); + var second = AdvisorApi.Recommend(light, DeepAnalysisReport.FromJson(deep.ToJson()), sequence); + Assert.SequenceEqual(first.Recommendations.Select(Describe), second.Recommendations.Select(Describe)); + } + + private static (LightAnalysisReport Light, SequenceContext Context) Inputs(SyntheticFrameSource source, int width = 6000, int height = 4000) + { + var frames = Enumerable.Range(0, source.Count).Select(source.Metadata).ToList(); + var exposures = frames.Where(f => f.ExposureTime is > 0).Select(f => f.ExposureTime!.Value).ToArray(); + return (LightAnalyzer.Analyze(frames), new SequenceContext + { + FrameCount = frames.Count, + SourceWidth = width, + SourceHeight = height, + MedianExposureSeconds = exposures.Length > 0 ? Statistics.Median(exposures) : null, + }); + } + + private static object? Value(AdvisorResult result, string parameter) => (result.Find(parameter) ?? throw new InvalidOperationException(parameter + " not recommended")).Value; + + private static string Describe(Recommendation r) => + $"{r.Parameter}={(r.Value is int[] list ? string.Join(",", list) : r.Value)} {r.Confidence} {r.ReasonKey} [{string.Join(";", r.ReasonArgs)}]"; + + private void Log(AdvisorResult result) + { + foreach (var r in result.Recommendations) context.Log(Describe(r)); + } +}