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 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_012iLMBNwBE2GnphAsu4cjaC
This commit is contained in:
Claude committed 2026-10-02 10:52:08 +00:00
1 parent 727b5cb488
commit d8d25f1877
8 files changed
+1707

No files matched your search

+91
View File
@@ -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;
/// <summary>
/// The analysis advisor (BRIEF §10.3, §10.4): turns the light and deep analyses into explained recommendations
/// (<see cref="Recommend"/>), stores them as Auto values without touching manual ones (<see cref="Apply"/>), and takes
/// the heavier per-section decisions on request (<see cref="Optimise"/>). Deterministic; every reason is a resource
/// key plus arguments.
/// </summary>
public static class Advisor
{
/// <summary>
/// Recommendations for every parameter the rules cover (see <see cref="AdvisorRules"/>), in section order, plus
/// every finding of both analyses. Without a deep report, pixel-based parameters get missing-data recommendations.
/// </summary>
public static AdvisorResult Recommend(LightAnalysisReport light, DeepAnalysisReport? deep, SequenceContext context)
{
ArgumentNullException.ThrowIfNull(light);
ArgumentNullException.ThrowIfNull(context);
var findings = new List<Finding>(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);
}
/// <summary>
/// Fills <see cref="Auto{T}.AutoValue"/>, <see cref="Auto{T}.ReasonKey"/> and <see cref="Auto{T}.ReasonArgs"/> 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 <see cref="Optimise"/>.
/// </summary>
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;
}
/// <summary>
/// "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.
/// </summary>
public static OptimiseResult Optimise(AdvisorSection section, ProjectSettings settings, AdvisorResult result)
{
ArgumentNullException.ThrowIfNull(settings);
ArgumentNullException.ThrowIfNull(result);
var optimised = settings;
var changes = new List<SettingChange>();
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);
}
/// <summary>Localised text of a recommendation in the current UI culture.</summary>
public static string Explain(Recommendation recommendation)
{
ArgumentNullException.ThrowIfNull(recommendation);
return Loc.L(recommendation.ReasonKey, [.. recommendation.ReasonArgs]);
}
/// <summary>
/// Localised text of a stored reason (<see cref="Auto{T}.ReasonKey"/>/<see cref="Auto{T}.ReasonArgs"/>): numeric
/// arguments, stored culture-neutral, are parsed back so they format with the current culture.
/// </summary>
public static string Explain(string reasonKey, IReadOnlyList<string>? 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);
}
}
+97
View File
@@ -0,0 +1,97 @@
namespace Titano.Core.Advisor;
/// <summary>
/// Resource keys (area <c>Advisor</c>) of the advisor's reasons, missing-data notes and sequence presets. Each key is
/// written through <c>LocKey(…)</c> so <c>Titano.Tools i18n check</c> verifies it exists in every required culture;
/// the resx comment of each key says what its placeholders hold.
/// </summary>
public static class AdvisorKeys
{
/// <summary>Every missing-data key starts with this; such a reason never carries a value.</summary>
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");
/// <summary>Identity function that marks a literal as a resource key for the i18n check.</summary>
private static string LocKey(string key) => key;
}
+507
View File
@@ -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;
/// <summary>
/// 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
/// <see cref="AdvisorKeys.MissingPrefix"/> reason.
/// </summary>
internal sealed class AdvisorRules
{
/// <summary>Visible shake threshold in output pixels (BRIEF §10.3).</summary>
public const double ShakeThresholdPx = 0.3;
/// <summary>Film-look target shutter angle in degrees.</summary>
public const double TargetShutterAngle = 180;
/// <summary>Path smoothing σ in frames (as <c>StabilizerOptions.SmoothingSigma</c>).</summary>
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<Recommendation> _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<Recommendation> Run()
{
Export();
Frames();
Timing();
Exposure();
Motion();
Camera();
return [.. _result.OrderBy(r => r.Section)];
}
/// <summary>Converts deep-analysis pixels (source resolution) to output pixels.</summary>
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);
/// <summary>
/// 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.
/// </summary>
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);
}
/// <summary>Presets for one output size in order of preference, with the reason each one carries.</summary>
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);
}
/// <summary>Whether an encoder for <paramref name="codec"/> handles the size (either orientation); with no
/// capability list everything fits. <paramref name="largest"/> is the codec's largest capability, if any.</summary>
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));
}
/// <summary>Hero frame from the deep analysis; exclusion of undecodable, black, white and duplicate frames.</summary>
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);
}
/// <summary>
/// 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.
/// </summary>
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));
}
/// <summary>
/// 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.
/// </summary>
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);
}
/// <summary>
/// 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.
/// </summary>
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);
}
/// <summary>
/// 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).
/// </summary>
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));
}
/// <summary>Night content: a star field, or a sequence the deep analysis or GPS phases call night.</summary>
private bool IsNightSky() => _deep is { } d && (d.Sky.StarField || d.Sky.Light == DayNight.Night);
/// <summary>Speed of moving content as a fraction of the frame's long edge per frame; null without motion data.</summary>
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;
}
}
+177
View File
@@ -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;
/// <summary>Sequence-editor section a recommendation belongs to (BRIEF §12.3).</summary>
public enum AdvisorSection
{
Frames,
Timing,
Exposure,
Motion,
Camera,
/// <summary>No automatic advice: a temporal median erases stars that move between frames, so stacking stays a user choice.</summary>
Stack,
Export,
}
/// <summary>
/// Stable ids of the parameters the advisor decides, named after their <see cref="ProjectSettings"/> path.
/// Value types: see each constant.
/// </summary>
public static class AdvisorParameters
{
/// <summary><see cref="int"/> frame index.</summary>
public const string Hero = "Frames.Hero";
/// <summary><see cref="int"/>[] frame indices to exclude.</summary>
public const string Excluded = "Frames.Excluded";
/// <summary><see cref="Project.TimingMode"/>.</summary>
public const string TimingMode = "Timing.Mode";
/// <summary><see cref="string"/> frame rate ("24", "25", "30", "60").</summary>
public const string FrameRate = "Timing.FrameRate";
/// <summary><see cref="double"/> seconds.</summary>
public const string FitToSeconds = "Timing.FitToSeconds";
/// <summary><see cref="bool"/>.</summary>
public const string Deflicker = "Exposure.Deflicker";
/// <summary><see cref="int"/> frames (odd).</summary>
public const string DeflickerWindow = "Exposure.DeflickerWindow";
/// <summary><see cref="double"/> 0..1.</summary>
public const string DeflickerStrength = "Exposure.DeflickerStrength";
/// <summary><see cref="RegionMode"/>.</summary>
public const string Regions = "Exposure.Regions";
/// <summary><see cref="bool"/>.</summary>
public const string HolyGrail = "Exposure.HolyGrail";
/// <summary><see cref="int"/> frames.</summary>
public const string TransitionLength = "Exposure.TransitionLength";
/// <summary><see cref="bool"/>.</summary>
public const string WhiteBalanceSmoothing = "Exposure.WhiteBalanceSmoothing";
/// <summary><see cref="bool"/>.</summary>
public const string MotionBlur = "Motion.MotionBlur";
/// <summary><see cref="double"/> degrees.</summary>
public const string TargetShutterAngle = "Motion.TargetShutterAngle";
/// <summary><see cref="FlowQualitySetting"/>.</summary>
public const string FlowQuality = "Motion.FlowQuality";
/// <summary><see cref="bool"/>.</summary>
public const string Stabilize = "Motion.Stabilize";
/// <summary><see cref="double"/> σ in frames.</summary>
public const string StabilizeSmoothing = "Motion.StabilizeSmoothing";
/// <summary><see cref="string"/> aspect ("16:9", "9:16", …).</summary>
public const string Aspect = "Camera.Aspect";
/// <summary><see cref="double"/> crop placement −1..1 (0 = centred).</summary>
public const string OffsetY = "Camera.OffsetY";
/// <summary><see cref="string"/> built-in export preset id.</summary>
public const string ExportPreset = "Export.Preset";
/// <summary><see cref="string"/> output size "WxH" (the cap from source, previews and encoder).</summary>
public const string Resolution = "Export.Resolution";
}
/// <summary>
/// One advisor decision (BRIEF §10.3). <see cref="Value"/> is null when data is missing; the reason then says what is
/// missing and nothing is changed. <see cref="ReasonArgs"/> are numbers (already rounded for display) or plain tokens,
/// formatted by the caller with its culture: <c>Loc.L(ReasonKey, [.. ReasonArgs])</c>.
/// </summary>
/// <param name="Confidence">0..1: how strongly the measurements support the value.</param>
public sealed record Recommendation(
AdvisorSection Section,
string Parameter,
object? Value,
double Confidence,
string ReasonKey,
IReadOnlyList<object> ReasonArgs)
{
public bool IsMissingData => Value is null;
}
/// <summary>Output of <see cref="Advisor.Recommend"/>: recommendations in section order plus every finding.</summary>
public sealed record AdvisorResult(IReadOnlyList<Recommendation> Recommendations, IReadOnlyList<Finding> Findings)
{
public Recommendation? Find(string parameter) => Recommendations.FirstOrDefault(r => r.Parameter == parameter);
public IEnumerable<Recommendation> In(AdvisorSection section) => Recommendations.Where(r => r.Section == section);
}
/// <summary>What the advisor knows about the sequence besides the analyses.</summary>
public sealed record SequenceContext
{
public int FrameCount { get; init; }
/// <summary>Oriented full-resolution size (0 = take the light analysis' dominant size).</summary>
public int SourceWidth { get; init; }
public int SourceHeight { get; init; }
/// <summary>Frames that decode only through their embedded preview (BRIEF §8.2 tier 2).</summary>
public int PreviewOnlyCount { get; init; }
/// <summary>Oriented size of those embedded previews (0 = unknown).</summary>
public int PreviewWidth { get; init; }
public int PreviewHeight { get; init; }
/// <summary>Median shutter time in seconds, for the real shutter angle.</summary>
public double? MedianExposureSeconds { get; init; }
/// <summary>Encoders available on the rendering machine; empty = unknown (no codec is ruled out).</summary>
public IReadOnlyList<EncoderCapability> Codecs { get; init; } = [];
/// <summary>Wanted video length ("fit to N seconds"), when the user set one.</summary>
public double? TargetDurationSeconds { get; init; }
/// <summary>Context from the archive's frame rows: count, dominant oriented size, preview-only count, median shutter time.</summary>
public static SequenceContext FromFrames(IReadOnlyList<Frame> frames, IReadOnlyList<EncoderCapability>? codecs = null)
{
ArgumentNullException.ThrowIfNull(frames);
var sizes = new Dictionary<(int, int), int>();
var exposures = new List<double>();
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 ?? [],
};
}
}
/// <summary>A value <see cref="Advisor.Optimise"/> changed: effective value before and after, and why.</summary>
public sealed record SettingChange(string Parameter, object? Before, object? After, string ReasonKey, IReadOnlyList<object> ReasonArgs);
/// <summary>Settings after <see cref="Advisor.Optimise"/> and the report of what changed.</summary>
public sealed record OptimiseResult(ProjectSettings Settings, IReadOnlyList<SettingChange> Changes);
@@ -0,0 +1,137 @@
using System.Collections;
using System.Globalization;
using Titano.Core.Export;
using Titano.Core.Project;
namespace Titano.Core.Advisor;
/// <summary>How one advisor parameter reads and writes <see cref="ProjectSettings"/>.</summary>
internal sealed class ParameterBinding
{
public required string Parameter { get; init; }
public required AdvisorSection Section { get; init; }
/// <summary>A module on/off decision: <see cref="Advisor.Optimise"/> returns it to Auto when the advice differs.</summary>
public bool IsModuleSwitch { get; init; }
/// <summary>The value in force (manual, else advised), null when neither exists.</summary>
public required Func<ProjectSettings, object?> Effective { get; init; }
/// <summary>Auto fields: stores the advice and its reason, never touching a manual value.</summary>
public Func<ProjectSettings, Recommendation, ProjectSettings>? Advise { get; init; }
/// <summary>Auto fields: drops the manual value so the advice applies.</summary>
public Func<ProjectSettings, ProjectSettings>? ResetToAuto { get; init; }
/// <summary>Plain fields: the heavier decision <see cref="Advisor.Optimise"/> takes (each guards user choices).</summary>
public Func<ProjectSettings, Recommendation, ProjectSettings>? Set { get; init; }
}
/// <summary>The binding of every <see cref="AdvisorParameters"/> id, in section order.</summary>
internal static class ParameterBindings
{
public static IReadOnlyList<ParameterBinding> 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);
/// <summary>Value equality that compares lists element by element.</summary>
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<object>().SequenceEqual(y.Cast<object>());
return Equals(a, b);
}
/// <summary>Recommendation arguments as stored in <see cref="Auto{T}.ReasonArgs"/> (culture-neutral text).</summary>
public static string[] Strings(IReadOnlyList<object> 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<T>(Auto<T> 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<T>(string parameter, AdvisorSection section, bool module, Func<ProjectSettings, Auto<T>> get, Func<ProjectSettings, Auto<T>, 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<T>(Auto<T> auto) => !auto.IsAuto && auto.Manual is not null ? auto.Manual : HasAdvice(auto) ? auto.AutoValue : null;
/// <summary>
/// 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.
/// </summary>
private static Auto<T> Advise<T>(Auto<T> 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);
}
/// <summary>Overrides the output size when the preset in force is larger than the recommended cap.</summary>
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 } } };
}
}
+217
View File
@@ -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;
/// <summary>
/// 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 <see cref="Name"/>.
/// </summary>
public sealed record SequencePreset
{
/// <summary>"night-sky", "holy-grail", "construction", "social-vertical", "standard", or a user id.</summary>
public required string Id { get; init; }
public required string NameKey { get; init; }
public IReadOnlyList<string> NameArgs { get; init; } = [];
/// <summary>The user's name for a saved preset; overrides <see cref="NameKey"/>.</summary>
public string? Name { get; init; }
public string? ReasonKey { get; init; }
public IReadOnlyList<string> ReasonArgs { get; init; } = [];
public required ProjectSettings Settings { get; init; }
public required string ExportPresetId { get; init; }
/// <summary>0..1: how well the measured content matches the preset.</summary>
public double Confidence { get; init; }
public bool IsUser { get; init; }
public string DisplayName() => Name ?? Advisor.Explain(NameKey, NameArgs);
/// <summary>A copy saved under the user's name.</summary>
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.");
}
/// <summary>
/// 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.
/// </summary>
public static class SequencePresets
{
public static IReadOnlyList<SequencePreset> 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<SequencePreset>();
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)];
}
/// <summary>The preset's own export choice when the advised size reaches 4K, else the advised (capped) preset.</summary>
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;
}
/// <summary>Export preset and (optionally) frame rate as the preset's manual choices.</summary>
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) } };
}
/// <summary>Resolution label of an export preset ("4K", "1440p", "1080p", …).</summary>
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,
};
/// <summary>Codec label of an export preset ("HEVC Main10", "HEVC", "H.264", "AV1"): technical names, not translated.</summary>
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>(T value) => Convert.ToString(value, CultureInfo.InvariantCulture) ?? string.Empty;
}
/// <summary>Source-generated JSON for saved sequence presets.</summary>
[JsonSourceGenerationOptions(
WriteIndented = true,
PropertyNamingPolicy = JsonKnownNamingPolicy.CamelCase,
DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingNull,
UseStringEnumConverter = true,
PropertyNameCaseInsensitive = true)]
[JsonSerializable(typeof(SequencePreset))]
internal sealed partial class AdvisorJson : JsonSerializerContext;
@@ -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<string, string> Entries(ResourceSet set)
{
var entries = new Dictionary<string, string>(StringComparer.Ordinal);
foreach (DictionaryEntry entry in set) entries[(string)entry.Key] = (string)entry.Value!;
return entries;
}
private static IEnumerable<string> 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<string> Placeholders(string text) => PlaceholderRegex().Matches(text).Select(m => m.Groups[1].Value).Order();
[GeneratedRegex(@"\{(\d+)(?:[,:][^}]*)?\}")]
private static partial Regex PlaceholderRegex();
}
@@ -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<int>());
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<bool>().WithAdvice(true, AdvisorKeys.HolyGrailReceived, "5"),
TransitionLength = new Auto<int>().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<string>().WithManual("50") },
Exposure = new ExposureSettings
{
Deflicker = new Auto<bool>().WithManual(false),
DeflickerWindow = new Auto<int>().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<bool>().WithManual(false), StabilizeSmoothing = new Auto<double>().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<string>().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));
}
}